CLI Reference

Every banatie command: exact syntax, what it does, and where to read more.

Quick Start

From nothing to a generated image on disk. Run these in order — no install needed (npx fetches the CLI on first use):

Account → project key → first image

# 1. Sign up — emails you a one-time login command
npx @banatie/cli signup [email protected]

# 2. Log in with the org slug + token from that email
npx @banatie/cli auth login <org-slug> <bnt_boot-token>

# 3. Create a project and link this folder to it
npx @banatie/cli project new my-app
npx @banatie/cli project connect my-app --root .

# 4. Mint a project API key into a local .env (BANATIE_API_KEY)
npx @banatie/cli project issue-key --write-env .env

# 5. Generate — reads BANATIE_API_KEY from .env, downloads the image here
npx @banatie/cli generate "a friendly robot waving hello" --output-dir .

Steps 1–4 are management commands (your org login); step 5 is a product command (your project BANATIE_API_KEY). The two contexts are explained just below.

Install

No install needed: run any command with npx (Node 18 or newer):

Run without installing

npx @banatie/cli <command>

Prefer a global banatie binary? Install once:

Global install

npm install -g @banatie/cli

Examples below use npx @banatie/cli. With a global install, drop the npx @banatie/cli prefix and use banatie. Run --help on any command, and --version to print the CLI version.

Two Auth Contexts

The CLI keeps two authentication contexts strictly separate:

Management commands (signup, auth, project) use your organization login — the token stored by auth login. The optional --org <slug> flag lives only here and picks which logged-in org to act on (omit it when only one org is logged in).

Product commands (generate, generation, flow, image, scope) use a project API key sent as X-API-Key, resolved from the environment or a local .env (BANATIE_API_KEY). They carry no org concept and no --org flag.

Auth Commands

These manage your organization login. How the login email works and where the token lives is covered in the authentication walkthrough.

Command	What it does
`signup <email> [--org-name <name>]`	Request the one-time login email for your address
`auth login <org-slug> <bnt_boot-token>`	Exchange the emailed one-time token for a stored org profile
`auth status [--org <slug>]`	Show the active org profile (token preview only)
`auth logout [--org <slug>]`	Remove the local profile; the server token stays valid
`auth rotate [--org <slug>]`	Replace the org token; the old one stops working
`auth revoke [--org <slug>]`	Invalidate the token on the server and remove the local profile

Request a login email, then run the one-time command it contains:

npx @banatie/cli signup [email protected]
# ...check your inbox, then:
npx @banatie/cli auth login acme <bnt_boot-token>

Output

Logged in to organization "acme" ([email protected]).
Token: bnt_org_...4f2a1c
Config: ~/.banatie/config.json

Project Commands

Command	What it does
`project new <slug> [--org <slug>]`	Create a project (mints its first key server-side)
`project list [--org <slug>]`	List the organization’s projects (metadata only)
`project connect <slug> [--root <path>]`	Link a local directory to a project (.banatie/project.json)
`project issue-key [<slug>] [--write-env <path>]`	Mint a project API key (auto-detects the connected project)
`project delete <slug> [<one-time-token>]`	Two-step, email-confirmed project delete
`project status`	Health-check the connected project from the current folder

Create a project, link your repo, and mint a key into .env:

Set up a project

npx @banatie/cli project new my-app
npx @banatie/cli project connect my-app --root .
npx @banatie/cli project issue-key --write-env .env

project connect writes .banatie/project.json (no key). project issue-key mints a fresh key on every call; with --write-env it upserts BANATIE_API_KEY into the file. Run it from a connected directory to omit the slug. Keep .banatie/ and your .env out of version control.

Product Commands

Product commands authenticate with your project API key (BANATIE_API_KEY from the environment or a local .env). Each group maps to a REST resource — follow the linked API reference for full request/response detail.

generate & generation

Generate an image

npx @banatie/cli generate "a watercolor fox" --output-format asset --output-dir ./art

Command	What it does
`generate <prompt>`	Create an image from a prompt (alias of generation create)
`generation create <prompt>`	Canonical create (inline prompt or --prompt-file)
`generation get <id>`	Fetch a generation; download or print its image
`generation list`	List generations (--flow, --status, --limit, --offset)
`generation update <id>`	Change prompt/aspect-ratio (regenerates) or flow
`generation regenerate <id>`	Regenerate with identical params
`generation delete <id>`	Delete a generation

Full parameters and responses: Generations API.

flow

Command	What it does
`flow list`	List flows with counts
`flow get <id>`	One flow with its counts and aliases
`flow generations <id>`	List a flow’s generations
`flow images <id>`	List a flow’s images
`flow alias set <id> <@alias> <imageId>`	Assign a flow-scoped alias
`flow alias remove <id> <@alias>`	Remove a flow-scoped alias
`flow regenerate <id>`	Regenerate the flow’s most recent generation
`flow delete <id>`	Delete a flow (cascade)

Flows are created lazily by generate / image upload (there is no flow create). Full detail: Flows API.

image

Command	What it does
`image upload <file>`	Upload an image ≤5MB (--alias, --flow, --flow-alias, --meta)
`image list`	List images (--flow, --source, --alias, --limit, --offset)
`image get <id-or-alias>`	Fetch an image; download or print it (--flow to resolve an alias)
`image update <id-or-alias>`	Update focal point / meta
`image alias <id-or-alias> <@alias \| --remove>`	Assign or remove a project alias
`image delete <id-or-alias>`	Delete an image

Identifiers accept a UUID or an @alias. Full detail: Images API.

scope

Command	What it does
`scope create <slug>`	Create a live scope (--allow-new-generations, --limit, --meta)
`scope list`	List live scopes
`scope get <slug>`	One scope with settings/stats
`scope update <slug>`	Update settings / meta
`scope regenerate <slug> [--image <id>]`	Regenerate one image or all images in the scope
`scope delete <slug>`	Delete a scope (cascade)

Manage live scopes and their images. Full detail: Live Scopes API.

config

Command	What it does
`config init [--force]`	Scaffold .banatie/config.json with current defaults
`config path`	Print which .banatie/config.json is in effect

Local, no network: manage the per-project defaults file described under Configuration.

Shared Output Flags

Product commands share a small set of flags. Their defaults come from .banatie/config.json, and a flag always wins over config:

Flag	Default	Purpose
`--output-format <asset\|url>`	`asset`	asset downloads image bytes; url prints the image URL only
`--output-dir <path>`	project root	Where asset-mode files are written
`--model <model>`	API default	Generation model to use
`--json`	—	Print raw JSON instead of formatted text
`--quiet`	—	Suppress non-essential output
`--config <path>`	discovery	Use an explicit .banatie/config.json

Configuration

Variable	Default	Purpose
`BANATIE_API_KEY`	—	Project API key for product commands (env or a local .env)
`BANATIE_API_BASE_URL`	`https://api.banatie.app`	Backend override (dev/testing)
`BANATIE_HOME`	`~/.banatie`	Where the CLI stores its login profiles

Three files hold all CLI state:

~/.banatie/config.json (global): your login profiles — backend URL, org slug, email, the org token, and timestamps. This is the only place the permanent org token lives.

.banatie/project.json (per repo): the project link written by project connect — org/project slug and id. It holds no keys; keep it out of version control.

.banatie/config.json (per repo): reusable command defaults — outputDir, outputFormat, model. Scaffold it with config init. This is not a secret store — the API key never lives here.

Point the CLI at a dev backend by exporting BANATIE_API_BASE_URL, e.g. BANATIE_API_BASE_URL=http://localhost:3000 npx @banatie/cli auth status --org acme.