> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.bannerify.co/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI commands

> Reference for every Bannerify CLI command, option, and exit code.

The Bannerify CLI has three commands: `config`, `create`, and `whoami`.

```text theme={null}
bannerify <command> [options]
```

Run `bannerify --help`, or `bannerify <command> --help`, to print the options of a command in your terminal.

## Global flags

| Flag | Description |
| - | - |
| `-v, --version` | Print the CLI version |
| `-h, --help` | Print help. Works on every subcommand |

## config

Manage the settings the CLI keeps between runs. The commands work like `git config`.

| Command | Description |
| - | - |
| `bannerify config set <key> [value]` | Set a value. Without `value`, the CLI prompts for it |
| `bannerify config get <key>` | Print one value |
| `bannerify config list` | Print all values |
| `bannerify config delete <key>` | Remove a value |

### Keys

| Key | Description |
| - | - |
| `apiKey` | The API key the CLI sends to the API |
| `baseUrl` | The API base URL. Defaults to `https://api.bannerify.co/v1` |
| `defaultFormat` | The image format used when `--format` is absent. Defaults to `png` |
| `outputDir` | The directory that holds the output file when `--out` is absent |

The `apiKey` value is masked in the output of `get` and `list`. Add `--show` to reveal it:

```bash theme={null}
bannerify config get apiKey --show
```

`config set apiKey` prompts for the key without echoing it. Add `--show` to the prompt when you paste a long key and want to see it:

```bash theme={null}
bannerify config set apiKey
bannerify config set baseUrl https://api.bannerify.co/v1
bannerify config set defaultFormat webp
bannerify config set outputDir ./renders
bannerify config delete defaultFormat
```

The config file lives at `$XDG_CONFIG_HOME/bannerify/config.json`, or `~/.config/bannerify/config.json`. The CLI creates it with `0600` permissions.

## create

Generate an image or a PDF from a template.

```bash theme={null}
bannerify create image <templateId> [options]
bannerify create pdf <templateId> [options]
```

### Options

| Option | Description |
| - | - |
| `-o, --out <path>` | Output file path. Use `--out=-` to write the file bytes to stdout |
| `--format <png\|jpeg\|webp\|svg>` | Image format. Image only. Defaults to `png`, or to `defaultFormat` |
| `--modifications '<json>'` | JSON array of layer modifications |
| `--modifications-file <path>` | Read the modifications array from a JSON file. Use `-` for stdin |
| `--api-key <key>` | Override the configured API key |
| `--base-url <url>` | Override the API base URL |
| `--json` | Print a machine-readable result on stdout |
| `-q, --quiet` | Suppress messages that are not errors |

Without `--out`, the CLI writes the file to `<templateId>.<format>` in the current directory, or in `outputDir` when you set it.

### Modifications

`--modifications` takes the same array as the `modifications` field of the REST API. Each entry names a layer with `name` and sets its value.

```bash theme={null}
bannerify create image tpl_xxxxx -o out.png \
  --modifications '[{"name":"title","text":"Hello world"}]'
```

For a long array, keep it in a file and pass the path, or pipe it through stdin:

```bash theme={null}
bannerify create image tpl_xxxxx -o out.png --modifications-file ./data.json
echo '[{"name":"title","text":"From stdin"}]' | \
  bannerify create image tpl_xxxxx --modifications-file - -o out.png
```

The layer names come from the template editor. See [Template elements](/essentials/elements) for the field each layer type accepts.

### Examples

```bash theme={null}
# WebP output with one text override
bannerify create image tpl_xxxxx --format webp -o out.webp \
  --modifications '[{"name":"title","text":"Summer sale"}]'

# A PDF with the same layers
bannerify create pdf tpl_invoice -o invoice.pdf \
  --modifications '[{"name":"total","text":"$29.00"}]'

# Image bytes on stdout, for the next command in the pipeline
bannerify create image tpl_xxxxx --out=- --quiet > out.png
```

## whoami

Verify the API key and print the project it belongs to.

```bash theme={null}
bannerify whoami
```

```text theme={null}
Authenticated as Acme
  project id: prj_xxxxx
  created:    2026-01-14T09:12:31.000Z
  key source: config
```

`key source` reports where the key came from: `flag`, `env`, or `config`. Use it to check which key a script uses.

Run `whoami` first in a new environment. It reports an authentication problem before a long batch fails.

## Use it from a script or an agent

The CLI detects a non-interactive session. When stdin or stdout is not a terminal, or when `CI` is set, it never prompts: a missing key fails at once with the commands to fix it.

| Behaviour | Detail |
| - | - |
| Prompting | Only in an interactive terminal |
| stdout | Data only: the file bytes, or the JSON result with `--json` |
| stderr | Messages, progress, and errors |
| Key source | `--api-key`, then `BANNERIFY_API_KEY`, then the config file |

### JSON output

Add `--json` to read the result from a script. On success, `create` prints one object:

```json theme={null}
{
  "ok": true,
  "command": "create image",
  "templateId": "tpl_xxxxx",
  "format": "png",
  "path": "/home/dev/out.png",
  "bytes": 80734
}
```

`create pdf` omits `format`. `whoami` prints the project and the key source:

```json theme={null}
{
  "ok": true,
  "project": {
    "id": "prj_xxxxx",
    "name": "Acme",
    "createdAt": "2026-01-14T09:12:31.000Z"
  },
  "keySource": "config"
}
```

On an error, the command prints the error object from the API and exits with a non-zero code:

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "template tpl_xxxxx not found",
    "docs": "https://bannerify.co/docs/api-reference/errors/code/NOT_FOUND"
  }
}
```

When `--out=-` is used with `--json`, the file bytes stay on stdout. Send the file to a target that accepts a stream, or write to a path instead.

### Exit codes

| Code | Meaning |
| - | - |
| `0` | The command succeeded |
| `1` | A general error, for example a missing template or a failed request |
| `2` | An authentication error: the key is missing, invalid, or not permitted |

```bash theme={null}
if ! bannerify create image tpl_xxxxx -o out.png --quiet; then
  echo "generation failed with code $?"
fi
```

## Troubleshoot

| Symptom | Cause | Fix |
| - | - | - |
| `No API key found` | The session is not interactive and no key is set | Set `BANNERIFY_API_KEY`, or run `bannerify config set apiKey` in a terminal |
| Exit code `2` | The key is invalid, or the project lost access | Run `bannerify whoami`, then create a new key in [API keys](/account/project) |
| Exit code `1` with `NOT_FOUND` | The template id does not exist in the project | Copy the id from the template list in the dashboard |
| Exit code `1` with `BAD_REQUEST` | A modification names a layer that the template does not have | Check the layer names in the template editor |
| Empty output file | `--out=-` sent the bytes to stdout | Redirect stdout to a file: `--out=- > out.png` |

## Learn more

* [Generate from the terminal](/cli/overview)
* [Errors](/api-reference/errors/introduction)
* [Quota and limits](/account/quota)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.