Reference

CLI Commands

The ima2 CLI is a thin shell over the local server, so most commands need a running ima2 serve. The exceptions — serve, setup, doctor, status, open, reset, config, grok, skill, capabilities, and local defaults — work without a live server.

Server

Command	Description
`ima2 serve [--dev]`	Start the local web server; `--dev` enables verbose diagnostics.
`ima2 setup` / `ima2 login`	Reconfigure saved auth (interactive).
`ima2 status`	Show config and OAuth status.
`ima2 doctor`	Diagnose Node, package, config, and auth.
`ima2 doctor image-probe [--json]`	Live sanitized Responses image probes for no-image support bundles.
`ima2 open`	Open the web UI in a browser.
`ima2 grok login/status/models/proxy`	Authorize and inspect the bundled progrok runtime used by `provider: "grok"`.
`ima2 reset`	Remove saved config.

Generation

Command	Description
`ima2 gen <prompt>`	Generate from the CLI.
`ima2 edit <file> --prompt <text>`	Edit an existing image.
`ima2 multimode <prompt>`	Multi-image SSE generation (streams `phase` / `partial` / `image`).
`ima2 video <prompt>`	Video generation via Grok (SSE streaming with progress).
`ima2 node generate`	Node-mode generate (SSE; supports `--no-stream`).
`ima2 node show <nodeId>`	Read node metadata.

Generation flags include --provider <auto|oauth|api|grok>, --reasoning-effort (none, low, medium, high, xhigh), --web-search / --no-web-search, --model, --mode, --moderation, --ref <file> (repeatable, up to 5), -q low|medium|high, -n <count>, and -o <file>.

ima2 gen "a poster of a samurai cat" --model gpt-5.4 --provider api --reasoning-effort high
ima2 grok login
ima2 gen "a cinematic neon city" --provider grok --model grok-imagine-image-quality
ima2 video "a cat playing piano" --duration 5 --resolution 720p
ima2 edit input.png --prompt "make it rainy" --provider oauth --web-search
ima2 multimode "two cats playing" --max-images 2 --ref cat.png --mode direct

Agent discovery

Agents should start from the packaged skill and capability commands instead of guessing from scattered help text.

Command	Description
`ima2 skill [--json]`	Print the packaged Markdown skill (or a JSON wrapper).
`ima2 capabilities --json`	Supported commands, model/quality/reasoning values, advisory limits.
`ima2 defaults --json`	Effective model/reasoning defaults (server, falling back to local config).

Use only valid.imageModels.supported from capabilities --json for generation/default choices. limits.maxParallel is advisory queue guidance, not a server-side concurrency semaphore.

History & observability

Command	Description
`ima2 ls [--session <id>] [--favorites]`	List recent history; `--favorites` filters server-side.
`ima2 show <name> [--metadata]`	Reveal a generated asset, optionally with embedded metadata.
`ima2 metadata <file>`	Read embedded metadata from a local image.
`ima2 inflight ls [--terminal]`	List active (and optionally terminal) jobs with phase / model / prompt.
`ima2 ps` / `ima2 cancel <id>`	Aliases for `inflight ls` / `inflight rm`.
`ima2 ping`	Health-check the running server.

Config & defaults

Command	Description
`ima2 config get <key>`	Read a dotted key from the effective config (secrets redacted).
`ima2 config set <key> <value>`	Write to the file layer; rejects unknown and auth keys.
`ima2 config keys [--json]`	List writable keys and the env vars that override them.
`ima2 defaults set model <model>`	Persist the default image model across both provider paths.
`ima2 defaults set reasoning <effort>`	Persist the default reasoning effort across both provider paths.

Full reference. Most server routes have a CLI wrapper — sessions, graphs, annotations, canvas versions, the prompt library, imports, and Card News all have one, while Agent Mode (/api/agent/*) is web-UI only. Prompt builder is available as ima2 prompt build. See the complete CLI.md.

Providers & Models Configuration