Skip to main content
Goal: write one file, run it offline, read a typed output. No API key, no model server, nothing leaves your machine.
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

Create hello.nika:
hello.nika
  • nika: <name> is the mark and the workflow’s kebab-case identifier.
  • model: mock/echo needs 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_tokens caps the answer’s length.
  • outputs: names what the run hands back.

2. Check it, then run it

Captured from 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:
The chain is intact, but the run is UNSEALED: this machine has no run-signing key yet. Mint one once, run again, and the record is signed:
Verification re-executes nothing: it reads the record and reports the evidence available to it. A missing key changes the verdict, not the run’s result. Seal your runs explains the variable and where the key is stored.

3. Ask the file three questions

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.
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.
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.
Measured CLI 0.120.1 plates (condensed, not a live recording); the refusal is unchanged in 0.124.3. Press play: nothing autoplays. Download GIF

4. Add a second task that depends on the first

Save this as greet-chain.nika:
greet-chain.nika
The 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 as names.nika:
names.nika
The engine asks the provider for output that conforms (using each provider’s native structured-output mode where the capability rules allow it) and validates the reply against your schema before passing it on. The mock validates too — it synthesizes a conformant instance, so this exact file runs offline. Captured from 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 using xai/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 the nika:fetch builtin under invoke).
  • with: (data) and after: (control) build the DAG — the binding IS the edge.
  • ${{ tasks.X.output }} crosses a task boundary in with:; 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.

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 ».