Skip to main content
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.1
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: hello

tasks:
  - id: greet
    infer:
      model: ollama/llama3.1               # <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 a human-readable name (kebab-case · the document-type discriminator).
  • tasks: is a list; each task has an id and 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
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.1
  ┌─ output ──────────────────
  │ Welcome inside the chrysalis. 🦋
  └───────────────────────────
✓ greet  T+00:00:01.42  OK

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

hello.nika.yaml
nika: v1
workflow: hello

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

  - id: critique
    depends_on: [greet]
    infer:
      model: ollama/llama3.1               # <provider>/<name> · local · swap for any cloud provider
      prompt: |
        The greeting was: ${{ tasks.greet.output }}

        Rewrite it shorter and more enigmatic.
Notice ${{ tasks.greet.output }}. That’s a binding. The engine injects the previous task’s output into the prompt at runtime, with explicit taint tracking and pipe filters.

​
The graph you just built

One depends_on line and the order falls out of the file. Tasks with no dependency between them run in parallel automatically. You never schedule anything.

​
5. Get structured output

hello.nika.yaml
nika: v1
workflow: hello-structured

tasks:
  - id: names
    infer:
      model: ollama/llama3.1               # <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, identified by id.
  • Four verbs (infer, exec, invoke, agent) define what each task does (HTTP fetch is the nika:fetch builtin under invoke).
  • depends_on: builds a DAG.
  • ${{ tasks.X.output }} bindings flow data between tasks, with taint tracking.
  • schema: enforces JSON schemas on AI output.

​
Next checks

1

Check before running

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

Inspect the DAG

nika inspect hello.nika.yaml or nika graph hello.nika.yaml --format mermaid.
3

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.