How to Change the Output Format of IPATool: JSON vs Text Mode

IPATool supports both human-readable plain text and machine-readable JSON output formats via the global --format flag, defaulting to text when unspecified.

IPATool is a command-line utility for interacting with the iOS App Store, allowing you to search for and download IPA files directly. Whether you are building automation scripts or simply prefer structured data for parsing, controlling the output format is essential for integrating IPATool into your workflow. This guide examines the source code of majd/ipatool to explain exactly how the --format flag works and how to leverage it effectively.

IPATool Output Format Options

IPATool provides two distinct output modes:

• Plain text: Human-readable formatting with color codes and spacing optimized for terminal interaction
• JSON: Structured, newline-delimited JSON suitable for piping to tools like jq or parsing in automation scripts

The format selection mechanism is implemented across three core files in the cmd/ directory, utilizing the enumflag library for type-safe command-line parsing.

How the Format Flag Works

Flag Registration in cmd/root.go

In cmd/root.go, the global --format flag is registered as a persistent flag, making it available to every subcommand. The implementation uses the enumflag package to map string inputs to internal enum values:

cmd.PersistentFlags().VarP(
    enumflag.New(&format, "format", map[OutputFormat][]string{
        OutputFormatText: {"text"},
        OutputFormatJSON: {"json"},
    }, enumflag.EnumCaseSensitive), "format", "", "sets output format for command; can be 'text', 'json'")

This registration ensures that both --format text and --format json are valid inputs across all IPATool commands, including list-purchases, download, and search.

The OutputFormat Enum Definition

The OutputFormat type is defined in cmd/output_format.go as a custom flag type based on enumflag.Flag:

type OutputFormat enumflag.Flag

const (
    OutputFormatText OutputFormat = iota
    OutputFormatJSON
)

Here, OutputFormatText is assigned the zero value (iota 0), which explains why text format is the default when no --format flag is provided.

Runtime Parsing and Renderer Selection

When commands execute, cmd/common.go handles the actual format parsing and logger configuration. The initWithCommand function retrieves the flag value and converts it to the enum type:

format := util.Must(OutputFormatFromString(cmd.Flag("format").Value.String()))

Based on this parsed value, the application instantiates the appropriate writer. As shown in cmd/common.go, the switch statement determines whether to use zerolog for JSON or the standard text writer:

switch format {
case OutputFormatJSON:
    writer = zerolog.SyncWriter(os.Stdout)   // JSON
case OutputFormatText:
    writer = log.NewWriter()                // Plain text
}

This architecture ensures that once the format is set, all subsequent output respects the choice consistently throughout the command execution.

Practical Usage Examples

To change the output format, append --format json or --format text to any IPATool command. The flag is global, so it must appear before subcommands or immediately after the binary name.

Default text output:

ipatool list-purchases

Explicit text output (equivalent to default):

ipatool --format text list-purchases

JSON output for scripting and filtering:

ipatool --format json list-purchases | jq '.[] | .bundleId'

Combined with other command-line options:

ipatool --format json download --bundle-id com.example.app --version 1.2.3

Automating Format Selection

If you consistently require JSON output, create a shell alias rather than typing the flag each time. Add this to your shell configuration file (.bashrc, .zshrc, or .bash_profile):

alias ipatool='ipatool --format json'

With this alias, every invocation automatically uses JSON format while preserving all other command-line functionality.

Summary

• IPATool supports two output formats: plain text (default) and JSON.
• The global --format flag controls output across all commands, implemented in cmd/root.go using PersistentFlags().VarP().
• The OutputFormat enum in cmd/output_format.go defines the available values, with text as the zero-value default.
• Runtime parsing in cmd/common.go switches between zerolog.SyncWriter for JSON and log.NewWriter() for text output.
• Use --format json for machine-readable output or set a shell alias to make JSON your permanent default.

Frequently Asked Questions

What is the default output format for IPATool?

The default output format is plain text. This occurs because OutputFormatText is defined as the zero value (iota 0) in the OutputFormat enum within cmd/output_format.go. When the --format flag is omitted, the application falls back to this zero value automatically, selecting the text writer.

Can I use the --format flag with any IPATool subcommand?

Yes. The --format flag is registered as a persistent flag in cmd/root.go using PersistentFlags().VarP(), which makes it available to all subcommands including list-purchases, download, and search. You can place it immediately after the binary name or before any subcommand.

Why does IPATool use zerolog for JSON output?

IPATool uses zerolog.SyncWriter(os.Stdout) when JSON format is selected because zerolog provides structured, zero-allocation JSON logging that is ideal for machine parsing. For text output, it uses log.NewWriter() to produce human-readable formatting with appropriate spacing and color codes for terminal display.

How can I pretty-print or filter JSON output from IPATool?

Pipe the JSON output to command-line tools like jq. For example, use ipatool --format json list-purchases | jq '.' for pretty-printing, or ipatool --format json list-purchases | jq '.[] | .bundleId' to extract specific fields. This works because the JSON output consists of valid, newline-delimited JSON objects.

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