Skip to main content
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:
Captured from nika 0.123.1 right after the fire below, with the wall clock, at the beat’s real 22:45 slot in Sydney (11:45 UTC); only the project path is replaced. The French phrases are the binary’s own wording. 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:
Captured offline from nika 0.124.1, with no provider key. In --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

One function applies the on-time window, the miss policy, the overlap lock, the per-fire ceiling and the firing record; the emitted OS units and 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 --var pairs, and the beat’s plafond is 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:
A resident 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).
The honesty contract. Delivery is at-least-once and exactly-once is never claimed: a crash between the claim and the receipt leaves a visible orphan, not a silent double fire. Keep a fired workflow’s effects idempotent and the result is effectively-once.