A look at mas-cli/mas: 12.4k stars on GitHub, written primarily in Swift. :package: Mac App Store command-line interface
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
mas is a command-line interface for the Mac App Store designed for scripting &
automation.
Installation
Provider
Method
mas
macOS
Homebrew Core
brew install mas
14+ (recommended)
Homebrew Tap
brew install mas-cli/tap/mas
13+
MacPorts
sudo port install mas
13+
Nix Nixpkgs unstable
nix-shell -p mas
14+
Nix Nixpkgs stable
nix-shell -p mas
14+
GitHub Releases
Installers & source archives
All
Release-dependent
Commands
Detailed documentation is available via man mas & mas --help.
Command
Functionality
Notes
Aliases
search <term>…
Search for App Store apps
json
lookup <id>…
Output App Store app details
json
info
list [<id>…]
Output installed apps
spotlight, json
outdated [<id>…]
Output outdated apps
spotlight, json
outdated --accurate [<id>…]
Output outdated apps
spotlight, account, json
get <id>…
Get free apps, install any apps
spotlight, root, account
purchase
install <id>…
Install gotten or purchased apps
spotlight, root, account
lucky <term>…
Install first matching app
spotlight, root, account
update [<id>…]
Update outdated apps
spotlight, root, account
upgrade
update --accurate [<id>…]
Update outdated apps
spotlight, root, account
upgrade
uninstall (<id>…|--all)
Uninstall apps
spotlight, root
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
json
version
Output version
Integrations
Tool
Functionality
Homebrew Bundle
Include installed apps in Brewfile; get, install & update Brewfile apps
Topgrade
Update apps
Known Issues
Issue
Solution
Manage system software (macOS, Safari…)
Use softwareupdate
Inconsistent app data
Wait hours – days (the App Store uses eventual consistency)
Cannot purchase paid apps
Purchase paid apps directly in the App Store; submit a PR
iOS & iPadOS apps are unsupported
Submit a PR
Hangs
Index apps in Spotlight; open a bug report if hangs persist
Undetected installed apps
Index apps in Spotlight
This redownload is not available for this Apple Account… error
Sign in the correct Apple Account to the App Store, or uninstall the app & get it with the current Apple Account
Other bugs
Subscribe to an existing, or open a new, bug report
Development
Action
Command
Build
Scripts/build or Xcode 26.4+
Set up zsh wrapper
Scripts/setup_libexec
Run zsh wrapper
Scripts/mas
Test (Swift Testing)
Scripts/test
App IDs
App Store apps each have 2 unique IDs:
Type
Format
Example (for Xcode)
ADAM ID
Integer
497799835
Bundle ID
String
com.apple.dt.Xcode
mas commands accept both types of app IDs as arguments.
By default, all-digit app IDs are considered ADAM IDs; other app IDs are
considered bundle IDs.
--bundle forces all-digit app IDs to also be considered bundle IDs.
ADAM IDs can be found via:
mas search <term>…
mas list
The App Store:
Open an app's App Store page.
Open the page's Share Sheet.
Choose Copy.
Extract the ADAM ID from the URL in the copied text. e.g., 497799835 from
https://apps.apple.com/us/app/xcode/id497799835?mt=12.
JSON App Output
list, outdated & search normally output tabular data, with a few fields
for each app on its own row.
lookup normally outputs fields as key-value pairs—one per line—in a contiguous
block for each app, with a blank line between apps.
If --json is supplied, these commands output a stream of JSON objects—one per
app—each containing all fields provided by Apple for that app.
Many of the keys provided by Apple are poorly named, so they are mapped to
better names by an algorithm.
Mapped keys are sorted.
Each key should be unique within an object; if duplicate keys exist in an
object, their relative ordering in the input is preserved in the output.
For tabular output, if an object contains duplicate keys, the last value is
used.
If Apple renames or adds keys, suboptimal keys might be output until the mapping
is updated.
JSON Config Output
config normally outputs settings as key-value pairs, one per line.
If --json is supplied, config outputs all settings in a single JSON object.
Since the keys are defined by mas, they are guaranteed to be unique & correct.
Spotlight
list, outdated, get, install, lucky, update & uninstall obtain
data for installed apps from the Spotlight Metadata Service (MDS).
Spotlight indexing thus must be enabled & valid for folders containing App Store
apps.
Check if an app is properly indexed in Spotlight via:
## General format:
$ mdls -rn kMDItemAppStoreAdamID <path-to-app>
## Outputs the ADAM ID if the app is indexed.
## Outputs nothing if the app is not indexed.
## Example:
$ mdls -rn kMDItemAppStoreAdamID /Applications/Xcode.app
497799835
If an app is indexed in Spotlight, find the path to the app from its ADAM ID
via:
mdfind 'kMDItemAppStoreAdamID = <adam-id>'
If any App Store apps are not properly indexed, index via:
# Individual app (if the omitted apps are known). e.g., for Xcode:
mdimport /Applications/Xcode.app
# All apps:
vol="$(/usr/libexec/PlistBuddy -c "Print :PreferredVolume:name" ~/Library/Preferences/com.apple.appstored.plist 2>/dev/null)"
mdimport /Applications ${vol:+"/Volumes/${vol}/Applications"}
# All volumes:
sudo mdutil -Eai on
If run without root privileges, mas requests them as necessary.
mas uses existing valid sudo credentials, falling back to prompting for the
macOS user password, which is piped directly to a sudo process; the password is
never visible to, nor stored by, mas.
Any sudo credentials used or established by mas remain valid after mas finishes,
pursuant to the user-configured sudo timeout.
App Store Apple Account Requirements
get, install, lucky, update & outdated --accurate require an Apple
Account signed in to the App Store.
App Store Apple Account Requirements for get
get requires an Apple Account signed in to the App Store.
Even when an Apple Account is already signed in to the App Store, the system
security settings might require authenticating the Apple Account for each app
being gotten.
If System Settings > Touch ID & Password > Use Touch ID for purchases in iTunes Store, App Store and Apple Books is:
Enabled: You must authenticate (via Touch ID or Apple Account password) for
each app being gotten.
Disabled: If System Settings > Apple Account > Media & Purchases >
Free Downloads is:
Always Require: You must authenticate (via Apple Account password) for
each app being gotten.
Never Require: Apps are gotten without additional authentication.
Note: App Store authentication is separate from any macOS user
authentication required to grant root privileges to get apps.
Outdated-App Detection
In outdated & update, the determination of whether an app is outdated is
configurable via 2 settings:
Minimum macOS Check
Accuracy
Concepts & Constraints
A release is a build of an app distributed to users.
A version is a label that orders a release relative to all other releases of
the same app.
The iTunes Search API
reports app data only for the latest release of which it is aware; eventual
consistency delays can prevent the API from knowing about the latest release
available from the App Store.
Minimum macOS Check
--check-min-os (default): Filters outdated apps to include only those for
which the release reported by the
iTunes Search API is
compatible with your current macOS.
--no-check-min-os: Does not filter outdated apps. This is useful only when
multiple newer releases are available, with some compatible with your current
macOS, but the latest incompatible. With this setting, an app whose latest
release is newer than the installed release but incompatible with your current
macOS will:
outdated: Be reported as outdated, which avoids false negatives, but could
cause false positives.
update: Display a dialog offering to install the newest release compatible
with your current macOS, which might be the installed, or a newer (but not
the latest), release.
Accuracy
The 2 outdated-app-detection modes are selectable via mutually exclusive flags:
Feature
--inaccurate (default)
--accurate
Method
Query the iTunes Search API
Initiate App Store download to read metadata
Accuracy
Potential false positives or negatives
No false positives or negatives
Speed
Fast (~7ms per app)
Slow (~175ms per app)
Requirements
iTunes Search API
Apple Account signed in to the App Store
Dialogs
Only if --no-check-min-os
Various potential dialogs
Hangs
None
If checking 100+ apps in quick succession
--inaccurate (default)
The inaccurate mode is optimized to:
Be fast.
Avoid hangs.
Avoid dialogs (as long as --no-check-min-os is not supplied).
Report outdated apps owned by any Apple Account without requiring an Apple
Account signed in to the App Store (apps can be updated, however, only for an
Apple Account signed in to the App Store).
It compares an installed app's version with the version reported by the
iTunes Search API as
Semantic Versions, with build metadata adjudicating ties.
This mode suffers from potential false positives & negatives:
Inconsistent versions: For certain apps, the iTunes Search API
consistently reports a different version for the same release than is reported
by all other App Store systems & by installed apps, causing false positives or
negatives.
Eventual consistency delays: Lags between the App Store & the iTunes
Search API can cause false negatives.
--accurate
The accurate mode is optimized to avoid false positives & negatives at the
expense of speed, potential hangs & potential dialogs.
It initiates a download of an installed app's latest release from the App Store
to obtain the correct latest version from the download metadata. Subsequent
behavior depends on the command:
outdated: Each download is immediately cancelled; an app is reported as
outdated if its version differs from the download metadata version.
update: The download is cancelled iff the installed version is the same as
the download metadata version. Otherwise, the update is allowed to complete.
This mode:
Connects to the
iTunes Search API iff
--no-check-min-os is not supplied.
Requires an Apple Account signed in to the App Store.
Opens a dialog:
If no Apple Account is signed in to the App Store.
For each app owned by a different Apple Account.
For each app no longer available from the App Store.
If --no-check-min-os is supplied, for each app for which the release
reported by the iTunes Search API is incompatible with your current macOS.
Can hang: Initiating downloads for dozens of apps is safe, but for hundreds of
apps can cause the App Store to stop responding. This is likely due to Apple
rate limiting, for which the exact thresholds, durations & ramifications are
currently unknown.
License
Licensed under the MIT license.
Originally created by Andrew Naylor
(@argon on GitHub |
@argon on X).
No homepage URL was recorded for mas-cli/mas in TopGit's last sync. The README tab above frequently contains screenshots and demo links, or check the repository description on GitHub.
Is mas-cli/mas open source?
Yes — mas-cli/mas ships under the MIT license, which makes its source code freely readable (and, depending on license terms, forkable and reusable). Source: github.com/mas-cli/mas.
What is mas-cli/mas?
mas-cli/mas (mas-cli/mas) is a Swift project on GitHub. From the project's own README: :package: Mac App Store command-line interface
What license does mas-cli/mas use?
mas-cli/mas is released under the MIT license. Always verify the LICENSE file directly on GitHub for the authoritative terms — license strings can be edited out of sync with a project's actual stance.
Where do I read more about mas-cli/mas?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/mas-cli/mas is the definitive source.
Read full README in the tab above.
Curious whether mas is right for you?
Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about mas.