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