Skip to content

The file is called .nika now

In Nika 0.120.0 a workflow file ends in .nika and nika compile writes new ones; .nika.yaml and nika new are retired, with a message to rename.

Two names a person types often changed in Nika v0.120.0, published on 18 September 2026: the suffix of a workflow file, and the command that writes a new one. Both changes are breaking. Together they explain why older posts on this blog show .nika.yaml files and a nika new command that a current binary refuses.

The suffix tells a tool what the file is #

Before 0.120.0, a workflow was a YAML file named something.nika.yaml. A Nika project can also hold a nika.yaml file for its settings, and the engine keeps run state in a .nika/ folder. Three names, all built on the same word.

From 0.120.0 the language specification tells the three apart by their exact names. Its file-naming section shows the layout:

output
project/
  nika.yaml                 # project / workspace configuration
  workflows/
    support-triage.nika     # executable Nika program (YAML-compatible source)
    child.nika
  .nika/                    # runtime / internal state

The 0.120.0 notes state the rule in one sentence: ".nika.yaml / .nika.yml are retired with an actionable rename diagnostic; nika.yaml remains the project file and .nika/ remains runtime state."

The content of a workflow did not change. A .nika file is still YAML-compatible source; only its name changed. The specification spells out the edges, and they are strict on purpose:

  • the suffix is exactly lowercase .nika, so foo.NIKA and foo.Nika are not workflow files, even on a filesystem that ignores case;
  • names that only look similar, such as a detached signature foo.nika.minisig, are not workflow files either;
  • nika.yaml is project configuration only, and no tool may discover or run it as a workflow;
  • an explicit path ending in .nika.yaml or .nika.yml is refused with a message that tells you to rename it, with "no silent fallback".

Bytes without a filename are not affected. A workflow passed as a string or on standard input is judged from its content, as before. The notes: "Parser source-string and stdin APIs stay filename-independent."

The change covers the places the engine finds or names a file. The notes list them in their own terms: "Live disk discovery, CLI capture, Serve registry names, cadence references, DAP inventory, session grounding and Compile materialization accept lowercase .nika only." The project file's JSON Schema caught up a few hours later in v0.120.1, whose notes say it "accepts .nika workflow references". In the companion repositories, commits titled feat(file-identity) and dated the same day moved the SDK, the GitHub Action, the registry, the editor extension and the plugins.

To move an existing workflow, rename name.nika.yaml to name.nika, and update any path in nika.yaml or in a schedule that names it.

One command writes a new file #

The second rename is the authoring command. Earlier releases created a starting file with nika new and a wizard; the skeleton in Not a workflow yet was made that way. 0.120.0 replaced both with one command. The notes: "Replaced the retired authoring command and wizard with nika compile".

nika compile fills a skeleton, one of the starting workflows built into the binary, from explicit answers. The README of the 0.120.0 tag starts new users with its offline lesson:

terminal
mkdir first-workflow
cd first-workflow
nika compile hello hello.nika

Then:

terminal
nika check hello.nika
nika run hello.nika

The lesson runs without a provider key. The README of that tag explains why: "Hello always uses mock/echo, including when provider keys are present", a stand-in that echoes its prompt, and compile "does not call a model, run the workflow, or choose access on your behalf."

Three properties matter when nika compile is called from a script or from another tool:

  • The notes: "Compile performs no workflow effects, credential probes or model calls."
  • A question left unanswered leaves the result incomplete. An incomplete result includes its candidate and its questions, and writes no file.
  • "Ready candidates require an explicit destination and overwrite requires --force."

nika compile --list lists the skeletons. nika compile <slug> --json previews one, and repeated --answer KEY=JSON_LITERAL flags answer its questions.

The same command edits an existing file, one constant at a time. A constant is a named value under the workflow's const: key. The README shows the form:

terminal
nika compile --base workflow.nika --change 'Set const.topic to "new topic"' --json

Adding --output edited.nika writes the edited file once the edit is ready.

Edits that touch only what they change #

The first version of that edit had a flaw, fixed the next day in v0.120.2. Changing one constant rewrote the whole file, "dropping the licence header, comments, key order and line endings". From 0.120.2 the edit replaces only the bytes of the value it changes, and a change that changes nothing returns the exact source.

The same release fixed large numbers. An integer answer too large to hold was rounded before any check ran: "18446744073709551616 was emitted as 1.8446744073709552e+19." Compile now refuses an integer it cannot hold exactly, names it, and leaves the source unchanged.

On 20 September, v0.120.3 put the same compile core behind nika serve, as POST /v1/compile, for applications. It writes no file and starts no run. The notes keep the boundary clear: "The preview is a review, never admission: POST /v1/jobs judges a candidate again."

Why both renames matter #

Both changes are about what a person types and what a tool can tell from a name. A file named <name>.nika is a workflow program, without opening it. A file named nika.yaml never is. A folder named .nika/ holds state. The specification turns that into a rule for every tool that creates a workflow file: it "MUST emit this form".

The command change follows the same idea. nika compile is a small, predictable step. It writes a complete file to the place you name, or it writes nothing and tells you what it still needs. In 0.120.0 it never called a model to guess the rest.

What this change does not do #

  • There is no automatic migration. Old files are refused with a rename message, and you rename them.
  • nika.yaml keeps its name. It is the project file, not a workflow.
  • nika compile in 0.120.0 is bounded. The README of that tag says: "Unsupported natural language stays incomplete without a substitute workflow. Full natural-language authoring and Graph editing are not implemented by this bounded CLI."
  • The byte-exact edit of 0.120.2 works on single-line values, including inline lists and maps. Block collections and multi-line values are refused with the source unchanged.
  • Large integers are refused, not stored with more precision. The 0.120.2 notes: "this is a refusal, not arbitrary precision."
  • Compile's check preview judges the source only. nika check and nika run still judge the real environment.

Read the v0.120.0 release, the follow-ups v0.120.2 and v0.120.3, and the file-naming rules in the specification.