# How to Use the Keychain Passphrase Override in IPATool

> Learn how to use the keychain passphrase override in IPATool to automate CI pipelines. Bypass terminal prompts and streamline your workflows with this essential flag.

- Repository: [Majd/ipatool](https://github.com/majd/ipatool)
- Tags: how-to-guide
- Published: 2026-09-01

---

**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`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/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:

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

```

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

```bash
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`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/cmd/common.go), but the secret is retrieved from the user's session keyring managed by the desktop environment or secret service daemon.