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> [--model <lane>/<model>] | Generate through a saved or explicit image lane. |
ima2 edit <file> --prompt <text> | Edit an existing image. |
ima2 multimode <prompt> | Multi-image SSE generation (streams phase / partial / image). |
ima2 video <prompt> [--model <lane>/<model>] | Generate through a saved or explicit Grok/MCP video lane. |
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. |
gen accepts --provider <oauth|api|grok|grok-api|agy|gemini-api|runway|higgsfield>,
--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>.
Generate-mode video accepts --provider <grok|grok-api|runway|higgsfield>.
Grok video commands also accept --planner-model <name> (default
grok-4.5; Grok 4.3 remains a compatibility override) 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 api/gpt-5.4 --reasoning-effort high
ima2 grok login
ima2 gen "a cinematic neon city" --model grok/grok-imagine-image-quality
ima2 video "a cat playing piano" --model grok/grok-imagine-video-1.5 --duration 5 --resolution 720p
ima2 video "animate this scene" --model grok/grok-imagine-video-1.5 --ref scene.png --planner-model grok-4.5 --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 directFail-closed generation contract
Bare ima2 gen and generate-mode ima2 video do not select a provider.
Configure ima2 defaults set image|video <lane>/<model>, or pass
--model <lane>/<model> for that call. A bare model ID is accepted only when it is
unique across lanes. Core image aliases work in the model segment, such as oauth/luna.
--provider auto was removed from these two commands and returns
PROVIDER_AUTO_REMOVED.
Core lanes are oauth, api, grok, grok-api,
agy, and gemini-api. Subscription-backed MCP lanes are
runway and higgsfield. MCP jobs submit asynchronously and the CLI waits
for SSE completion; they support one output per command, require generated-gallery filenames for
--ref, and reject unsupported core-only flags with FLAG_NOT_SUPPORTED.
--json, failures print exactly one
{"ok":false,"code":"...","message":"..."} document. Exit 2 means a
user-fixable target or flag error (including NO_DEFAULT_MODEL), exit 3 means the server
is unreachable, and exit 1 means generation failed after submission.
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 models [--kind image|video] [--lane <lane>] [--json] | Live lane status, model IDs, and capability summaries. JSON is stable as { ok, kinds: { image: [], video: [] } }. |
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 pingHealth-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. ima2 defaults set image|video <lane>/<model>Validate and persist the fail-closed CLI generation target. ima2 defaults reset image|videoRemove the saved CLI target; the next bare generation fails closed again.
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.