Skip to main content
The machine-readable schema is at https://nika.sh/schema/workflow.json. Point your editor at it for live validation — see editor setup.

​
Top level

the envelope · a skeleton, not a runnable file
nika: v1                     # required · language + contract version (single marker)
workflow: <identifier>       # required · kebab-case · unique within file
description: <string>        # optional · human-readable

model: <provider>/<name>     # optional · default model for infer/agent tasks

vars: { ... }                # optional · inputs (typed or untyped) · ${{ vars.* }}
env: { ... }                 # optional · non-sensitive config · ${{ env.* }}
secrets: { ... }             # optional · vault/env/file references · ${{ secrets.* }}

tasks: [ ... ]               # required · non-empty

outputs: { ... }             # optional · the workflow's return value

​
A task

- id: <identifier>           # required, unique within workflow (snake_case)

  depends_on: [<id>, ...]    # optional DAG edge
  when: <expression>         # optional gate · ${{ }} CEL boolean OR literal true/false
  for_each: <expression>     # optional fan-out (an array)
  max_parallel: <int>        # optional · cap concurrent iterations
  fail_fast: <bool>          # optional · default true · false = collect errors
  timeout: "<duration>"      # optional · quoted Go-duration · per-iteration on for_each
  retry: { ... }             # optional retry policy (max_attempts · backoff · on_codes)
  on_error: { ... }          # optional recovery · recover/skip/fail_workflow + on_codes
  with: { ... }              # optional task-scoped variables
  output: { <name>: <jq> }   # optional named jq bindings over the raw output
  on_finally: [ ... ]        # optional cleanup steps · run if the task STARTED

  # exactly one verb block:
  infer: { ... }
  exec: { ... }
  invoke: { ... }
  agent: { ... }
The full per-field semantics live in the spec: 03 · DAG shape.

​
Verbs

See individual pages:
  • infer — LLM call
  • exec — shell commands
  • invoke — built-in or MCP tool (HTTP fetch is invoke: nika:fetch)
  • agent — tool-calling loop

​
Full schema

The canonical JSON Schema is at https://nika.sh/schema/workflow.json. It’s 100% machine-authoritative. This doc is a readable summary.

​
Contract version policy

nika: v1 is a single version marker — v1 is the only value for the entire lifetime of the v1 contract. Minor additions (a new optional field, a new builtin) are additive and never change it (no @minor bumps, no nika migrate for them). A future nika: v2 would be a deliberate breaking-change generation with its own spec — and since the v1 envelope is frozen, effectively never.