IPATool Global Flags: Complete Guide to Persistent CLI Options

IPATool provides four persistent global flags—--format, --verbose, --non-interactive, and --keychain-passphrase—defined in cmd/root.go that are automatically inherited by every sub-command.

The majd/ipatool repository implements its command-line interface using the Cobra framework, which enables a clean pattern of persistent flags shared across the entire application. These global flags allow users to control output formatting, logging verbosity, interactive behavior, and keychain authentication from any command without redeclaring them individually.

How Global Flags Work in IPATool

IPATool leverages Cobra's persistent flag mechanism to define options once at the root command level and propagate them to all sub-commands. In cmd/root.go, the application registers these flags via cmd.PersistentFlags(), ensuring that values are parsed before any sub-command executes and injected into the command context for downstream use.

This architecture means that whether you run auth, search, download, or list-purchases, the identical set of global options remains available without additional configuration.

Complete List of IPATool Global Flags

The following flags are declared in cmd/root.go (lines 39‑47) and are available for every IPATool command:

--format <format>

Type: string
Default: text

Specifies the output format for command results. Accepts either text for human-readable output or json for machine-readable structured data. This flag controls how all sub-commands present their results to stdout.

--verbose

Type: bool

Enables detailed logging output for troubleshooting and debugging. When set, IPATool exposes additional operational details that help diagnose network requests, authentication flows, and download processes.

--non-interactive

Type: bool

Forces the tool to operate without interactive prompts, making it ideal for CI/CD pipelines and automated scripts. When enabled, the nonInteractive flag toggles the interactiveKey context value to prevent blocking for user input.

--keychain-passphrase <pass>

Type: string

Supplies the passphrase required to unlock the macOS Keychain-based credential store. This is essential for commands that need to access stored Apple ID credentials without triggering a GUI keychain prompt.

Practical Usage Examples

Use global flags in combination with any sub-command to control execution behavior:

# Search for an app with JSON output and verbose logging

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

# Download an IPA non-interactively for automation

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

# List purchases with keychain authentication for stored credentials

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

# Combine multiple flags for automated pipeline execution

ipatool download -i 987654321 --format json --non-interactive --verbose

Summary

• Four persistent flags (--format, --verbose, --non-interactive, --keychain-passphrase) are defined in cmd/root.go and inherited by all sub-commands.
• These options use Cobra's PersistentFlags() API to ensure universal availability across the CLI.
• The --non-interactive flag specifically controls the interactiveKey context value to disable prompts.
• JSON output mode (--format json) enables machine-readable integration with external tools and scripts.
• Keychain passphrase support allows headless operation with stored credentials on macOS systems.

Frequently Asked Questions

What is the default output format in IPATool?

The default output format is text, as defined in cmd/root.go. Users can override this with --format json to receive structured JSON output suitable for parsing by other applications or automation frameworks.

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

Pass the --non-interactive flag to any command. This global flag forces IPATool to skip all interactive prompts and fail immediately if required input is missing, preventing your automation from hanging indefinitely.

Where are IPATool global flags defined in the source code?

According to the majd/ipatool source, global flags are registered in cmd/root.go between lines 39 and 47 using Cobra's persistent flag system. This single definition point ensures consistency across auth.go, search.go, download.go, and all other sub-command files.

Can I combine multiple global flags in a single command?

Yes. IPATool global flags are designed to work together. For example, you can run ipatool search "example" --format json --verbose --non-interactive to get detailed JSON output without any interactive prompts, which is particularly useful for logging and debugging in automated environments.

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