CLI commands

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

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:

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:

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.

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.

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:

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 for the field each layer type accepts.

Examples

# 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.

bannerify whoami

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:

{
  "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:

{
  "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:

{
  "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

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