Bannerify CLI

Command-line interface for Bannerify — generate images and PDFs at scale, straight from your terminal. Built for developers, agents, and automation.

Install

npm install -g bannerify-cli
# or use on demand
npx bannerify-cli <command>

Quick start

# 1. Save your API key (persisted, like git config)
bannerify config set apiKey ban_xxxxxxxxxxxx

# 2. Verify it works
bannerify whoami

# 3. Generate an image from a template
bannerify create image tpl_xxxxx -o out.png

# 4. Generate a PDF
bannerify create pdf tpl_xxxxx -o out.pdf

Running bannerify with no config in an interactive terminal launches a guided onboarding that validates your key and saves it for you.

Configuration

The API key (and other settings) are stored persistently at $XDG_CONFIG_HOME/bannerify/config.json (or ~/.config/bannerify/config.json). The file is created with 0600 permissions.

bannerify config set <key> [value]   # set a value (prompts if value omitted)
bannerify config get <key>           # print a value (apiKey masked; --show reveals)
bannerify config list                # list all values
bannerify config delete <key>        # remove a value

Config keys: apiKey, baseUrl, defaultFormat, outputDir.

API key resolution

The CLI resolves your API key in this order:

1. --api-key flag
2. BANNERIFY_API_KEY environment variable
3. persisted config (apiKey)

This makes it easy to override per-command or per-environment without changing global config.

Create images & PDFs

bannerify create image <templateId> [options]
bannerify create pdf   <templateId> [options]

Options:

| Option | Description | | --- | --- | | -o, --out <path> | Output file path. For stdout use --out=- or -o=- | | --format <png\|jpeg\|webp\|svg> | Image format (image only; default: png) | | --modifications '<json>' | JSON array of modifications | | --modifications-file <path> | Read modifications from a JSON file (use - for stdin) | | --api-key <key> | Override the configured API key | | --base-url <url> | Override the API base URL | | --json | Output structured JSON (machine-readable) | | -q, --quiet | Suppress non-essential output |

Examples

# Image with text modification
bannerify create image tpl_xxx -o out.png \
  --modifications '[{"name":"title","text":"Hello world"}]'

# Pipe image bytes to another tool (agent-friendly)
bannerify create image tpl_xxx --out=- --quiet | base64 > out.b64

# PDF from stdin modifications
echo '[{"name":"title","text":"From stdin"}]' | bannerify create image tpl_xxx --modifications-file - -o out.png

# Use a specific format
bannerify create image tpl_xxx --format webp -o out.webp

Built for agents & automation

The CLI is designed for programmatic, parallel, and scripted use:

• Non-interactive by default in CI/pipes. When stdin/stdout is not a TTY, it never prompts; missing auth fails fast with actionable guidance.
• Structured JSON output. Pass --json to get machine-readable results on stdout.
• Stdout is data, stderr is messages. Human text goes to stderr so piping image/PDF bytes to stdout stays clean.
• Exit codes. 0 success, 1 generic error, 2 auth error (401/403).
• Environment override. Set BANNERIFY_API_KEY to skip config entirely — ideal for CI and containers.

JSON success (create image):

{"ok":true,"command":"create image","templateId":"tpl_xxx","format":"png","path":"out.png","bytes":80734}

JSON error:

{"ok":false,"error":{"code":"NOT_FOUND","message":"template tpl_xxx not found","docs":"...","requestId":"req:..."}}

Commands reference

| Command | Description | | --- | --- | | bannerify config set/get/list/delete | Manage persistent configuration | | bannerify whoami | Verify your API key and show the linked project | | bannerify create image <templateId> | Generate an image (png, jpeg, webp, svg) | | bannerify create pdf <templateId> | Generate a PDF | | bannerify --version / -v | Print the CLI version | | bannerify --help / -h | Show help (works on every subcommand) |

How it works

The CLI is built on the official bannerify-js SDK and packaged as a single bundled file for fast cold start — important when generating many images in parallel. It uses citty for commands, @clack/prompts for onboarding, and ts-pattern for result handling.

Development

bun install
bun run build       # tsup -> dist/index.js (single-file ESM bundle)
bun run typecheck   # tsc --noEmit
bun test ./test/config.unit.ts ./test/modifications.unit.ts

License

MIT