Builtins catalog

The language stays verbs. Everything else is a tool, and the standard library ships builtins under the nika:* namespace, engine-native (no MCP round-trip, no subprocess), all invoked the same way:

read_config:
  invoke:
    tool: "nika:read"
    args: { path: "./config.yaml" }

The tables below name every builtin so you know what exists offline. For the argument contract of any one of them, ask your installed binary rather than a page that can drift:

nika catalog --tools          # every builtin, by category, with one-line contracts
nika catalog --tools --json   # the model-facing JSON Schemas (args · required)

Canonical source: nika-spec/stdlib/builtins-v0.1.md, the Apache-2.0 language spec. The set was curated by the Rams “less but better” sweep (ADR-086/087/088): one super-powerful builtin with mode args beats five single-purpose ones.

Overview

Builtins

tools · 6 categories

Extract modes

on nika:fetch

Namespace

nika:* · engine-native

Core (6)

The workflow-control family: speak, signal, guard, ask, finish, pause.

Builtin	What it does
`nika:log`	Emit a log entry (`debug`/`info`/`warn`/`error`) to the event stream: the human-readable diagnostic.
`nika:emit`	Emit a custom machine event (consumed by subscribers and the journal). `log` is for humans, `emit` is for machines.
`nika:assert`	Fail the task if a CEL `${{ }}` condition is false: the fail-fast guard (`when:` is the skip-guard).
`nika:prompt`	Interactive human confirm: blocks until answered; engines may use `default` in CI.
`nika:done`	Mark the current `agent:` loop complete and exit. Valid only inside an agent tool whitelist.
`nika:wait`	Temporal pause: relative `duration:` XOR absolute `until:` (ISO 8601), validated at parse time.

gate:
  with:
    count: ${{ tasks.fetch_data.output.count }}
  invoke:
    tool: "nika:assert"
    args:
      condition: "${{ with.count > 0 }}"
      message: "Expected non-empty result"

File (5)

Builtin	What it does
`nika:read`	Read a file. Returns string content.
`nika:write`	Write a file. Returns the path; binary upstream values are written as-is.
`nika:edit`	In-place find/replace. Returns the modified path.
`nika:glob`	Glob match. Returns an array of paths.
`nika:grep`	Recursive grep. Returns an array of `{ path, line, match }`.

Data (9)

jq is THE data language: map, filter, reshape, merge. The other eight cover what jq genuinely cannot do: diff, validate, delete-on-null merge, format conversion, generation, time, hashing, adjudication.

Builtin	What it does
`nika:jq`	Run a jq expression: the single transform-and-extraction language, same jq as `output:` bindings.
`nika:json_diff`	JSON diff. Returns RFC 6902 JSON Patch (jq can’t diff).
`nika:validate`	Validate data against a JSON Schema: `format: json \| yaml`, returns `{ valid, errors }`.
`nika:json_merge_patch`	RFC 7396 merge patch: `null` deletes a key, the semantics jq’s `*` merge does not provide.
`nika:convert`	Universal format converter: `json` · `yaml` · `toml` · `csv`, `from:`/`to:` mode args. CSV emit takes `formula_guard: true` (opt-in) to neutralize spreadsheet formula-injection in untrusted data.
`nika:uuid`	Generate a UUID: `v7` default (timestamped/sortable, RFC 9562) or `v4`.
`nika:date`	Timestamp arithmetic: op-discriminated (`now`/`add`/`subtract`/`format`/`parse`/`diff`), timezone-aware, ISO 8601 out.
`nika:hash`	Content hashing: default blake3, or `sha256`/`sha512`; md5/sha1 are not supported.
`nika:decide`	The deterministic decision kernel (spec 11): evaluates a portable Decision Bundle (`bundle:`) against an EvidenceSnapshot (`evidence:`) and returns the full receipt — outcome, term-by-term contributions, intervals, conflicts with their witnesses, determination provenance. The model never decides: an `infer:` task collects the facts, this applies the rubric. Same evidence, same verdict, forever.

# recursive deep-merge of two task outputs — pure jq, no extra builtin
merged:
  with:
    base: ${{ tasks.base.output }}
    overlay: ${{ tasks.overlay.output }}
  invoke:
    tool: "nika:jq"
    args:
      input: ["${{ with.base }}", "${{ with.overlay }}"]
      expression: ".[0] * .[1]"

Network (2)

Builtin	What it does
`nika:fetch`	HTTP request + content extraction: extract modes (`article`, `markdown`, `links`, `feed`, `sitemap`, `selector`, `text`, `metadata`, `jq`) + `raw` passthrough — plus `form:` (urlencoded), `multipart:` (file parts ride the `permits.fs` READ boundary · ≤32 MiB) and `traverse:` (bounded same-origin crawl · `max_pages` ≤ 25 · robots honored · the effect certificate counts every page). Fetching a URL is calling a tool, not a verb — and so is crawling: no `nika:crawl`.
`nika:notify`	Send notifications: `channel:` enum (`webhook`/`slack`/`email`/`discord`/`sms`), one builtin not five.

Engines MUST ship SSRF defense on nika:fetch: private-network and cloud-metadata targets are rejected unless explicitly configured, and self-signed TLS is rejected by default.

Introspection (2)

Builtin	What it does
`nika:inspect`	Workflow introspection. One builtin, four `view:` modes: `cost` (running USD by task/provider), `records` (full execution record), `dag_info` (nodes/edges/waves), `threads` (engine pool state, advisory).
`nika:compose`	The agent loop’s self-check: pass a drafted workflow YAML, get the full `nika check` verdict back as JSON — never executed. Loop-only, like `nika:done` (valid only inside an `agent:` tools whitelist).

budget_check:
  invoke:
    tool: "nika:inspect"
    args: { view: cost }

Media (4)

Builtin	What it does
`nika:chart`	Deterministic chart rendering from rows + a semantic spec (`bar` · `line` · `area_band` · `scatter` · `heatmap`): a byte-identical SVG lands at `out:` (permit-gated write) and its sha256 rides the outputs as a trace-chain receipt. Pure compute + one write — no network, no clock, re-runs idempotent; optional Vega-Lite sibling via `compile_to:`. Full guide: Charts.
`nika:image_generate`	Provider-backed image generation and editing as an asset pipeline: renders land under a declared `output_dir:` (rides `permits.fs.write`), and `mode: edit` sources are read permit-gated (`permits.fs.read` — the mirror boundary); outputs and a provenance manifest carry paths + dimensions + sha256, and an edit records its `source_images` — image bytes never ride workflow outputs. Providers (v1.1 · local-first): `local` (any OpenAI-images-compatible self-hosted server — LocalAI · Ollama · sd.cpp · SGLang · vLLM-Omni · base URL via `NIKA_IMAGE_LOCAL_URL`) · `openai` (`gpt-image-2`) · `gemini` (`gemini-3.1-flash-image`) · `xai` (`grok-imagine-image`) · `mock` (offline, deterministic, zero keys). Full guide: Image generation — sovereign quickstart · editing · cookbook · honesty rules.
`nika:tts_generate`	Speech synthesis on the same asset-pipeline contract (full guide: Speech generation): ONE audio file lands under `output_dir:` (permit-gated), output + manifest carry path + sha256 + `duration_ms` (wav-exact, mp3 honestly null) — audio bytes never ride outputs. Providers (sovereign-first): `local` (any OpenAI-speech-compatible server — LocalAI · Kokoro-FastAPI · Speaches — via `NIKA_TTS_LOCAL_URL`) · `openai` (`gpt-4o-mini-tts`) · `elevenlabs` (`ELEVENLABS_API_KEY`) · `mock` (real deterministic WAV, offline).
`nika:image_fx`	Deterministic artistic effects on a PNG — dither (bayer · blue-noise · ign · floyd_steinberg · atkinson · jjn) · palette mapping (Oklab) · duotone · pixelate · halftone · grain · vignette · chromatic aberration · scanlines · glitch · ascii (png/text/ansi). Zero providers, zero network: byte-identical output forever for identical `(input, args)` — the artifact’s sha256 joins the trace chain, re-render IS the tamper check, and the full recipe (contract tag `image_fx/v1` · input sha256 · seed · ops) rides the PNG itself as a `nika` tEXt chunk. `input:` read + `out:` write both ride `permits.fs`. Full guide: Image effects — the receipts story · op table · cookbook.

hero:
  invoke:
    tool: "nika:image_generate"
    args:
      provider: mock              # offline dry-run · flip to local (sovereign) / gemini / openai / xai for real renders
      prompt: "OG hero — a monarch butterfly over a nebula"
      aspect_ratio: "16:9"
      output_dir: "./assets/og"

API keys are engine-configured, never workflow args: OPENAI_API_KEY / GEMINI_API_KEY / XAI_API_KEY (or the NIKA_-prefixed variants) and the local server’s NIKA_IMAGE_LOCAL_URL (+ optional NIKA_IMAGE_LOCAL_API_KEY) are read once at the engine’s composition root. The provider endpoints are engine-fixed constants — permits.net.http does not govern them (exactly like infer:); permits.tools and permits.fs do.

Design rules the set obeys

One super-powerful builtin, multi-mode args: fetch+extract, jq, convert, wait, date, inspect all follow the same pattern. No per-direction or per-shape builtin slots.
jq subsumes: anything that is a pure JSON transform is a jq expression, not a builtin. A builtin earns its slot only by doing what jq cannot.
Additive forever: new builtins may join in stdlib v0.x; existing arg shapes never break (the language envelope nika: v1 is frozen).

Full stdlib spec

Per-builtin args, error codes (NIKA-BUILTIN-*), trust classes, and what jq subsumed out of v0.1.

Verbs

How invoke: dispatches nika:* builtins vs MCP tools.

MCP catalog

External tools: the MCP server registry Nika knows by id.

Bindings

Templating that pipes output from one invoke: to the next.

YAML

CLI & errors

Data catalogs

Workspace

Builtins catalog

Overview

Builtins

Extract modes

Namespace

Core (6)

File (5)

Data (9)

Network (2)

Introspection (2)

Media (4)

Design rules the set obeys

See also

Full stdlib spec

Verbs

MCP catalog

Bindings

​Overview

Builtins

Extract modes

Namespace

​Core (6)

​File (5)

​Data (9)

​Network (2)

​Introspection (2)

​Media (4)

​Design rules the set obeys

​See also

Full stdlib spec

Verbs

MCP catalog

Bindings

Overview

Core (6)

File (5)

Data (9)

Network (2)

Introspection (2)

Media (4)

Design rules the set obeys

See also