repository·main·Indexed 11 days ago
https://github.com/mas-cli/masA command-line interface for the Mac App Store designed for scripting and automation. It allows developers to search, install, update, and manage Mac App Store applications via the terminal using ADAM IDs or Bundle IDs. Features include JSON output for programmatic access, integration with Homebrew Bundle and Topgrade, and tools for managing app updates with configurable accuracy modes.
The mas CLI can be integrated with other automation tools:
mas to include installed apps in a Brewfile. You can then use brew bundle to get, install, and update apps listed in the Brewfile.topgrade to automate the updating of your apps via mas.Commands that modify the system (get, install, lucky, update, uninstall) require root privileges. mas will request them via sudo as necessary. It uses existing valid sudo credentials or prompts for the macOS user password. The password is never stored by mas.
Commands that interact with the App Store (get, install, lucky, update, and outdated --accurate) require an Apple Account to be signed in to the App Store.
Authentication behavior depends on System Settings:
Always Require: Authentication required for every app.Never Require: Apps are processed without additional authentication.When running outdated or update, you can control how mas determines if an app needs an update using two main concepts: Minimum macOS Check and Accuracy.
--check-min-os (default): Only reports apps as outdated if the latest version is compatible with your current macOS.--no-check-min-os: Reports an app as outdated even if the latest version is incompatible with your current macOS. This prevents false negatives but may cause false positives.Select between these two mutually exclusive modes:
| Flag | Method | Pros | Cons |
|---|---|---|---|
--inaccurate (default) | Queries iTunes Search API | Fast (~7ms/app), no hangs, no dialogs | Potential false positives/negatives due to API lag or inconsistent version reporting |
--accurate | Initiates a metadata download | 100% accurate | Slow (~175ms/app), can hang if checking 100+ apps, requires Apple Account, may show dialogs |
Note on --accurate: In outdated mode, the download is immediately cancelled after reading metadata. In update mode, the download is only cancelled if the version matches the installed version; otherwise, the update proceeds.
# Check for outdated apps accurately
mas outdated --accurateApp Store apps are identified by two unique types of IDs. mas commands accept both as arguments:
497799835). By default, mas treats all-digit arguments as ADAM IDs.com.apple.dt.Xcode).To force an all-digit ID to be treated as a Bundle ID, use the --bundle flag.
How to find an ADAM ID:
mas search <term> or mas list.https://apps.apple.com/us/app/xcode/id497799835?mt=12, the ID is 497799835).# Example: Using a Bundle ID explicitly if it looks like an ADAM ID
mas install --bundle 123456789You can install mas using several package managers depending on your macOS version and preference:
brew install masbrew install mas-cli/tap/massudo port install mas# Using Homebrew Core
brew install mas
# Using Homebrew Tap
brew install mas-cli/tap/mas
# Using MacPorts
sudo port install masThe mas command-line interface provides a way to interact with the Mac App Store from the terminal. It supports a wide range of subcommands for managing applications, including installation, updates, searching, and configuration.
To see the full list of available commands, run mas --help.
# Example: list installed apps
mas list
# Example: search for an app
mas search "Xcode"Commands like list, outdated, get, install, lucky, update, and uninstall rely on the Spotlight Metadata Service (MDS) to find installed apps. If an app is not appearing in mas results, it may not be indexed in Spotlight.
1. Verify if an app is indexed:
Use mdls to check for the kMDItemAppStoreAdamID attribute:
mdls -rn kMDItemAppStoreAdamID /Applications/Xcode.appIf it outputs nothing, the app is not indexed.
2. Find an app path via ADAM ID:
mdfind 'kMDItemAppStoreAdamID = <adam-id>'3. Fix indexing:
mdimport /Applications/Xcode.appvol="$(/usr/libexec/PlistBuddy -c "Print :PreferredVolume:name" ~/Library/Preferences/com.apple.appstored.plist 2>/dev/null)"
mdimport /Applications "${vol:+"/Volumes/${vol}/Applications"}"sudo mdutil -Eai on# Check if Xcode is indexed
mdls -rn kMDItemAppStoreAdamID /Applications/Xcode.appCommon issues and their solutions:
mas does not manage system software. Use the softwareupdate command instead.The mas CLI provides a variety of commands for interacting with the Mac App Store. For detailed documentation, use man mas or mas --help in your terminal.
| Command | Functionality | Aliases |
search <term>… | Search for App Store apps
lookup <id>… | Output App Store app details | info
list [<id>…] | Output installed apps
outdated [<id>…] | Output outdated apps
outdated --accurate [<id>…] | Output outdated apps
get <id>… | Get free apps, install any apps | purchase
install <id>… | Install gotten or purchased apps
lucky <term>… | Install first matching app
update [<id>…] | Update outdated apps | upgrade
update --accurate [<id>…] | Update outdated apps | upgrade
uninstall (<id>…|--all) | Uninstall apps
signout | Sign out from App Store
open [<id>] | Open app App Store page
home <id>… | Open app web pages
seller <id>… | Open seller app web pages | vendor
reset | Reset App Store processes
config | Output config
version | Output versionBy default, mas commands output tabular data or key-value pairs. To use mas in scripts or for programmatic access, use the --json flag to output a stream of JSON objects.
list, outdated, & search: Output a stream of JSON objects (one per app) containing all fields provided by Apple. Keys are mapped to more readable names and are sorted numerically.config: Outputs all settings in a single JSON object.lookup: When --json is supplied, it outputs a JSON object for the app.# Example: List outdated apps in JSON format
mas outdated --jsonIf mas list returns no results but you know apps are installed, you may need to re-index your applications using Spotlight (mdimport).
To index a specific app (e.g., Xcode):
mdimport /Applications/Xcode.appTo index all applications on your main volume:
vol="$(/usr/libexec/PlistBuddy -c "Print :PreferredVolume:name" ~/Library/Preferences/com.apple.appstored.plist 2>/dev/null)"
mdimport /Applications ${vol:+"/Volumes/${vol}/Applications"}To ensure Spotlight indexing is enabled for all volumes:
sudo mdutil -Eai on# Example: Indexing a specific app
mdimport /Applications/Xcode.appWhen requested in JSON format, the mas config command returns an object containing the following keys:
| Key | Description |
|---|---|
mas | The version of mas |
slice | The architecture of the currently running slice |
slices | A space-separated list of supported slice architectures |
dist | The distribution |
origin | The git origin |
rev | The git revision |
swift | The Swift version |
driver | The Swift driver version |
store | The App Store region |
region | The macOS region |
macos | The macOS version (major.minor.patch) |
build | The macOS build version (from kern.osversion) |
mac | The hardware product name (from hw.product) |
cpu | The CPU brand string (from machdep.cpu.brand_string) |
arch | The hardware machine architecture (from hw.machine) |
{
"mas": "7.0.0",
"slice": "arm64",
"slices": "arm64 x86_64",
"dist": "...",
"origin": "...",
"rev": "...",
"swift": "...",
"driver": "...",
"store": "...",
"region": "...",
"macos": "14.4.0",
"build": "...",
"mac": "...",
"cpu": "...",
"arch": "arm64"
}