How to Use the Keychain Passphrase Override in IPATool

IPATool provides the --keychain-passphrase flag to supply the keychain password non-interactively, enabling automated workflows in CI pipelines by bypassing the terminal prompt.

IPATool stores Apple ID credentials in the system keychain (or Secret Service on Linux), protected by a passphrase that the tool requests at runtime. When deploying majd/ipatool in automated environments such as CI/CD pipelines, interactive prompts are impossible, making the keychain passphrase override essential for uninterrupted authentication.

How the Keychain Passphrase Override Works

IPATool encrypts your Apple ID credentials locally using the system keychain. To decrypt this store, the tool requires a passphrase that—by default—it requests via an interactive terminal prompt. To support headless automation, the tool implements a priority-based passphrase resolution system controlled by the FilePasswordFunc callback.

Flag Definition in cmd/root.go

The --keychain-passphrase option is registered as a persistent CLI option in the root command. In cmd/root.go at line 46, the flag binds to the global variable keychainPassphrase, making the supplied value available throughout the application lifecycle regardless of which subcommand you invoke.

Passphrase Retrieval Logic in cmd/common.go

The actual logic governing how IPATool obtains the passphrase resides in the initWithCommand function within cmd/common.go. When initializing the keychain, the code configures a FilePasswordFunc callback (lines 73-81) that evaluates three distinct conditions:

1. Non-interactive mode without passphrase: If the --non-interactive flag is set but no passphrase is provided, the function returns an error instructing the user to include --keychain-passphrase.
2. Passphrase flag provided: When --keychain-passphrase contains a value, the function returns that string directly, bypassing all prompts.
3. Interactive mode: If running in a terminal without the flag, the tool prompts the user via golang.org/x/term and reads the password from standard input.

Implementing the Keychain Passphrase Override

For standard interactive use, IPATool automatically prompts for the passphrase when accessing stored credentials:

ipatool download --bundle-id com.example.app

For automation scenarios, combine --keychain-passphrase with --non-interactive to prevent any terminal interaction:

ipatool download \
    --bundle-id com.example.app \
    --non-interactive \
    --keychain-passphrase "my-secret-passphrase"

Omitting --non-interactive while providing the flag also prevents prompts, which suits scripts running in terminal-attached sessions where background processes should not hang waiting for input.

Summary

• IPATool stores Apple ID credentials in the system keychain, requiring a passphrase for decryption that is normally requested interactively.
• The --keychain-passphrase flag, defined in cmd/root.go (line 46), accepts the password as a command-line argument and stores it in the global keychainPassphrase variable.
• The initWithCommand function in cmd/common.go implements the retrieval logic via FilePasswordFunc (lines 73-81), prioritizing the flag value over interactive prompts.
• For CI/CD automation, always combine --keychain-passphrase with --non-interactive to ensure the tool fails explicitly rather than hanging on a hidden prompt.

Frequently Asked Questions

What happens if I use --non-interactive without --keychain-passphrase?

The tool detects the missing passphrase in the FilePasswordFunc callback within cmd/common.go (lines 74-76) and returns an explicit error, terminating execution immediately rather than waiting indefinitely for terminal input that will never arrive.

Is the keychain passphrase the same as my Apple ID password?

No. The keychain passphrase protects the local encrypted store containing your Apple ID credentials, while your Apple ID password authenticates with Apple's servers. IPATool requires both: the keychain passphrase to unlock local storage via the logic in cmd/common.go, and the Apple ID password (stored within that keychain) for App Store communication.

Can I use environment variables instead of the --keychain-passphrase flag?

The source code in cmd/root.go only defines the persistent flag --keychain-passphrase; it does not automatically bind to environment variables. You must explicitly pass the value via the CLI argument, though wrapper scripts can inject environment variable contents into this flag at runtime.

Where does IPATool store the keychain on Linux systems?

On Linux, IPATool utilizes the Secret Service API rather than a file-based keychain. The same --keychain-passphrase logic applies in cmd/common.go, but the secret is retrieved from the user's session keyring managed by the desktop environment or secret service daemon.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}