Skip to main content
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

To run a command without installing the package:

Save your API key

Store the key once, the way you would with git config:
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

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

Generate an image

The CLI saves the image to out.png and prints its path and size:
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:
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

A PDF takes the same --modifications value:

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=-:
For a batch, send each result to its destination as it finishes:
To pass a long array of modifications, keep it in a file or pipe it in:
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:
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

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