The questions everyone asks
Can I run Nika today?
Can I run Nika today?
Yes. Install the latest tagged release with Homebrew or
install.sh,
then run nika check and nika run locally. The engine is still
pre-1.0 and hardening toward the 1.0 launch; a grammar change before
1.0 ships with its nika check --fix migration.Why is the language v1 but the engine pre-1.0?
Why is the language v1 but the engine pre-1.0?
Two independent axes. The language is versioned by the spec and
changes only with a migration the binary applies (
nika check --fix);
after 1.0 it is additive only. The engine follows real
semver toward 1.0 (public tags are the 0.12x line today, then 1.0.0
when the gates are green).
Same model as SQL or GraphQL: the contract is stable, implementations
iterate.Is fetch a verb?
Is fetch a verb?
No. There are exactly verbs (
infer · exec ·
invoke · agent), locked forever. Fetching a URL is calling a
tool: invoke: { tool: "nika:fetch" }. If you see fetch: as a
verb anywhere, it’s the pre-spec legacy dialect.Which providers work offline?
Which providers work offline?
local runtimes (Ollama · LM Studio · llama.cpp
· LocalAI · vLLM). Point
model: ollama/llama3.2:3b at your machine and
the infer step stays on the machine. “Zero cloud” is about model
inference: nika:fetch, MCP, and other declared tools can still
call the network if permits allow them. mock/echo infers with
nothing at all.Do I write {{ }} or ${{ }}?
Do I write {{ }} or ${{ }}?
Always
${{ … }}: what’s inside is CEL. The bare {{ … }} form is
legacy and rejected by the validator. Same rule: there are no
template filters (| upper, | truncate): transforms are jq, in
extract: bindings or nika:jq.My YAML is valid, so why does nika check still fail?
My YAML is valid, so why does nika check still fail?
Schema-valid ≠ spec-valid. The validator also enforces the semantic
rules:
tasks.* references live at the boundary only (with: ·
after: — a body reference is NIKA-VAR-021, hoist it into
with:), when: must be a CEL boolean over local namespaces,
nika:done only inside an agent’s tool list, exactly one verb per
task. The error names the exact rule. Fix that rule, nothing else,
re-check.Errors you’ll hit, decoded
Caught before anything runs. nika check stops a pull-request reviewer on two mistakes: a misspelled task name, with the right one suggested, and a value read outside the task’s with: boundary (NIKA-VAR-021, in the table below). Each finding names its fix; after the fix, the same check says the file is ready to run. Output captured from the real CLI.
transient
flag (error model). The frequent ones:
When it breaks, in order
1
Read the code, not the message
NIKA-<NAMESPACE>-<NNN> is stable and greppable. The
catalog gives the namespace’s contract.2
Check transient
transient: true → retry can help (declare retry: with backoff).
transient: false → the input or the file is wrong; retrying burns
money.3
Recover structurally
on_error: recover: substitutes a fallback value ·
on_error: on_codes: scopes recovery to specific codes (recover the
not-found, still fail loudly on permission-denied).4
Ask with context
Two guided forms exist so nothing gets lost: First run
failed
(a stumble in your first minutes is a bug, even when nothing
crashed) and I was confused
here
(paper cuts are bugs in the teaching). The output of
nika welcome
is the perfect diagnostic attachment — it prints key presence,
never values. For everything else,
Discussions is
the fastest lane. Security findings: security@supernovae.studio,
never public issues.Nika ships zero telemetry — the binary never phones home. These
forms and Discussions ARE the project’s analytics: a report that you
reached your first green run in under two minutes is a data point we
cannot get any other way.
See also
Error codes
The namespaces + the typed error shape.
Templates
Skeletons that avoid most of these errors by construction.
Security model
Why fetch/exec block what they block.
Live engine state
The live engine snapshot, judged by the downloadable binary.