A native dark desktop and CLI for App Store search, account access, IPA / PKG downloads, and guided FairPlay workflows in Rust.
Built on the work of ipatool, UnfairPlay, and their contributors. The combined Go project ipatool-fairplay is the direct reference for this port. Thank you to the original authors and maintainers.
Experimental Rust rewrite. This project was created to use otherwise-unused Codex quota and explore whether Codex could carry a substantial port through implementation, testing, and release. For practical use, prefer the original projects. Full parity remains under validation; see known limitations.
Install · Quick start · Commands · Desktop app · Architecture · MCP · Development · Documentation
| Area | Capabilities |
|---|---|
| Public catalog | Search applications, look up details, and find the latest external version ID without signing in. |
| Desktop app | Native dark GPUI desktop for public browsing, account interaction, Library, download tasks, and primary FairPlay workflows. Controlled Apple Silicon download, FairPlay setup and automatic reuse passed; other live gates remain. |
| Account and Store | Sign in, inspect or revoke saved credentials, obtain free-app licenses, and query purchases and version metadata. |
| Packages | Download entitled IPA or Mac PKG packages, with package metadata and SINF handling. |
| MCP | Expose six App Store tools to compatible clients over standard input and output. |
| FairPlay | Diagnostics, collection, recovery, and model-based decryption command paths. Controlled macOS setup and two real multi-image IPAs matched pinned UnfairPlay; broader private-data parity remains open. |
The following release targets are available:
| Operating system | Architecture | Distribution | Current scope |
|---|---|---|---|
| macOS | Apple Silicon / arm64 | Homebrew formula (CLI), cask (GUI), .tar.gz / .zip |
Developer ID signed and notarized CLI and desktop; controlled account, download and FairPlay setup/reuse checked. |
| Linux | x86_64 | .tar.gz |
Experimental; native CI and public catalog checks pass. Real account and package flows remain unverified. |
| Windows | x86_64 | .zip |
Experimental; native CI and public catalog checks pass. Real account and package flows remain unverified. |
macOS x86_64, Linux ARM64, Windows ARM64, and iOS runtime releases are deferred. The platforms accepted by --platform select an App Store offer; they do not expand the host operating systems supported by this release.
brew tap everettjf/tap
brew install --cask everettjf/tap/ipatool-rs-guiOpen IPATOOL-RS from Applications. Requires macOS 12 or later; protected FairPlay preparation requires macOS 13 or later and explicit administrator approval. Browse first, sign in when downloading, then follow FairPlay → First-time preparation once for a matching installed app and sample IPA. Later matching IPA downloads automatically reuse the saved model. Models and original downloads stay local. Remove collection access in the app before uninstalling it.
For upgrades, use brew upgrade --cask everettjf/tap/ipatool-rs-gui. The CLI and
desktop are installed separately; you can use either or both.
brew tap everettjf/tap
brew install everettjf/tap/ipatool-rs
ipatool-rs --versionFor an existing installation, use brew upgrade everettjf/tap/ipatool-rs.
Download the matching archive and its companion .sha256 file from GitHub Releases:
| Platform | Archive |
|---|---|
| macOS arm64 desktop | Latest release — choose *-gui-macos-arm64.zip, then move IPATOOL-RS.app to Applications |
| macOS arm64 CLI | Latest release — choose *-macos-arm64.tar.gz |
| Linux x86_64 | Latest release — choose *-linux-x86_64.tar.gz |
| Windows x86_64 | Latest release — choose *-windows-x86_64.zip |
For CLI archives, verify the checksum, extract the archive, and put the directory containing ipatool-rs on your PATH. On Windows, the executable is ipatool-rs.exe. The installed command is ipatool-rs and can coexist with the original ipatool.
Checksum verification
Run the check from the directory containing both the archive and its checksum file. Keep only the release you want to verify in that directory; the wildcards below match its downloaded filenames.
macOS:
shasum -a 256 -c ipatool-rs-*-macos-arm64.tar.gz.sha256For the macOS desktop ZIP:
shasum -a 256 -c ipatool-rs-*-gui-macos-arm64.zip.sha256Linux:
sha256sum -c ipatool-rs-*-linux-x86_64.tar.gz.sha256Windows PowerShell: compare the resulting hash with the companion .sha256 file.
Get-FileHash .\ipatool-rs-*-windows-x86_64.zip -Algorithm SHA256All usage examples assume that the installed ipatool-rs command is on your PATH.
ipatool-rs search ScriptWidget --platform macos --country US --limit 5
ipatool-rs lookup --app-id 1555600758 --platform macos --country US
ipatool-rs latest-version-id --app-id 1555600758 --platform macos --country USPublic queries default to the US storefront. Use --country to select another storefront and --format json for machine-readable output. Catalog requests support iPhone, iPad, Apple TV, Apple Watch, macOS, and visionOS offers.
ipatool-rs auth login
ipatool-rs auth info
ipatool-rs list-purchases --platform macos --max-results 2
ipatool-rs download --app-id 1555600758 --platform macos --output ./ScriptWidget.pkgEnter the Apple ID password and any verification code at the interactive prompts. purchase obtains a license for a free application; download requires the appropriate account entitlement.
Native Mac applications such as ScriptWidget download as PKGs. A compatible iPhone or iPad application offered on Apple Silicon Mac can return an IPA instead. Use --platform iphone to request an iPhone offer when the account is entitled to it. Package format follows the selected Store offer.
The desktop FairPlay page starts with a one-time preparation guide: prepare this Mac, choose an installed app and matching sample IPA, then review and start. It collects the supported authorization data, creates a model, processes the sample, and saves the model privately only after processing and applicable page hash checks pass. Advanced options also allow importing an existing model with a matching sample.
On macOS 13 or later, first-time preparation can use a separate, narrowly scoped authorization helper. The GUI stays unprivileged. Protected access requires a Developer ID signed, notarized bundle and explicit administrator approval in System Settings; opening the page never registers the helper. Local ad hoc builds disable this access. The helper reads only two fixed App Store authorization databases, not arbitrary paths, passwords or IPA files. Signed live registration, collection and real recovery passed on the controlled Apple Silicon host; see the authorization design.
After preparation, new IPA downloads automatically queue a separate decryption
task and match saved models using the IPA's authorization. You can turn this off
or use Decrypt IPA... for an existing download. No model selection is needed
for each app. Missing or mismatched models preserve the original download and
offer preparation; existing output files are never replaced. PKGs are unaffected.
Models are enrollment-specific; the same Apple ID does not guarantee a match.
Encrypted executables, extensions and frameworks resolve their own adjacent or
manifest-declared authorization. Missing or ambiguous relationships stop processing;
unused SINF resources do not select a model for an unrelated image.
Managed model storage currently requires macOS/Linux private-file permissions;
Windows support and portable private-processing validation remain open. These checks
require complete pre-encryption page-hash coverage to report verified plaintext.
Older executables without these tables remain explicitly unverified; a present
malformed or mismatching table rejects output. Embedded hashes do not establish
Apple CMS signature trust. Reports use ipatool-fairplay-decryption-v2; older
model receipts retain their original structural-check assurance.
See the FairPlay guide for prerequisites and limitations.
| Task | Commands |
|---|---|
| Search and inspect public catalog entries | search, lookup, latest-version-id |
| Manage saved account credentials | auth login, auth info, auth revoke |
| Obtain a free-app license | purchase |
| Query purchases and versions | list-purchases, list-versions, get-version-metadata |
| Download an application package | download |
| Start the MCP server | mcp |
| Inspect and process FairPlay data | fairplay-doctor, fairplay-enroll, fairplay-decrypt |
| Generate shell completions | completion |
Use ipatool-rs --help or a command's --help for its available options.
The CLI, MCP server, and optional GPUI desktop share Rust application modules. Public catalog queries use the catalog client directly and do not need a saved account or Apple guest execution.
Selected Store and SAP signing paths load pinned Apple framework images and execute ARM64 guest code through Unicorn. Rust supplies the image loaders, execution control, and host-call models. The program does not launch a separate Go, Python, or Swift executable; it still depends on the corresponding Apple guest code and the Unicorn runtime for these paths.
FairPlay setup defaults to native current-format SIDB recovery ported from pinned UnfairPlay. It verifies captured signed keyfiles, authenticates one selected enrollment route, and processes a matching sample IPA before saving a model. fairplay-enroll recover --engine legacy retains exact-build fairplayd/startup-profile research explicitly; there is no automatic legacy retry. SUPF variants 3/5 and signed SUPP variants 1/4 use deterministic class selection, consistent paired tables and available legacy code-signature bindings; conflicting tables never trigger a fallback. Controlled macOS authorization, model recovery and real multi-image decryption passed, including automatic reuse after restart; broader enrollment and portable private-data parity remain open. See real acceptance evidence.
The editable diagram is available as SVG. Implementation and parity evidence are recorded in PORTING.md.
Actual public-catalog capture; no account credentials or private packages are shown.
Install the signed and notarized Apple Silicon app with the Homebrew cask, or build the optional desktop from source:
cargo run --locked --features gui --bin ipatool-guiThe desktop is titled 🦀IPATOOL-RS 🦀 and uses a macOS-inspired graphite dark palette: neutral gray surfaces, a brighter sidebar and dialogs, gray selections, and blue primary actions and focus rings. It has a full-height workspace. Account, settings and sidebar controls sit at the bottom of the aligned navigation. The account control shows only signed-in status and the account region, including its tooltip. Narrow or collapsed windows use a compact icon rail. It supports public search, lookup by App ID or bundle identifier, six download targets, and a region dropdown searchable by English name or two-letter code. Every launch starts Explore and Library with iOS (iPhone), including when an older preference saved another platform. Other targets remain selectable during the session. Submit the search field with Enter or Search. Subsequent platform or region changes refresh results automatically and clear the previous selection while loading. Select a result to inspect metadata or copy identifiers, JSON, and CLI commands. Queries run in the background and report loading, empty, and error states.
Version 0.3.1 refreshes public support links, the contact email and project copyright to AtomSprout. Platform and live-validation limitations below remain applicable.
Version 0.3.0 adds a signed, notarized Apple Silicon desktop ZIP and Homebrew cask alongside the existing CLI distributions. This is an experimental release, with real controlled macOS account, download and FairPlay setup/reuse acceptance. The Windows GNU x86_64 GUI cross-build links successfully on macOS. Native CI also passes GUI builds, controller fixtures and Clippy on Linux x86_64 and Windows MSVC x86_64. Interactive Linux/Windows desktop and account checks remain open; CLI release status is unchanged. GPUI requires a graphical desktop and graphics support; macOS builds need Xcode with the Metal compiler tools. See the pinned GPUI crate for platform dependencies.
The desktop also exposes login/verification and file-store unlock, purchase history, version selection, background downloads, and FairPlay inspection/collection/recovery/model decryption through shared Rust application workflows. Browsing does not open credential storage. Account access starts only through an explicit account/download action; downloads check the account's storefront and entitlement. The download dialog allows changing the target platform and explains when the browsing region differs from the account region. Signing in or loading a saved account defaults browsing to that account's region, including when its identity or storefront changes. You can still select another region; the catalog and download sheet then warn that some applications may be unavailable to download. The catalog offers a return-to-account-region action. Same-account reauthentication preserves a manual browsing override. Browsing another region does not change the Apple account's storefront. A catalog miss during download preflight reports the account region before any package transfer starts. Task history contains request metadata and artifact paths, without credentials or signed download URLs. Interrupted tasks require explicit review and retry. See current evidence and remaining gates.
For a locally signed Apple Silicon application bundle, use
scripts/build-gui-macos.sh (or --debug). The generated .app is ad hoc signed,
not notarized or published by default. An explicitly Developer ID signed preview
has passed notarization and controlled macOS account/FairPlay acceptance. Public
desktop packages use Developer ID signing and stapled notarization tickets; the
remaining account/platform gates stay open.
Building without --features gui keeps the CLI-only build;
plain cargo run still selects ipatool.
Native screenshots include public browsing and separately labeled synthetic account/task walkthroughs. The optional fixture preview supports repeatable interaction testing without an Apple account; its simulated results are not live validation.
| Host | Default credential store |
|---|---|
| macOS | Apple Keychain; interactive commands may request authorization. |
| Linux | Secret Service when available, with encrypted file storage as a fallback. |
| Windows | Encrypted file storage. |
Use --file-keychain to select encrypted file storage explicitly:
ipatool-rs --file-keychain auth loginThe file store prompts for a separate passphrase. IPATOOL_STATE_DIR can select an absolute private directory for isolated account state and cookies. Keep credentials, cookies, downloaded packages, and private captures outside the repository.
--non-interactive disables terminal prompts and Keychain authorization dialogs. A command that needs approval or missing credentials returns an error so an unattended client can handle it.
Start the stdio server with:
ipatool-rs mcp --non-interactiveA typical client configuration is:
{
"mcpServers": {
"ipatool-rs": {
"command": "ipatool-rs",
"args": ["mcp", "--non-interactive"]
}
}
}Use an absolute executable path if the client does not inherit your shell's PATH.
Available tools: search_apps, list_purchases, list_app_versions, get_version_metadata, purchase_app, and download_app. Public search does not require an account; authenticated tools use saved account state.
Encrypted file storage with MCP
MCP uses standard input for its protocol, so it cannot prompt for the file-store passphrase. Supply --keychain-passphrase-file /absolute/private/path with the MCP command. On macOS and Linux, restrict the file to its owner with mode 0600. Remove the file after use and keep both Apple ID passwords and file-store passphrases out of process arguments and client configuration files.
- Linux and Windows real-account login, credential-store migration, and package workflows have not been validated end to end.
- macOS still needs a real 2FA challenge, successful expired-token recovery, and complete interactive default-Keychain login and revoke checks. Some authenticated MCP paths also remain unverified.
- Current-format FairPlay setup and two real IPAs passed on the controlled Apple Silicon host. Matching authorization is required; arbitrary enrollment formats, portable private flows and legacy private-data parity remain unverified.
- Automatic generation of a new FairPlay startup profile during collection is not implemented in the release.
See TODO.md for actionable remaining work and PORTING.md for the evidence behind each status. The release version does not imply full parity with the reference projects.
Use the stable Rust toolchain with rustfmt and clippy. Run the repository checks before submitting Rust changes:
cargo fmt --check
cargo test --all-targets --quiet
cargo clippy --all-targets -- -D warningsSome checks require cached Apple framework images or explicitly supplied private data. See the porting record for their prerequisites.
scripts/build-macos.sh --arm64The script writes an ad hoc signed target/release/ipatool-macos-arm64. To install a local development build under the usual command name:
mkdir -p "$HOME/.local/bin"
install -m 755 target/release/ipatool-macos-arm64 "$HOME/.local/bin/ipatool-rs"
export PATH="$HOME/.local/bin:$PATH"
ipatool-rs --versionAdd the PATH setting to your shell configuration if needed. This development signature is ad hoc; signed and notarized release packaging follows RELEASING.md.
cargo build --release --lockedCargo's internal binary name is ipatool (ipatool.exe on Windows). Release packaging installs it as ipatool-rs (ipatool-rs.exe). Use the installed name for the usage examples above.
| Document | Contents |
|---|---|
| PORTING.md | Reference parity, implementation notes, and verification evidence. |
| TODO.md | Remaining validation and implementation work. |
| RELEASING.md | Packaging, signing, notarization, CI releases, and Homebrew updates. |
| STARTUP_PROFILE_EXPORT.md | Design for the unfinished startup-profile export feature. |
Project website · Releases · Issues
The project is distributed under the MIT License, matching ipatool and UnfairPlay. The adapted DarkPhoenix recovery component retains its Apache-2.0 license and attribution; see NOTICE and LICENSE-DARKPHOENIX.txt.