https://github.com/mas-cli/mas
:package: Mac App Store command line interface
https://github.com/mas-cli/mas
homebrew mac-app-store macos mas osx software-update
Last synced: 2 days ago
JSON representation
:package: Mac App Store command line interface
- Host: GitHub
- URL: https://github.com/mas-cli/mas
- Owner: mas-cli
- License: mit
- Created: 2015-08-02T20:43:12.000Z (almost 10 years ago)
- Default Branch: main
- Last Pushed: 2025-05-07T10:42:47.000Z (4 days ago)
- Last Synced: 2025-05-08T22:00:04.207Z (2 days ago)
- Topics: homebrew, mac-app-store, macos, mas, osx, software-update
- Language: Swift
- Homepage:
- Size: 3.8 MB
- Stars: 11,366
- Watchers: 106
- Forks: 285
- Open Issues: 103
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Audit: audit_exceptions/github_prerelease_allowlist.json
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- Awesome-iPhoneBlog.de-List - mas-cli/mas: Mac App Store command line interface
- awesome-tools - mas - Mac App Store CLI. (Command Line / Dependency Management)
- awesome-starred-test - mas-cli/mas - :package: Mac App Store command line interface (Swift)
- my-awesome-starred - mas-cli/mas - :package: Mac App Store command line interface (Swift)
- awesome-list - mas - cli | 8320 | (Swift)
- command-line-tools - mas - Command line interface for the Mac App Store. (macOS)
- awesome-hacking-lists - mas-cli/mas - :package: Mac App Store command line interface (Swift)
- my-awesome - mas-cli/mas - app-store,macos,mas,osx,software-update pushed_at:2025-04 star:11.3k fork:0.3k :package: Mac App Store command line interface (Swift)
- awesome - ๐ง mas - Mac App Store command line interface (Application / Other)
- awesome - ๐ง mas - Mac App Store command line interface (Application / Other)
- Awesome-GitHub-Repo - mas - App Store ็ๅฝไปค่กๅทฅๅ ทใ[<img src="https://tva1.sinaimg.cn/large/008i3skNly1gxlhtmg11mj305k05k746.jpg" alt="ๅพฎไฟก" width="18px" height="18px" />](https://mp.weixin.qq.com/s?__biz=MzUxNjg4NDEzNA%3D%3D&chksm=f9a1d521ced65c373d8970ddb8789ae7217e70c33981b00b7cdd6e4a13e528a9cba6509e1aad&idx=1&mid=2247485160&scene=21&sn=8c3ccfa18af516589f226bef3e8335d3#wechat_redirect) (ๅผๆบๅทฅๅ ท / ๅฝไปค่กๅทฅๅ ท)
README
# mas
A command-line interface for the Mac App Store. Designed for scripting & automation.
[](https://github.com/mas-cli/mas/releases)
[](LICENSE)
[](https://www.swift.org)
[](
https://github.com/mas-cli/mas/actions/workflows/build-test.yaml?query=branch%3Amain
)
## ๐ฒ Installation
### ๐บ Homebrew
[Homebrew](https://brew.sh) is the preferred way to install:
```shell
brew install mas
```
โ ๏ธ macOS 10.15 (Catalina) or newer is required to install mas from the Homebrew core formula.
### ๐ MacPorts
[MacPorts](https://www.macports.org/install.php) is an alternative way to install:
```shell
sudo port install mas
```
โ ๏ธ macOS 10.15 (Catalina) or newer is required to install mas from MacPorts.
### ๐งฎ Older macOS Versions
#### ๐ป Custom Homebrew tap
The [mas custom Homebrew tap](https://github.com/mas-cli/homebrew-tap) provides pre-built bottles for all macOS versions
since 10.11 (El Capitan). The newest versions of mas, however, are only available for macOS 10.15+ (Catalina or newer).
To install mas from the custom tap:
```shell
brew install mas-cli/tap/mas
```
#### ๐ GitHub Releases
Alternatively, binaries & sources are available from [GitHub Releases](https://github.com/mas-cli/mas/releases).
#### ๐ Swift 5 Runtime Support
mas requires Swift 5 runtime support. macOS 10.14.4 (Mojave) & newer include it, but earlier releases do not. Without
it, running mas might report errors similar to:
> dyld: Symbol not found: _$s11SubSequenceSlTl
To get Swift 5 support on macOS versions older than 10.14.4 (Mojave), you can:
- Upgrade to macOS 10.14.4 (Mojave) or newer.
- Install the [Swift 5 Runtime Support for Command Line Tools](https://support.apple.com/en-us/106446).
- Install Xcode 10.2 or newer to `/Applications/Xcode.app`.
## ๐คณ Usage
### ๐ชช App IDs
Each application in the Mac App Store has an integer app identifier (app ID). mas commands accept app IDs as arguments &
output app IDs to uniquely identify apps.
`mas search` & `mas list` can be used to find the app IDs of relevant apps.
Alternatively, to find an app's app ID:
1. Find the app in the Mac App Store
2. Select `Share` > `Copy Link`
3. Extract the app ID from the URL.
- e.g., extract app ID `497799835` from the URL for Xcode ()
### ๐ Info from the Mac App Store
None of the commands in this section require you to be logged into an Apple Account, neither for your macOS user nor in
the Mac App Store.
#### `mas search`
`mas search ` searches by name for applications available from the Mac App Store. Providing the `--price`
flag includes each app's price in the output.
```console
$ mas search Xcode
497799835 Xcode
688199928 Docs for Xcode
[...]
```
#### `mas info`
`mas info ` displays more detailed information about an application available from the Mac App Store.
```console
$ mas info 497799835
Xcode 16.0 [Free]
By: Apple Inc.
Released: 2024-09-16
Minimum OS: 14.5
Size: 2.98 GB
From: https://apps.apple.com/us/app/xcode/id497799835?mt=12&uo=4
```
### ๐ Info from Your Local App Library
All the commands in this section require you to be logged into an Apple Account for your macOS user.
#### `mas list`
`mas list` displays all the applications on your Mac that were installed from the Mac App Store.
```console
$ mas list
497799835 Xcode (15.4)
640199958 Developer (10.6.5)
899247664 TestFlight (3.5.2)
```
#### `mas outdated`
`mas outdated` displays all applications installed from the Mac App Store on your Mac that have pending upgrades.
```console
$ mas outdated
497799835 Xcode (15.4 -> 16.0)
640199958 Developer (10.6.5 -> 10.6.6)
```
Run [`mas upgrade`](#mas-upgrade) to install pending upgrades.
### โฌ๏ธ Installing Apps
All the commands in this section require you to be logged into an Apple Account in the Mac App Store.
> Depending on your Apple Account settings, you might need to re-authenticate yourself in the Mac App Store to perform a
> purchase, install, lucky, or upgrade, even if you are already signed in to an Apple Account in the Mac App Store.
#### `mas purchase`
`mas purchase โฆ` installs free applications that you haven't yet gotten/"purchased" from the Mac App Store.
> `purchase` is currently a misnomer, because it currently can only "purchase" free apps. To purchase apps that cost
> money, please purchase them directly in the Mac App Store.
```console
$ mas purchase 497799835
==> Downloading Xcode
==> Installed Xcode
```
#### `mas install`
`mas install โฆ` installs apps that you have already gotten/"purchased" from the Mac App Store. Providing the
`--force` flag re-installs the app even if it is already installed on your Mac.
```console
$ mas install 497799835
==> Downloading Xcode
==> Installed Xcode
```
#### `mas lucky`
`mas lucky ` installs the first result that would be returned by `mas search `. Like
`mas install`, `mas lucky` can only install apps that have previously been gotten/"purchased".
```console
$ mas lucky Xcode
==> Downloading Xcode
==> Installed Xcode
```
### ๐ Upgrading Apps
All the commands in this section require you to be logged into an Apple Account in the Mac App Store.
> mas only installs/upgrades applications from the Mac App Store.
>
> Use [`softwareupdate(8)`](https://www.unix.com/man-page/osx/8/softwareupdate) to install system updates (e.g., Xcode
> Command Line Tools, Safari, etc.)
#### `mas upgrade`
`mas upgrade` upgrades outdated apps installed from the Mac App Store. Without any arguments, it upgrades all such apps.
```console
$ mas upgrade
Upgrading 2 outdated applications:
Xcode (15.4) -> (16.0)
Developer (10.6.5) -> (10.6.6)
==> Downloading Xcode
==> Installed Xcode
==> Downloading Developer
==> Installed Developer
```
Upgrades can be performed selectively by providing app IDs to `mas upgrade`.
```console
$ mas upgrade 715768417
Upgrading 1 outdated application:
Xcode (15.4) -> (16.0)
==> Downloading Xcode
==> Installed Xcode
```
### Mac App Store Account Management
All the commands in this section interact with the Apple Account for which you are signed in to the Mac App Store. These
commands do not interact with the Apple Account for which your macOS user is signed in.
#### `mas signin`
> โ The `signin` command is not supported on macOS 10.13 (High Sierra) or newer. On those macOS versions, please sign in
> via the Mac App Store instead. Please see [Known Issues](#known-issues).
On macOS 10.12 (Sierra) or older, `mas signin ` signs in to the specified Apple Account in the Mac App Store.
```console
$ mas signin [email protected]
Password:
```
Providing the `--dialog` flag signs in using a graphical dialog provided by Mac App Store.
```shell
mas signin --dialog [email protected]
```
You can also embed your password in the command.
```shell
mas signin [email protected] MyPassword
```
#### `mas signout`
`mas signout` signs out from the current Apple Account in the Mac App Store.
## ๐บ Homebrew integration
mas integrates with [homebrew-bundle]. If mas is installed, when you run `brew bundle dump`, your Mac App Store apps
will be included in the created Brewfile. See the [homebrew-bundle] docs for more details.
### ๐ฅ Changed Apple Private Frameworks
mas uses multiple undocumented Apple private frameworks to implement much of its functionality. Over time, Apple has
silently changed these frameworks, breaking some functionality. Known issues include:
- โ The `signin` command is not supported on macOS 10.13 (High Sierra) or newer.
[#164](https://github.com/mas-cli/mas/issues/164)
- โ The `account` command is not supported on macOS 12 (Monterey) or newer
[#417](https://github.com/mas-cli/mas/issues/417)
### โณ Eventual Consistency
The Mac App Store operates on eventual consistency, so the versions seen by various parts of mas or the Mac App Store
might be inconsistent for short periods of time. This might cause symptoms like
[#384](https://github.com/mas-cli/mas/issues/384) & [#387](https://github.com/mas-cli/mas/issues/387).
### ๐ฑ iOS & iPadOS Apps
Apple Silicon Macs can install & run iOS & iPadOS apps from the Mac App Store. mas does not yet support such apps.
[#321](https://github.com/mas-cli/mas/issues/321)
### ๐บ Using `tmux`
mas operates via the same system services as the Mac App Store. These exist as separate processes with communication
through XPC. As a result of this, mas experiences similar problems as the pasteboard when running inside `tmux`. A
[wrapper tool exists](https://github.com/ChrisJohnsen/tmux-MacOSX-pasteboard) to fix pasteboard behavior which also
works for mas.
You should consider configuring `tmux` to use the wrapper, but, if you do not wish to do this, it can be used on a
one-off basis as follows:
```shell
brew install reattach-to-user-namespace
reattach-to-user-namespace mas install
```
### ๐ญ `mas list`, `mas outdated`, `mas uninstall`, or `mas upgrade` does not detect installed apps
mas 2.0.0+ sources data for installed Mac App Store apps from macOS's Spotlight metadata store.
mas can only interact with installed Mac App Store apps if they have been indexed by the Spotlight Metadata Server (aka
MDS) background processes.
You can check if a Mac App Store app has been indexed in the metadata store by running:
```console
## General format:
$ mdls -rn kMDItemAppStoreAdamID /path/to/app
## Outputs nothing if the app is not indexed
## Outputs the app ID if the app is indexed
## Example:
$ mdls -rn kMDItemAppStoreAdamID /Applications/WhatsApp.app
310633997
```
If an app has been indexed in the metadata store, given its app ID, you can find the path to the app by running:
```console
$ mdfind 'kMDItemAppStoreAdamID == 310633997'
/Applications/WhatsApp.app
```
If any of your Mac App Store apps are not indexed, you can enable/rebuild the metadata store for all file system volumes
by running:
```shell
sudo mdutil -Eai on
```
## ๐ซ When something doesn't work
If you see the following error, it's probably because you haven't yet "purchased" the app through the Mac App Store. See
[#46](https://github.com/mas-cli/mas/issues/46#issuecomment-248581233).
> This redownload is not available for this Apple Account either because it was bought by a different user or the item
> was refunded or canceled.
If mas doesn't work for you as expected (e.g., you can't install/upgrade apps), run `mas reset`, then try again. If the
issue persists, please [file a bug](https://github.com/mas-cli/mas/issues/new). All feedback is much appreciated! โจ
## ๐ Build from source
You can build from Xcode by opening the root mas directory, or from the terminal:
```shell
script/build
```
Build output can be found in the `.build` directory within the project.
## ๐งช Tests
Tests are written using [Quick](https://github.com/Quick/Quick) & [Nimble](https://github.com/Quick/Nimble).
```shell
script/test
```
## ๐ License
Code is under the [MIT license](LICENSE).
mas was created by [@argon](https://github.com/argon).
[homebrew-bundle]: https://github.com/Homebrew/homebrew-bundle