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

> Learn how to change IPATool output format to JSON or text mode using the global --format flag. Easily switch between human-readable and machine-readable data.

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

---

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

```go
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`](https://github.com/majd/ipatool/blob/main/cmd/output_format.go) as a custom flag type based on `enumflag.Flag`:

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

```go
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`](https://github.com/majd/ipatool/blob/main/cmd/common.go), the switch statement determines whether to use zerolog for JSON or the standard text writer:

```go
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:

```bash
ipatool list-purchases

```

Explicit text output (equivalent to default):

```bash
ipatool --format text list-purchases

```

JSON output for scripting and filtering:

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

```

Combined with other command-line options:

```bash
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`):

```bash
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`](https://github.com/majd/ipatool/blob/main/cmd/root.go) using `PersistentFlags().VarP()`.
- The `OutputFormat` enum in [`cmd/output_format.go`](https://github.com/majd/ipatool/blob/main/cmd/output_format.go) defines the available values, with text as the zero-value default.
- Runtime parsing in [`cmd/common.go`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/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.