CLI

The blon command uses your Blon account and spends its credits. It is also what Skills run.

Install

@blon/cli has not been published to npm yet. These commands work once the first release is out.

npm i -g @blon/cli
# or run without installing
npx @blon/cli --help

Node.js 22 or later is required.

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

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).

# 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.

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

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.

export BLON_API_KEY=blon_api_...
blon generate nano-banana-2-lite --prompt "A ceramic teapot" --wait --json

Get started

Concepts

How-to

Models

Help

Install

First generation

Media inputs

Voice inputs

Commands

JSON output

Exit codes

Environment variables

CI

​Install

​Sign in

​First generation

​Media inputs

​Voice inputs

​Commands

​JSON output

​Exit codes

​Environment variables

​CI

Install

Sign in

First generation

Media inputs

Voice inputs

Commands

JSON output

Exit codes

Environment variables

CI