Bannerify Docs
Search docs.../
DiscordDashboard
DocumentationAPI ReferenceSDK
Navigation
DocumentationAPI ReferenceSDK

CLI

Generate from the terminal

Learn how to install the Bannerify CLI and generate images and PDFs from your shell.

The Bannerify CLI generates images and PDFs from a terminal. It uses the same templates and API keys as the REST API, so you can render a file with one command and pass the result to another tool. This page is for developers who work in a shell, and for scripts and agents that call one.

Use the CLI when you want to:

  • Render a file during a build, a deploy, or a cron job.
  • Run many renders from a shell script.
  • Let an agent or a script create files without writing code.

Before you start

  • A Bannerify account with at least one template. Copy its id with Copy Template ID in the menu of the template card.
  • An API key. Create one on the API Keys page with New API key. Authenticate requests has the steps.
  • Node.js 18 or later.

Install

npm install -g bannerify-cli

To run a command without installing the package:

npx bannerify-cli <command>

Save your API key

Store the key once, the way you would with git config:

bannerify config set apiKey YOUR_API_KEY

In an interactive terminal, you can also run bannerify with no arguments when no key is saved yet. The CLI asks for the key, hides what you type, checks the key, and saves it. In an interactive terminal, any command that needs a key starts the same setup when it finds none. In a script, the command fails at once instead.

The CLI writes the key to $XDG_CONFIG_HOME/bannerify/config.json, or to ~/.config/bannerify/config.json when XDG_CONFIG_HOME is not set. It sets 0600 permissions on the file.

Check the key

bannerify whoami

The command prints the name and the id of the workspace, its creation date, and where the CLI found the key:

+ Authenticated as Acme
  project id: proj:xxxxxxxxxx
  created:    2026-01-14T09:12:31.000Z
  key source: config

Generate an image

bannerify create image tpl_xxx -o out.png

The CLI saves the image to out.png and prints its path and size:

+ Created image /home/dev/out.png (80734 bytes, png)

Without -o, the file is named <templateId>.<format>, for example tpl_xxx.png, and goes to the current folder.

To change the layers of the template, pass --modifications:

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

The value is a JSON array. Each entry names a layer with name and sets its fields, such as text or src. Modifications lists the fields of every layer type.

Pick the format with --format: png (default), jpeg, or webp.

Generate a PDF

bannerify create pdf tpl_xxx -o out.pdf

A PDF takes the same --modifications value:

bannerify create pdf tpl_invoice -o invoice.pdf \
  --modifications '[{"name":"total","text":"$29.00"}]'

Use it in a pipeline

The CLI keeps stdout for data and stderr for messages, so the bytes of a file pass cleanly to the next command. Write the file to stdout with --out=-:

bannerify create image tpl_xxx --out=- --quiet > out.png

For a batch, send each result to its destination as it finishes:

for id in tpl_a tpl_b tpl_c; do
  bannerify create image "$id" --out=- --quiet | rclone rcat "remote:$id.png"
done

To pass a long array of modifications, keep it in a file or pipe it in:

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

CLI commands covers JSON output and exit codes for scripts.

Key resolution

The CLI looks for the API key in this order:

  1. The --api-key flag.
  2. The BANNERIFY_API_KEY environment variable.
  3. The saved config.

You can keep one key in the config and override it for a single command or a container:

BANNERIFY_API_KEY=YOUR_OTHER_KEY bannerify create image tpl_xxx -o out.png

The base URL follows the same order: the --base-url flag, the BANNERIFY_BASE_URL environment variable, the saved config, and then https://api.bannerify.co/v1.

Configuration file

Key Purpose
apiKey The API key that the CLI sends
baseUrl The API base URL. The default is https://api.bannerify.co/v1
defaultFormat The image format when --format is absent. The default is png
outputDir The folder for the output file when --out is absent

Change the file with the config commands. CLI commands lists them.

Usage and limits

A generation from the CLI counts toward the same monthly and daily limits as the REST API and the SDKs. A request that fails does not count. Quota and limits has the details.

Next steps