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 video edit <prompt> --video <value>`	Video-to-video edit; supports HTTPS URL, xAI file_id, data URL, or generated MP4.
`ima2 video extend <prompt> --video <value>`	Extend a video from its last frame; extension duration is 2–10s.
`ima2 video frame <generated-file>`	Extract a PNG frame from a generated MP4.
`ima2 video analyze <generated-file>`	Analyze first/last frames from a generated MP4; remote URLs are rejected.
`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|grok-api|agy|gemini-api>, --reasoning-effort (none, low, medium, high, xhigh), --web-search / --no-web-search, --model (GPT models, grok-imagine-image, grok-imagine-image-quality, nano-banana-2, nano-banana-pro), --mode, --moderation, --ref <file> (repeatable, up to 5), -q low|medium|high, -n <count>, and -o <file>. Video commands also accept --planner-model <name> (default grok-4.3) and --storyboard for character/scene continuity across sequential clips.

ima2 grok login uses the manual-paste login flow by default.

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 video "animate this scene" --ref scene.png --planner-model grok-4.3 --storyboard
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`	Print the core CLI skill (`skills/ima2/SKILL.md`).
`ima2 skill front`	Print the frontend implementation skill (`skills/ima2-front/SKILL.md`).
`ima2 skill uiux`	Print the design direction skill (`skills/ima2-uiux/SKILL.md`).
`ima2 skill ls`	List all available packaged skills.
`ima2 skill [front\|uiux] --json`	JSON wrapper around a skill (for agent consumption).
`ima2 skill [front\|uiux] path`	Print the resolved skill file path.
`ima2 skill [front\|uiux] refs`	List reference modules with line counts.
`ima2 skill [front\|uiux] ref <name>`	Print one reference module (e.g. `motion`, `design-isms`).
`ima2 skill [front\|uiux] --with-refs`	Bundle SKILL.md + all reference modules into one output.
`ima2 skill install --dir <path>`	Install all skills to the agent's skill directory.
`ima2 skill install --tmp`	Install to `$TMPDIR/ima2-skills/` (ephemeral fallback).
`ima2 capabilities --json`	Supported commands, model/quality/reasoning values, advisory limits.
`ima2 defaults --json`	Effective model/reasoning defaults (server, falling back to local config).

Three packaged skills. ima2 skill (core) covers CLI and prompting. ima2 skill front adds production-grade frontend engineering: asset pipeline, motion/video, responsive, a11y, anti-slop, with 28 reference files. ima2 skill uiux adds design direction discovery: image-first ism workflow, UX states, product personalities, with 18 reference files.

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