> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Sign in once, then generate images, video and audio from the terminal.

The `blon` command uses your Blon account and spends its credits. It is also what [Skills](https://docs.blon.ai/how-to/skills.md) run.

## Install

> [!NOTE]
>
> `@blon/cli` has not been published to npm yet. These commands work once the first release is out.

```bash theme={null}
npm i -g @blon/cli
# or run without installing
npx @blon/cli --help
```

Node.js 22 or later is required.

## Sign in

```bash theme={null}
blon auth login
blon auth status
blon auth logout
```

`blon auth login` uses the device authorization flow. It prints a URL and a code and opens your browser on the approval page; approve the request while signed in to Blon. Over SSH or in a container the browser does not open, so open the printed URL on any device.

The session is saved in `~/.config/blon/credentials.json` (mode `0600`). Set `BLON_CONFIG_DIR` to keep it elsewhere. `blon whoami` prints the account, site, workspace and balance.

## First generation

```bash theme={null}
blon models list
blon models get nano-banana-2-lite
blon generate nano-banana-2-lite --prompt "A ceramic teapot on a linen table" --wait --out ./out
```

Each model input becomes a flag: `--<inputId> <value>`. `blon models get <id>` lists them. List inputs take comma-separated values or a repeated flag. Write negative numbers as `--seed=-1`.

## Media inputs

A media flag takes a local file path, an `https://` URL, or an asset id. Local files are uploaded for you (images up to 20,000,000 bytes, other files up to 52,428,800 bytes).

```bash theme={null}
# local file (uploaded automatically)
blon generate seedance-2.0 --prompt "Slow push-in" --firstFrame ./frame.png --wait --out ./out
# https URL
blon generate seedance-2.0 --prompt "Slow push-in" --firstFrame https://example.com/frame.png --wait
# asset id
blon generate seedance-2.0 --prompt "Slow push-in" --firstFrame <asset-id> --wait
```

## Voice inputs

A voice flag takes a preset voice id from the model (`blon models get <id>` shows the allowed ones), or `workspace:<voiceId>` for a voice in your workspace.

```bash theme={null}
blon generate minimax-speech-2.8-hd --text "Welcome to Blon." --voice Wise_Woman --wait
```

## Commands

| Command | What it does |
| - | - |
| `blon auth login` / `status` / `logout` | Sign in, show the signed-in account, sign out |
| `blon whoami` | Account, site, workspace and balance |
| `blon balance` | Balance only |
| `blon models list` / `models get <id>` | Models and their inputs |
| `blon estimate <model> [--<input> <value>]…` | Estimate without submitting |
| `blon generate <model> [--<input> <value>]…` | Submit a job |
| `blon jobs list` / `get <id>` / `wait <id>` / `cancel <id>` | Work with jobs |
| `blon assets list` / `assets download <id>` | Assets in the workspace |
| `blon workflows get <revisionId>` / `workflows run <revisionId>` | [Workflows](https://docs.blon.ai/how-to/workflows.md) |
| `blon usage [--timeframe <t>] [--start <iso>] [--end <iso>]` | Usage report |

`generate` flags:

| Flag | Meaning |
| - | - |
| `--wait` | Poll until the job finishes |
| `--timeout <duration>` | How long `--wait` waits, such as `90s`, `10m`, `1h`. Default `10m` |
| `--out <dir>` | Download the artifacts as `<jobId>-<n>.<ext>` |
| `--idempotency-key <key>` | Reuse a key when retrying; a random one is sent otherwise |
| `--webhook-url <url>` | Send a [webhook](https://docs.blon.ai/how-to/webhooks.md) when the job ends |

If a wait is interrupted, resume it with `blon jobs wait <id>` instead of submitting again.

Global flags: `--json`, `--workspace <slug>`, `--base-url <url>`, `--help`, `--version`.

## JSON output

With `--json`, stdout holds only the response JSON; progress goes to stderr. With `--wait --json` that is the whole finished job.

```bash theme={null}
blon generate nano-banana-2-lite --prompt "A ceramic teapot" --wait --json
```

## Exit codes

| Code | Meaning |
| - | - |
| `0` | Success |
| `1` | Usage error, not signed in, 401 or 403, or network error |
| `2` | The job failed, was canceled, or the wait timed out |
| `3` | Insufficient balance |

## Environment variables

| Variable | Meaning |
| - | - |
| `BLON_API_KEY` | A `blon_api_` key. Takes precedence over the saved sign-in |
| `BLON_BASE_URL` | Site to talk to. Default `https://blon.ai`; `--base-url` overrides it |
| `BLON_CONFIG_DIR` | Where the sign-in is stored. Default `~/.config/blon` |

## CI

For unattended runs, set `BLON_API_KEY` and skip `blon auth login`. The CLI then spends the key's workspace balance.

```bash theme={null}
export BLON_API_KEY=blon_api_...
blon generate nano-banana-2-lite --prompt "A ceramic teapot" --wait --json
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.