IPATool Global Flags: A Complete Guide to Persistent Command-Line Options

IPATool exposes four persistent global flags—--format, --verbose, --non-interactive, and --keychain-passphrase—defined in cmd/root.go that apply to every sub-command via the Cobra CLI framework.

The majd/ipatool repository implements its command-line interface using the Cobra library, which supports persistent flags that automatically propagate to all sub-commands. These IPATool global flags control output formatting, logging verbosity, interactive behavior, and keychain authentication across the entire toolset, eliminating the need to specify common options for individual commands like download or search.

Available IPATool Global Flags

The following persistent flags are registered in the root command and inherited by all sub-commands:

--format: Configure Output Serialization

Type: string
Default: text
Source: cmd/root.go (lines 39-44)

The --format flag controls the serialization format of command output. Acceptable values are text for human-readable terminal output or json for structured, machine-parseable responses. When using JSON output, programmatic scripts can reliably parse search results, download metadata, and authentication status.

--verbose: Enable Debug Logging

Type: bool
Default: false
Source: cmd/root.go (lines 44-45)

Setting the --verbose flag activates detailed logging output, which is essential for troubleshooting network requests, authentication flows, and App Store API interactions. This boolean flag injects debug information into stderr without affecting the primary command output stream.

--non-interactive: Suppress User Prompts

Type: bool
Default: false
Source: cmd/root.go (lines 44-46)

The --non-interactive flag forces IPATool to run without interactive prompts, making it suitable for CI/CD pipelines and automated scripts. When enabled, this flag sets the interactiveKey context value to disable password prompts and confirmation dialogs that would otherwise hang in headless environments.

--keychain-passphrase: Authenticate Credential Store

Type: string
Source: cmd/root.go (lines 45-47)

This flag supplies the passphrase required to unlock the macOS Keychain when accessing stored Apple ID credentials. Providing this value programmatically prevents the OS from displaying a graphical keychain unlock dialog, which is critical for automated workflows on macOS systems.

Practical Usage Examples

The following examples demonstrate how to combine these global flags with specific IPATool sub-commands:

# Use JSON output and enable verbose logging for debugging search results

ipatool search "spotify" --format json --verbose

# Run a download non-interactively for automation (no password prompts)

ipatool download -i 123456789 --output ./spotify.ipa --non-interactive

# Provide keychain passphrase for credential-dependent operations

ipatool list-purchases --keychain-passphrase "mySecretPass"

Implementation in the Source Code

According to the majd/ipatool source code, global flags are registered using Cobra's cmd.PersistentFlags() method within cmd/root.go. This architectural decision ensures that flags are parsed during command initialization and their values are injected into the command context before any sub-command logic executes.

For instance, the nonInteractive boolean flag toggles the interactiveKey context value, which downstream commands check before presenting user prompts. Because these are persistent flags rather than local flags, all sub-commands—including auth, search, download, and list-purchases—automatically inherit these options without requiring redundant flag declarations in individual command files.

Summary

• IPATool defines four global flags in cmd/root.go using Cobra's persistent flags mechanism
• The --format flag accepts text or json output formats (default: text)
• Use --verbose to activate detailed troubleshooting logs for debugging
• The --non-interactive flag disables all prompts for automated CI/CD workflows
• Pass --keychain-passphrase to programmatically unlock macOS Keychain stored credentials
• These flags automatically propagate to all sub-commands without individual configuration

Frequently Asked Questions

What is the default output format for IPATool?

IPATool defaults to text format for human-readable terminal output. Specify --format json to receive structured JSON responses suitable for programmatic parsing and integration with other tools.

Can I use global flags with any IPATool sub-command?

Yes. Because these flags are registered as Cobra persistent flags in the root command at cmd/root.go, they are automatically available for every sub-command including auth, search, download, and list-purchases without additional configuration.

How do I run IPATool in CI/CD pipelines without prompts?

Add the --non-interactive flag to your commands. This boolean flag, defined at lines 44-46 of cmd/root.go, disables all interactive prompts and graphical dialogs, allowing the tool to execute headlessly in automated environments.

Where are the global flags defined in the source code?

The global flags are defined in the cmd/root.go file within the majd/ipatool repository. The --format flag configuration appears at lines 39-44, while --verbose, --non-interactive, and --keychain-passphrase are configured between lines 44-47.

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