This page describes the released
nika {STATUS.version}. Your binary is the
source of truth: nika --help --all lists every command, and
nika <command> --help lists that command’s flags.Commands
| Command | What it does |
|---|---|
nika (no arguments, on a terminal) | Opens the terminal Session: describe an outcome, review the proposed .nika file, yes saves it, run it runs it. nika --plain gives the same Session as plain lines; piped, bare nika prints the welcome mirror |
nika <file>.nika | The file is the command: the same as nika run <file>.nika |
nika welcome [--json] [--deep] | The mirror: what this binary contains, what this machine has (editors, local servers, key presence), and the next line to type. Its this binary block names the running nika (version, commit, installer, path) and warns when another copy on PATH differs. A provider key is reported set, never checked: the first call checks it. Offline, always exit 0. --deep audits every workflow in the workspace and folds recent runs |
nika try [slug] | See a canonical workflow work: a mock/echo rehearsal in a temporary folder, nothing written. The mock replaces the model (zero keys, no model call), not the network: a step that fetches still reaches its host. When its permits.net.http declares hosts, nika try prints them first on stderr (may reach: <hosts>), except with --quiet or a JSON output. Bare nika try lists the path and the jobs; --all lists everything; --model runs one on a real model |
nika compile [intent] [dest] | Write a workflow from an exact skeleton (--list), a bounded intent or a conservative edit (--base + --change). No destination previews; only a ready result with a destination writes (--force replaces). --json prints the result and its questions, --answer KEY=JSON_LITERAL answers one, --authoring-model <provider/name> lets a model you choose author free intent |
nika init [dir] | Found a repository for agents and editors: AGENTS.md, CLAUDE.md, NIKA.md, the .agents/skills authoring skill, Cursor rules and subagents, project MCP configs, Claude Code and Cursor hooks, .vscode/settings.json, a commented nika.yaml and workflows/01-hello.nika (the full list). --recipe, --example, --wire, --yes, --force |
nika list | Every .nika workflow below the current directory, one relative path per line |
nika check <file> | The static audit before any run: plan, models and access, cost ceiling, secret flows, types, tools, permits, the order law and the trifecta (through child workflows and the files builtins read back). - reads stdin. A registry:owner/name coordinate is refused in 0.124.3 (NIKA-REG-005, Known limits). Flags below |
nika run [file] | Run a workflow: the same audit runs first, then the live storyboard. With no file and exactly one workflow in the workspace, that one runs. Flags below |
nika test <file> | Golden test: run under the mock provider (offline, deterministic) and compare the typed outputs: with <file>.golden.json. --update pins it; --case <name> with --var key=value pins one golden per case; --at <instant> sets run.scheduled_for (Testing) |
nika inspect <file> | Static anatomy: tasks, verbs, waves, cost, permits. --format json|mermaid|dot|ascii projects the graph (graph_format: 3 for JSON); - reads stdin |
nika explain <code|file> | Teach an error code (NIKA-SEC-004), a hint kind nika check printed in brackets, or narrate a workflow file: its waves, its cost before a token is spent, what it touches. --json and --forecast for the file form |
nika doctor [--ping] [--json] [--verbose] | Diagnose this machine by presence only: binary, access paths, sandbox, run-signing key, local servers, keys, media backends, pricing, agent apps. The running and path rows name the running binary (resolved path, version, commit, installer), what typing nika runs, and every other nika on PATH with the version it reports and a safe repair hint; each copy is asked --version under a two-second deadline, from /, with no credential in its environment. --json adds running, others[] and others_truncated. --ping connects to configured local ports (300 ms cap) and reads their model lists with one bounded GET: no inference, no download. Prints fixes, never applies them |
nika catalog [--json] | The embedded provider and model catalog (catalog_version: 1). --tools lists the builtin tools instead (tools_version: 1) |
nika spec [--canon] [--schema] | The embedded specification identity; --canon prints the canon, --schema the workflow JSON Schema, --schema --project the project file’s |
nika wire <target> | Add Nika’s read-only MCP server to one agent client, idempotently: any client nika wire --help lists, detected (the clients this machine shows; preview with --dry-run, the recommended door) or all (previewed, then confirmed or --yes). Client table |
nika mcp | Run the read-only MCP server over stdio, or Streamable HTTP with --transport http (loopback port 8123 by default). nika mcp approve <server> pins the current tool definitions of a server declared in .nika/mcp_servers.json |
nika lsp | Run the language server over stdio |
nika dap | Debug Adapter Protocol server over stdio: step forward and back through a recorded run in any DAP client. Replay re-renders, never re-executes |
nika model pull|serve|list|rm | Built-in local inference: pull downloads a GGUF from the Hugging Face Hub into ~/.nika/models (it prints the size first and asks to confirm 2 GiB and over), serve starts an OpenAI-compatible server on 127.0.0.1:8712 (Qwen3-family models in 0.124.3), list and rm manage the disk (Local models) |
nika key init|trust|rotate|align | The run-signing key: init mints it once per machine, trust prints the public key and its fingerprint to enroll elsewhere, rotate retires it (old records stay verifiable), align copies a Linux Secret Service key to ~/.nika/keys/ for nika serve and the SDK, and refuses on macOS in 0.124.3 (Seal your runs) |
nika sign <file> | Sign a workflow file: mints <file>.minisig; --check verifies it. nika run --require-signature refuses an unsigned file |
nika trace <command> | Read a run’s record (below) |
nika arm | Read the project’s arm: registry and print each beat’s readiness and next slots, scheduling nothing. fire fires one due beat, migrate upgrades old sidecars into the chained ledger, disarm teaches the disarm gesture; --emit launchd|systemd writes the OS units; --json for programs (nika arm reference) |
nika serve | The resident firer of the arm: registry. --once fires what is due once and exits; --dry runs nothing and prints each beat due now, and stays resident unless combined with --once. In a project that arms nothing, both say so, with the --bind command and the token recipe, and exit 0. With --bind, --workflows and --token-file it also serves authenticated HTTP: jobs, SSE, cancellation, trace verification, a settled job’s artifacts, workflows, schedules, compile and OpenAPI. --state-root, --run-cost-ceiling (1 USD per job by default), --allow-remote, --authoring-model, --sessions (the Session under /v1/sessions), --cost-review (Server surfaces) |
nika completions <shell> | Generate shell completions for bash, zsh, fish, elvish or powershell (setup) |
nika guard | The judge behind the agent hooks nika init installs: reads a hook payload or a command line, audits every nika run it finds, and answers allow or deny without executing anything. Agents never type it |
nika serve cost flags
| Flag | What it does |
|---|---|
--run-cost-ceiling <USD|none> | Server default per-job ceiling, 1 USD unless explicitly disarmed with none. A standing rule does not override it. |
--cost-review | Enable the one-time review endpoints; advertised as costReviewV1 and costReviewV2. Separate from a standing rule. |
--cost-policy <RULE> | Repeatable startup authorization for a named unpriced HTTPS OpenAI-compatible text route: PROVIDER/MODEL:requests=N,output-tokens=N,timeout=SECONDS,runs=N/PERIOD. Optional request-bytes=N and paired input-usd=USD,output-usd=USD. Covered runs need no per-run review; /health lists costStandingPolicyV1. Without declared prices, every binding USD ceiling must be absent; with them, the declared worst case must fit. See Standing cost rules for bounds, schedules and recovery. |
nika trace commands
With no path, they read the workspace’s latest trace under .nika/traces/.
| Command | What it does |
|---|---|
nika trace ls [--json] | The trace store: age, size, workflow, final state (ls_version: 1) |
nika trace show | The run’s final card |
nika trace replay [--speed N] | Re-render the run live, compressed 6× by default; never re-executes |
nika trace outputs [--json] | Each task’s output with its verb, duration and tokens (outputs_version: 2) |
nika trace peek <trace> <task> | One task’s full output and identity; --raw prints the exact value |
nika trace verify [--json] [--sealed] [--anchored] [--replay <fresh>] | Walk the hash chain, then the proof ladder: OK, SEALED, ANCHORED, REPLAYED (Traces) |
nika trace evidence [-o dir] [--full] | Export the evidence pack: journal, manifest, receipt and VERIFY.md (redacted by default) |
nika trace receipt explain <file> | A readable projection of a receipt (a reading, never a proof) |
nika trace export <trace> | The journal as OTLP/JSON lines, with GenAI attributes, for Jaeger or any OTLP collector |
nika trace cost | This project’s unknown cost exposures, as data (cost_inspect_version: 1) |
nika trace reproduce | Compare a recorded journal with a fresh one and classify each task |
nika trace session | The run digest: waves, the task others waited for, spend by verb |
nika trace flow | Which output fed which task, with recorded sizes |
nika trace rm | Remove traces by name, --older-than <duration> or --all; a paused trace needs --force |
nika trace anchor | Notarize the journal head outside the journal, on the public Sigstore Rekor log with an RFC 3161 timestamp. A network act: running it is the opt-in |
nika run flags
| Flag | What it does |
|---|---|
--max-cost-usd <USD> | The run’s budget over metered spend. A cost floor above it refuses to start (exit 2, NIKA-1709); the call that crosses it mid-run completes, then the run fails NIKA-1704. Local and mock models are never blocked. nika guard denies a priced run without it. A cloud model the catalog cannot price is refused before any call, with or without the flag (exit 3, price unknown: …, no NIKA- code), unless an interactive terminal run confirms its one-time cost review; --max-cost-usd 0 refuses it there too. Paid images and speech are billed from a dated price table, and under the flag a paid media call the table cannot price (OpenAI’s default voice gpt-4o-mini-tts, gpt-image-1.5, gpt-image-1-mini, an unlisted id) is refused before the run starts (NIKA-1709; paid media) |
--access <class|seat> | Pin the access path: a class (local, mock, harness, oauth, api) or a harness seat (claude-code, codex, copilot, gemini-cli, grok-build, kimi-code, opencode, qwen-code). An unsatisfied pin refuses and never substitutes |
--model <provider/name> | Replace the workflow’s default model: only; task pins and child workflows keep theirs. --model mock/echo puts the mock, which makes no model call, in that default’s place; pinned tasks, child workflows and the run’s other effects stay real, and a fetch still reaches its host |
--var key=value | Set an inputs: value (repeatable): overrides a default:, satisfies required: true, parsed as JSON when it parses, unknown keys refused. With --json, a refusal carries its code: unknown_input, input_type_mismatch, malformed, env_unset, env_undeclared_in_ci or env_name_missing |
--inputs-json - | Bind literal JSON inputs from stdin (an object, at most 1 MiB): no coercion, no @env lookup |
--output json | Print the typed outputs: as one JSON object on stdout |
--json | Machine NDJSON: one event per line, ending with run_settled (or one refusal object) |
--dry-run | Plan only, zero effects; with --json, one plan object (plan_version: 1). A task the run’s seat would refuse (NIKA-432, NIKA-465) is refused here too, with the lines nika check blocks run ready on (exit 2) |
--resume <trace> | Resume from a recorded trace: matching successes are skipped (task_cache_hit); the chain is verified first (Resume) |
--answer task=value | Answer a nika:prompt gate (repeatable); without --resume it pre-answers the fresh run |
--from <task> | With --resume: re-run this task and everything downstream |
--resume-compat <version>, --resume-unverified | Named opt-outs for resuming across engine versions or from an edited trace |
--task <task> | Run one task and its upstream only; the whole file is still audited |
--require-signature | Refuse an unsigned or badly signed workflow |
--cost-review-stdio | Negotiate a one-time cost review over stdio, for a host that implements it |
--no-trace-file, --no-gc | Skip the run’s journal (NIKA_NO_TRACE_FILE for every run); skip trace collection |
--no-progress, --quiet, --no-outputs | Rendering: one final frame, the verdict card only, no per-task output previews |
nika check flags
| Flag | What it does |
|---|---|
--json | The machine report (report_version: 1): clean, verdicts.{valid, access_ready, capacity_fit, run_ready, blockers, network_tasks}, findings, permits, cost, requirements, risk_grade (Machine surfaces) |
--fix | Apply the machine-applicable repairs, then audit again: near-miss renames (field, tool, arg, reference), with: hoists (NIKA-VAR-021) and retired-form migrations (needs:, depends_on, vars:, a string exec: …). Other findings stay yours |
--infer-permits | Print the tightest permits: block the file needs |
--native-strict | Fail while any native-first hint remains (an exec: a builtin probably covers) |
--profile advisory|operational | operational fails a risk grade of High or above, and an unready access path |
--model <provider/name> | Price and judge as if this model replaced the envelope default |
--access <class|seat> | Judge the access plan under this pin |
--sdk-snapshot | Print the report with the execution snapshot nika serve admits |
Global flags
| Flag | What it does |
|---|---|
--color always|never|auto | Colour (auto follows the terminal, TERM, CLICOLOR_FORCE, NO_COLOR, CLICOLOR=0) |
--hyperlink always|never|auto | OSC-8 hyperlinks on printed paths |
--plain | One flag for scripts, CI and transcripts: no colour, ASCII glyphs, no hyperlinks, no animation |
--ascii | ASCII glyphs everywhere; colour stays |
Environment variables
The five local servers (Ollama, LM Studio, llama.cpp, LocalAI, vLLM) need no variable: they are keyless, with loopback defaults built in. Everything below is opt-in.| Variable | What it does |
|---|---|
MISTRAL_API_KEY | Mistral |
SCALEWAY_API_KEY | Scaleway Generative APIs |
ANTHROPIC_API_KEY | Anthropic |
OPENAI_API_KEY | OpenAI |
GEMINI_API_KEY | Google Gemini |
DEEPSEEK_API_KEY | DeepSeek |
XAI_API_KEY | xAI |
GROQ_API_KEY | Groq |
OPENROUTER_API_KEY | OpenRouter |
HF_TOKEN | Hugging Face (also authenticates gated nika model pull repositories) |
NVIDIA_API_KEY | NVIDIA |
MOONSHOT_API_KEY | Moonshot (Kimi) |
NIKA_<ID>_API_KEY | Wins over the vendor variable for that provider, for example NIKA_OPENAI_API_KEY |
NIKA_<ID>_BASE_URL | A complete endpoint override for that provider, for example NIKA_OPENAI_BASE_URL for any OpenAI-compatible server; for a local provider, OLLAMA_HOST works too |
ELEVENLABS_API_KEY | ElevenLabs speech (NIKA_ELEVENLABS_API_KEY wins when set) |
NIKA_IMAGE_LOCAL_URL · NIKA_TTS_LOCAL_URL | Base URL of a local OpenAI-compatible image or speech server |
NIKA_SANDBOX | auto (default), require or off (an attested waiver) (Servers) |
NIKA_KEYCHAIN | off keeps the run-signing key out of the OS keychain (key files in ~/.nika/keys/) |
NIKA_RUN_KEY_FILE · NIKA_RUN_PUB_FILE | An explicit run-signing key pair, for CI or a server, both set: runs seal with it, and nika trace verify and nika serve weigh its public half first (after --key) |
NIKA_TRACE_KEEP · NIKA_TRACE_MAX_AGE_DAYS · NIKA_TRACE_BUDGET_MB | Trace retention: traces kept per workflow, maximum age, total size |
NIKA_NO_TRACE_FILE | Any non-empty value skips the run journal for every run |
NIKA_TUI | 0 opens the Session as plain lines; inline keeps finished blocks in your scrollback |
NIKA_MCP_TOKEN | Bearer token for nika mcp --transport http behind a proxy |
NIKA_BIN | The absolute engine path the TypeScript SDK should use |
nika doctor reports set or unset and
never prints a value.
Exit codes
| Code | nika run | nika check |
|---|---|---|
0 | the run settled | the report holds (clean) |
1 | a task failed and the run settled failed (also a budget stop, NIKA-1704) | never |
2 | the file: findings, or a cost floor above --max-cost-usd (NIKA-1709) | the file: a grammar refusal or findings |
3 | the environment: no ready access path (NIKA-1800), an unsatisfied --access, an unreadable file, a missing required input (NIKA-1708) | the environment: the file is missing or unreadable, a registry is unreachable |
4 | paused on a human gate: resume with --resume <trace> --answer <task>=<value> | never |
130 | cancelled by the operator (Ctrl-C, SIGTERM) | never |
The MCP server
nika mcp is read-only. It serves tools: nika_check ·
nika_explain · nika_schema · nika_examples · nika_template ·
nika_canon · nika_catalog · nika_tools · nika_inspect. Execution stays
behind nika run. MCP server describes each tool.
MCP protocol · latest ; the server accepts
versions ().