# Generate from the terminal

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

Canonical: https://bannerify.co/docs/cli/overview

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](https://bannerify.co/docs/api-reference/authentication#create-an-api-key) has the steps.
- Node.js 18 or later.

## Install

```bash
npm install -g bannerify-cli
```

To run a command without installing the package:

```bash
npx bannerify-cli <command>
```

## Save your API key

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

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

```bash
bannerify whoami
```

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

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

## Generate an image

```bash
bannerify create image tpl_xxx -o out.png
```

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

```text
+ 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`:

```bash
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](https://bannerify.co/docs/essentials/modifications) lists the fields of every layer type.

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

## Generate a PDF

```bash
bannerify create pdf tpl_xxx -o out.pdf
```

A PDF takes the same `--modifications` value:

```bash
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=-`:

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

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

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

```bash
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](https://bannerify.co/docs/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:

```bash
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](https://bannerify.co/docs/cli/commands#config) 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](https://bannerify.co/docs/account/quota) has the details.

## Next steps

- [CLI commands](https://bannerify.co/docs/cli/commands)
- [Create an image](https://bannerify.co/docs/api-reference/endpoint/create-image)
- [Connect an MCP client](https://bannerify.co/docs/mcp/overview)

## Related

- [Previous: Generate files with MCP tools](https://bannerify.co/docs/mcp/tools)
- [Next: CLI commands](https://bannerify.co/docs/cli/commands)
- [Documentation index](https://bannerify.co/docs/llms.txt)