The file proposes, the machine disposes. Arming a project means
declaring beats in
nika.yaml, what runs, when and under which
policies, and letting the machinery fire them: an OS unit (launchd ·
systemd), or the resident nika serve where no OS scheduler exists.
Reading this page schedules nothing; firing is always a machine act.1
Declare the beat
Add an entry under
arm: in nika.yaml: the workflow, its cadence with
its time zone, a spend ceiling and a missed-run policy.2
Read the report
nika arm checks every beat and prints READY, UNREADY or DORMANT
with the next three slots. It schedules nothing.3
Hand it to the machine
nika arm --emit launchd --write (or systemd) installs the OS unit,
or nika serve fires the beats from a resident process.The arm: block
Each entry under arm: in nika.yaml is one beat:
The set is closed: any other key, such as
signature: or budget:, is
refused (project.unknown-key) and nika arm exits 2.
A beat that uses a refused policy is reported UNREADY with the reason, and
nika arm fire, the OS units that call it and a nika serve --once sweep
refuse to fire it. The two catch-up policies, rattraper and
{ rattraper: N }, are the exception the refusal names (« nika serve
keeps it »): the resident nika serve fires such a beat. Otherwise change the
policy, or suspend the beat with the triple.
The miss policies (manqué:)
nika arm: the report
Bare, the verb reads the registry, checks each beat and its workflow, and
reports what is ready, what fired and what fires next. It schedules nothing:
The proof line separates PROUVÉ (a recorded fire, read from the beat’s
ledger) from DÉCLARÉ (the registry says so; the machine never fired it).
on-webhook is a declaration: the report shows no clock slot, and
nika arm fire records a webhook skip. Sidecar directories that no registry
entry names are reported as orphans and never erased.
A beat that speaks with OpenAI’s default voice is the common paid-media case.
Its workflow calls nika:tts_generate on openai with no model:, so the
call bills gpt-4o-mini-tts, which the price table cannot price:
--json, the blocker carries the code once on its own field, kind: budget_floor, and the sentence alone.
A beat cannot drop its plafond:, so change the call: model: tts-1 or
tts-1-hd, a priced elevenlabs model, the keyless provider: system voice,
or local / mock. The same beat with model: tts-1 reads [READY]. A beat
on gpt-image-1.5 or gpt-image-1-mini moves to gpt-image-2 (the default)
or a GPT Image 2.5 model.
nika arm --json prints the same judgment for programs
(schedule_readiness_version: 2): one object per beat in schedules, with
status, next_fire, blockers, required_inputs and the workflow’s
snapshot_digest. Exit 0 when the registry reads, 2 when it refuses; the
refusal teaches the fix.
nika arm fire <label>: the one firer
nika serve both end there, so the policy lives in one place. The resident
nika serve also keeps the two catch-up policies this firer refuses
(rattraper and { rattraper: N }). The label is
the workflow file’s name without its extension (workflows/doctor.nika →
doctor); a collision takes -2, -3 in file order.
A decision prints exactly one line on stdout: fired …, skipped …
(for example skipped nightly-report · not-due), paused … or failed …,
so a launchd or serve log stays clean. The run’s own storyboard goes to
stderr. A registry refusal (exit 2) explains itself on several lines.
What a fire guarantees:
- The per-beat lock is taken before the decision and held until the
receipt lands. Delivery is at-least-once: a crash between the claim
and its receipt leaves a durable unmatched claim in
history.ndjson, never a silent double fire. Exactly-once is never promised; keep the workflow’s effects idempotent and the result is effectively-once. - Every fire is a fresh run: a run that pauses on a human gate is parked
with its trace (
paused … · trace …), never resumed by the firer. - The beat’s
inputs:are bound like--varpairs, and the beat’splafondis the run’s--max-cost-usd.
What a fire leaves in
.nika/arm/<label>/:
nika arm migrate upgrades sidecars written by older engines into this
chained ledger, verifies each chain and rebuilds its projections. It is
idempotent and gives every beat a verdict.
nika arm disarm <label>
Prints the disarm gesture: removing the line from the file is not it;
actif: false + raison: + jusqu_au: is, because that leaves an
auditable trail. --write removes only generated unit files and prints the
launchctl bootout or systemctl --user disable --now command for you to
run; it never runs that command itself.
nika arm --emit: the OS bridge
--emit launchd|systemd prints the OS unit that fires the beats instead of
reading the registry; add --write to install it:
launchd writes a macOS user agent,
~/Library/LaunchAgents/nika.arm.<project key>.<label>.plist, and prints the
launchctl bootstrap line that loads it; systemd writes a user timer and
service pair. A unit never arms a beat that cannot run: while any beat is
UNREADY, --emit refuses and names it; fix it, suspend it, or emit the
ready beats one by one with --beat. Any of these flags without --emit
is refused, and so is --json with --emit: --json reports readiness only.
nika serve: the resident firer
Where no OS scheduler exists (a container, a bare server, a VM you own), the
resident loop ends at the same firer as an emitted unit. It also keeps the
catch-up policies rattraper and { rattraper: N }, which a --once sweep
refuses like nika arm fire:
--dry runs and records nothing, and stays resident unless combined with
--once. It previews the cadence only: it does not take the beat lock or
apply the missed-run, overlap, cost or execution policy, so would fire is
not a promise that the real firer will run. To see upcoming slots, use
nika arm.
In a project whose nika.yaml arms nothing, --once and --dry print the
sentence nika arm prints, then the --bind command and the token recipe for
running workflows over HTTP, and exit 0:
nika serve prints the same lines once on stderr and keeps
watching nika.yaml, so a beat you arm later still fires.
Startup, registry, clock and loop failures exit 1. Once the loop runs, each
beat’s result is carried by its stdout line and ledger; a completed --once
sweep exits 0 even when an individual run failed or paused.
With --bind, --workflows and --token-file, the same process also serves
the authenticated HTTP API, including runtime schedules declared over HTTP
(Server surfaces). Those schedules live in
the server’s state root, separate from this registry
(Schedules).