# mist-cli: a Swift command line tool that fetches macOS installers and firmware by name > mist-cli is a macOS command line tool written in Swift that lists and downloads Apple firmware restore images and macOS installers, verifies checksums as it goes, and can turn a downloaded installer into an application bundle, a disk image, a bootable ISO or a signed package. It also exports the catalogue as CSV, JSON, plist or YAML for scripted deployment. **ninxsoft/mist-cli** — A Mac command-line tool that automatically downloads macOS Firmwares / Installers. - Repository: https://github.com/ninxsoft/mist-cli - Stars: 823 · Forks: 46 - Language: Swift - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/ninxsoft-mist-cli ## What the three subcommands do mist stands for macOS Installer Super Tool and is described as a Mac command line tool that automatically downloads macOS firmwares and installers. The command surface is small enough to read in one screen: ```shell OVERVIEW: macOS Installer Super Tool. Automatically download macOS Firmwares / Installers. USAGE: mist OPTIONS: -h, --help Show help information. SUBCOMMANDS: list List all macOS Firmwares / Installers available to download. download Download a macOS Firmware / Installer. version Display the version of mist. See 'mist help ' for detailed help. ``` Three subcommands, and the interesting one is list. The listing shows display names, versions, builds, sizes and release dates for everything available, and it can optionally include beta versions. Two filters do real work for an administrator: one restricts the list to versions compatible with the Mac the tool is being run from, and one selects a particular macOS release by name. The export flag turns the listing into a file. The same list can be written as CSV, JSON, a Property List or YAML: ```shell # List + Export macOS Installers to a CSV file: mist list installer --export "/path/to/export.csv" ``` That export is what turns this from a convenience script into something you can drive. Listing the catalogue and exporting it as JSON is how you would work out what a fleet needs, and the compatible filter is how you find out what a given machine can actually take. The tool is written in Swift, MIT licensed, and the last release was v2.3 on 2026-06-10, with v2.2 in September 2025 and v2.1.1 in July 2024. ## Listing by version, by latest and by compatibility The examples section shows the range of listing queries. The simplest lists everything for a given artifact type: ```shell # List all available macOS Installers for Intel Macs, # including Universal Installers for macOS Big Sur and later: mist list installer ``` Adding the compatible flag narrows it to what the current machine supports: ```shell # List all macOS Installers that are compatible with this Mac, # including Universal Installers for macOS Big Sur and later: mist list installer --compatible ``` A name selects a release line, and the latest flag reduces that to the newest build in it: ```shell # List only the latest macOS Sonoma Installer for Intel Macs, # including Universal Installers for macOS Big Sur and later: mist list installer --latest "macOS Tahoe" ``` Betas are opt-in rather than the default: ```shell # List all available macOS Installers for Intel Macs, including betas, # also including Universal Installers for macOS Big Sur and later: mist list installer --include-betas ``` The separation between the two artifact types matters. The firmware listing covers restore files for Apple Silicon Macs, while the installer listing covers the Intel side, with the Universal installers that exist from macOS Big Sur onward counted as installers rather than firmware. The examples in the README also show a build number being used as the selector, for instance a build identifier in place of a marketing name, which is how you pin an exact build. One permission note runs through the documentation. Depending on what mist downloads, you may need to allow Full Disk Access for your terminal application of choice through System Settings. ## Downloading and the four output formats The download command takes a firmware or installer, a version selector, and then a format. The formats for an Intel Mac installer are an application bundle, a disk image, a bootable disk image and an installer package. The application bundle is the simplest: ```shell # Download the latest macOS Sonoma Installer for Intel Macs, # including Universal Installers for macOS Big Sur and later: mist download installer "macOS Tahoe" application ``` A disk image with a custom name uses a template with placeholders: ```shell # Download a specific macOS Installer version for Intel Macs, # including Universal Installers for macOS Big Sur and later, # and generate a Disk Image with a custom name: mist download installer "26.0" image --image-name "Install %NAME% %VERSION%-%BUILD%.dmg" ``` And the signed disk image case adds an identity and an output directory: ```shell # Download a specific macOS Installer build for Inte Macs, # including Universal Installers for macOS Big Sur and later, # and generate a codesigned Disk Image output to a custom directory: mist download installer "25A354" image \ --image-signing-identity "Developer ID Application: Name (Team ID)" \ --output-directory "/path/to/custom/directory" ``` The placeholder convention is worth noting, since you will meet it in any script you write: %NAME% is the product name, %VERSION% the version and %BUILD% the build number, so the same template works across releases. The bootable ISO exists for virtualisation software, named as Parallels Desktop, VMware Fusion and VirtualBox, which is the case where you want an installer that boots in a VM rather than one that installs onto the machine. The package format is noted as supporting packages on macOS Big Sur and newer, with a payload of more than 12GB, which is a useful warning before you commit disk space. The firmware path for Apple Silicon downloads a .ipsw restore file and validates the SHA-1 checksum upon download. The installer path validates the chunklist checksums. Both are the kind of verification that turns a downloaded installer into a trusted one, and both are checked for you rather than left to the reader. ## Catalogs, caching and the operational details A catalog URL can be specified, which is what lets you list and download from the seed programs rather than the public catalogue. Three are named: Customer Seed, the catalog available as part of the AppleSeed Program, Developer Seed from the Apple Developer Program, and Public Seed from the Apple Beta Software Program. The documentation is careful about what that means in practice. Catalogs from the seed programs may contain beta or unreleased versions of macOS, and you are told to ensure you are a member of those programs before proceeding. That is a licensing condition, not a technical one, and it is the sort of thing that gets forgotten when a script is scheduled on a build server. Three more operational details are worth knowing. Downloads are cached to speed up build operations, so repeated runs of a pipeline do not re-fetch the same payload. Free space is checked before any download or installation is attempted, which matters a great deal when the package payload is over 12GB and the disk image doubles it. And there are automatic retries for failed downloads, which matters because these are large files over a network that occasionally drops. Optional codesigning is available for disk images and installer packages, using a Developer ID identity you supply. ## Building it from the Makefile The repository is a Swift package with an Xcode project, a Mist source directory, a MistTests directory, a Package.swift and a Makefile for packaging. The Makefile is short and shows how releases are produced. The build target compiles for both architectures at once: ```make build: swift build --configuration release --arch arm64 --arch x86_64 codesign --sign "$(identity_app)" --options runtime "$(source)" ``` Building a universal binary is the obvious requirement for a tool that runs on both Apple Silicon and Intel Macs, and the codesign step with the runtime option matches what the download command can also do for disk images and packages. The package target assembles a macOS installer package rather than a plain archive. It stages the binary into a temporary directory, runs pkgbuild with the identifier, the version, a minimum OS version of 11.0 and a signing identity, and then removes the staging directory. The version is not hard-coded, it is read back out of the built binary with mist --version, so the package always matches the artifact inside it. The repository also carries a .swiftlint.yml, a .swiftformat configuration, a .swift-version file, a .drstring.toml for localisation strings, a CHANGELOG and three GitHub Actions workflows for linting, unit tests and building. ## Where mist-cli is the wrong choice The first limit is platform. This is a macOS tool that talks to Apple's catalog and downloads Apple installers, so it is only useful where Apple installers are the thing you need. The second is that it is a downloader, not a deployment system. mist-cli gets a named installer onto one machine, and the companion Mist Mac app is the graphical version of the same thing. Neither is a management agent: there is no inventory, no reporting back to a server, no enforcement that a machine is on a given version. For a fleet with hundreds of Macs, the usual answer is a management platform, and mist-cli is the tool you reach for when you need the installer itself rather than the deployment. The third is the licensing boundary. The seed catalogs contain beta and unreleased macOS, and using them requires membership of the relevant Apple program. A team that wants a beta in CI has to be in the program, and a team that has left the program has to fall back to the public catalog and the released versions in it. The fair comparison is with Apple's own tooling. The softwareupdate mechanism manages updates for the running system, and the App Store and MDM payloads handle the standard cases with Apple's support behind them. What mist-cli adds is exact version and build selection, machine-readable export of the catalogue, and the ability to produce a bootable ISO or a signed disk image from an installer, which the standard tools do not do. ## Conclusion mist-cli fits a Mac administrator who needs a named macOS build on a machine without clicking through an installer, who wants the catalogue in a scriptable format, and who wants checksums verified rather than assumed. It does not fit a Windows or Linux shop, and it does not replace a managed software deployment system for a large estate. Before using it, grant Full Disk Access to your terminal as the documentation asks, verify that the build you request is one you are licensed to install, and note that the versions and catalogs change with Apple's release cycle, so a script that hard-codes a version should be checked against the catalogue output rather than assumed. ## FAQ ### What is mist-cli and what can it download? It is a Swift command line tool for macOS that lists and downloads Apple firmware restore images and macOS installers. For Intel Macs it can produce an application bundle, a disk image, a bootable ISO for virtualisation software, or an installer package, and for Apple Silicon Macs it downloads the .ipsw firmware file. ### How do I list the macOS versions mist-cli can download? Use `mist list installer` for installers and `mist list firmware` for firmware. You can add `--compatible` to restrict the list to versions the current Mac supports, `--include-betas` to include beta versions, a version name such as "macOS Tahoe" to select a release line, `--latest` for the newest build in it, and `--export` with a .csv, .json, .plist or .yaml path to write the list to a file. ### Does mist-cli verify what it downloads? Yes. The firmware download validates the SHA-1 checksum, and the installer download validates the chunklist checksums. The tool also checks free space before attempting a download and retries automatically when a download fails. ### Can mist-cli fetch installers from the Apple seed programs? Yes, by specifying a custom catalog URL. The documentation names Customer Seed from the AppleSeed Program, Developer Seed from the Apple Developer Program, and Public Seed from the Apple Beta Software Program, and warns that those catalogs may contain beta or unreleased macOS and that you must be a member of the programs. ### What permissions does mist-cli need on macOS? Depending on what it downloads, you may need to allow Full Disk Access for your terminal application of choice through System Settings. The tool also downloads large payloads, with installer packages on macOS Big Sur and newer carrying more than 12GB, and checks free space before starting. ## Sources - [Issues](https://github.com/ninxsoft/mist-cli/issues) - [License: MIT](https://github.com/ninxsoft/mist-cli/blob/main/LICENSE) - [ninxsoft/mist-cli on GitHub](https://github.com/ninxsoft/mist-cli) - [README](https://github.com/ninxsoft/mist-cli/blob/main/README.md) - [Releases](https://github.com/ninxsoft/mist-cli/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ninxsoft-mist-cli