Your first workflow

v: nika check, nika run, nika doctor, nika lsp, and nika mcp ship in the binary. Run nika init once per repo for schema and agent rules.

Goal

Write a .nika.yaml file, run it, get structured output. No setup beyond nika installed. Your first run needs no API key and no model server.

1. Pick how the AI step runs

Three paths, from zero-setup to production: Instant (no model at all): the built-in mock/echo model returns a deterministic response, so you can see a workflow’s shape right now:

model: mock/echo

Local (free · private): have Ollama running, no API key, nothing leaves your machine:

ollama pull llama3.2:3b

Cloud: set any provider key:

export MISTRAL_API_KEY=...
# or export ANTHROPIC_API_KEY=... · any provider in the catalog

At any point, nika doctor tells you exactly what’s wired and how to fix what isn’t:

nika doctor

All provider env vars listed in Providers catalog.

2. Write the workflow

Create hello.nika.yaml:

hello.nika.yaml

nika: v1
workflow:
  id: hello

tasks:
  greet:
    infer:
      model: ollama/llama3.2:3b            # <provider>/<name> · local · swap for any cloud provider
      prompt: "Say hi to the chrysalis. Be brief."

Three things to notice:

nika: v1 declares the workflow language + pins the contract version (a single version marker · v1 forever).
workflow: is an object — id: (kebab-case) names the run.
tasks: is a map keyed by task id; each task declares one verb (here, infer).

3. Check it, then run it

nika check hello.nika.yaml   # the static audit: plan · cost · secrets · types · before a single token is spent
nika run hello.nika.yaml

nika check catches broken references, missing dependencies and schema problems before any model is called, and points at the exact fix:

No provider handy? Swap the model: line for mock/echo. Both commands work fully offline, and you can wire a real model later.

Example output:

▶ greet  infer  → ollama/llama3.2:3b
  ┌─ output ──────────────────
  │ Welcome inside the chrysalis. 🦋
  └───────────────────────────
✓ greet  T+00:00:01.42  OK

Read the story back (0.98+)

nika explain <file> narrates any checked workflow — the waves, the cost before a token is spent (an unbounded task reads FLOOR, a local model reads unpriced — not « free » — the whole vocabulary lives in Cost honesty), what it touches, and the flight recorder hand-off. Captured verbatim against the released 0.107.0 on the chain skeleton after one recorded run:

cost before a token is spent
  bounded portion $0.0000 · no total ceiling · 1 uncapped
    think: ollama/llama3.2:3b has no catalog price — unknown stays unknown (never $0)
  local models: your compute · tokens unpriced — not « free »

flight recorder
  1 run in .nika/traces · latest:
  nika trace show .nika/traces/2026-08-02T01-11-53Z-7f42.ndjson
  nika trace verify <same file>   # prove the hash chain

The skeleton already caps the seat (max_tokens: 800) — the uncapped part is the unpriced local model, and the report says so instead of printing a fake $0. Swap in any priced cloud seat and the same report reads ≤ $0.0005 worst case · ≥ $0.0005 cheapest path — a hard ceiling.

4. Add a second task that depends on the first

hello.nika.yaml

nika: v1
workflow:
  id: hello

tasks:
  greet:
    infer:
      model: ollama/llama3.2:3b            # <provider>/<name> · local · swap for any cloud provider
      prompt: "Say hi to the chrysalis. Be brief."

  critique:
    with:
      greeting: ${{ tasks.greet.output }}  # the binding IS the edge
    infer:
      model: ollama/llama3.2:3b            # <provider>/<name> · local · swap for any cloud provider
      prompt: |
        The greeting was: ${{ with.greeting }}

        Rewrite it shorter and more enigmatic.

Notice the with: block. Each ${{ tasks.X.* }} reference in it is a binding: it names the data the task consumes (${{ with.greeting }} in the prompt) and declares the edge that orders it — greet → critique, one declaration, no invisible edges. The engine injects the value at runtime, with explicit taint tracking.

The graph you just built

One with: binding and the order falls out of the file. Tasks with no edge between them run in parallel automatically. You never schedule anything. (For an ordering with no data — run the deploy after the tests, consume nothing — use after: { tests: success }, the control door.)

5. Get structured output

hello.nika.yaml

nika: v1
workflow:
  id: hello-structured

tasks:
  names:
    infer:
      model: ollama/llama3.2:3b            # <provider>/<name> · local · swap for any cloud provider
      prompt: "Generate three names for a butterfly."
      schema:                          # structured output · JSON Schema
        type: object
        properties:
          names:
            type: array
            items:
              type: string
              minLength: 3
              maxLength: 20
            minItems: 3
            maxItems: 3
        required: [names]

Nika takes the JSON Schema, asks the provider for output that conforms (using each provider’s native structured-output API where the capability rules allow it: schema mode, object mode, or JSON-mode emulation), and validates the result against your schema before passing it on.

nika run hello.nika.yaml
# Output is guaranteed to be { "names": ["...", "...", "..."] }

What you just built

Workflows are YAML files: .nika.yaml.
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> }}, with taint tracking.
schema: enforces JSON schemas on AI output.

Next checks

Check before running

nika check hello.nika.yaml: static audit before any token or effect.

Inspect the DAG

nika inspect hello.nika.yaml (add --format mermaid|dot|json for the machine projections).

Wire your agent

Run nika wire cursor or nika wire all for explicit MCP setup, or use the editor extension’s agent setup.

Examples · real jobs

Climb the ladder: starter chains to multi-agent swarms, every file conformance-validated.

How to write Nika

The twelve patterns: where the determinism lives, where the model is allowed to think.

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.

Live state

Which verbs are admitted today.

Overview

Getting started

Agents & integrations

Concepts

Your first workflow

Goal

1. Pick how the AI step runs

2. Write the workflow

3. Check it, then run it

Read the story back (0.98+)

4. Add a second task that depends on the first

The graph you just built

5. Get structured output

What you just built

Next checks

Read next

Examples · real jobs

How to write Nika

The 4 verbs

Bindings

Providers

Live state

​Goal

​1. Pick how the AI step runs

​2. Write the workflow

​3. Check it, then run it

​Read the story back (0.98+)

​4. Add a second task that depends on the first

​The graph you just built

​5. Get structured output

​What you just built

​Next checks

​Read next

Examples · real jobs

How to write Nika

The 4 verbs

Bindings

Providers

Live state

Goal

1. Pick how the AI step runs

2. Write the workflow

3. Check it, then run it

Read the story back (0.98+)

4. Add a second task that depends on the first

The graph you just built

5. Get structured output

What you just built

Next checks

Read next