Install Nika first if you have not. This
page writes each file by hand so you learn every line; to describe a job in
your own words instead, open the terminal Session.
1. Write the file
Createhello.nika:
hello.nika
nika: <name>is the mark and the workflow’s kebab-case identifier.model: mock/echoneeds no key and no server — the engine echoes the prompt back. The mechanics are real; the “answer” is a rehearsal.permits: {}declares zero authority up front. A workflow that later touches a file, a host or a shell must say so here, or admission refuses it (NIKA-SEC-004, naming the missing permission).max_tokenscaps the answer’s length.outputs:names what the run hands back.
2. Check it, then run it
nika 0.123.1 on a fresh machine, offline. The audit ends
fully green (audited · 1 task · 1 wave · permits {} · est out ≤$0.0000 · 0 hints · risk low, then layers · valid ✔ · access ready ✔ · capacity fit ✔ · run ready ✔), and the run prints:
nika check catches broken references, missing dependencies and schema
problems before any model is called, and points at the exact fix. The run
wrote a hash-chained record under .nika/traces/. unpriced (1 call) is the
honest total for a model the catalog cannot price: never $0.00. Verify the
latest record:
UNSEALED: this machine has no
run-signing key yet. Mint one once, run again, and the record is signed:
3. Ask the file three questions
What if a required input is missing?
What if a required input is missing?
Mark an input
required: true (with no default:) and the run refuses
to start without it (NIKA-1708, exit 3): admission fails, nothing
half-executes. An input with neither required: true nor a default:
does not stop the start: the first task that reads it fails
(NIKA-VAR-001, exit 1). Callers pass values with
run(..., { inputs }) in the SDK or --var key=value on the CLI.What if a permission is absent?
What if a permission is absent?
Admission refuses at check; the finding names the missing
permission. An absent
permits: block is zero authority
(NIKA-AUTH-006). A declared permits: {} that omits a reached
tool or path is NIKA-SEC-004 — the plate below. The file needs
both the named tool (nika:read) and the specific path
(./hello.nika). nika check --infer-permits drafts the
tightest block for you.What if I switch the model?
What if I switch the model?
One line.
ollama/llama3.2:3b runs locally after
ollama pull llama3.2:3b; a cloud provider takes its environment key
(export MISTRAL_API_KEY=... for mistral/mistral-small-latest). A
reasoning (thinking) model spends its thinking inside max_tokens, so
raise the cap when you switch to one: nika check names the minimum for
a cataloged reasoning model. The file, the check and the record keep the
same shape; only the answer changes. nika doctor reports what your
machine can reach.4. Add a second task that depends on the first
Save this asgreet-chain.nika:
greet-chain.nika
with: block is a binding: it names the data the
task consumes and declares the edge that orders it — greet → critique, one
declaration, no invisible edges. Tasks with no edge between them run in
parallel automatically. (For ordering without data, such as deploy after
tests while consuming nothing, use after: { tests: success }.) The
outputs: line matters too: without a consumer, nika check points out that
the last task’s tokens would be spent unread ([dead-spend]).
5. Get structured output
Save this asnames.nika:
names.nika
nika 0.123.1 (nika run names.nika --output json):
${{ tasks.names.output.names }} indexes into the validated object, so the
output is the array itself. additionalProperties: false closes the shape,
so every provider returns the same keys.
On a successful run, outputs: carries the declared shape — checked
when the model answers. A failed or refused run produces no output: the
guarantee covers shape, not outcome.
6. See a real job
This short recorded demonstration turns synthetic notes into an action list usingxai/grok-3-mini, on CLI 0.120.1 with condensed timing. The
0.124.3 catalog no longer lists that model: to reproduce it, pick a model
nika catalog lists, for example xai/grok-4.3 (a reasoning model, so give
it max_tokens of at least 256) with your XAI_API_KEY.
The demonstration file has no typed schema, so the run exports a
string. The full meeting-actions
example declares {owner, task, due} and exports typed actions.
Download GIF
What you just built
- Workflows are YAML files:
.nika. - Tasks are units of work; the map key is the identity.
- Four verbs (
infer,exec,invoke,agent) define what each task does (HTTP fetch is thenika:fetchbuiltin underinvoke). with:(data) andafter:(control) build the DAG — the binding IS the edge.${{ tasks.X.output }}crosses a task boundary inwith:; the body reads${{ with.<name> }}.schema:checks AI output shape at answer time;outputs:exports the result.
Next lesson
1
Drive it from an app
SDK quickstart: the same file through
check → run → result → traceVerify in TypeScript.2
Inspect the DAG
nika inspect hello.nika (add --format mermaid|dot|json for the
machine projections); nika explain hello.nika narrates the waves and
the cost before a token is spent.3
Wire your agent
Run
nika wire detected --dry-run to preview, then nika wire detected
to add Nika’s MCP server to the agent clients this machine shows, or
nika wire cursor for one client.Read next
Examples · real jobs
Starter chains to multi-step reports: every file passes
nika check, and
each page lists what it needs to run.How to write Nika
The patterns of well-written Nika, each taught by a canonical example.
The 4 verbs
Deep dive on
infer, exec, invoke, agent.Bindings
How data flows between tasks with taint tracking.
Providers
Why one
InferRequest works across providers.Cost honesty
Read the cost report: floors, ceilings and honest « unpriced ».