Reference

Twenty verbs, the Luau API, and the shapes niwa reads and writes. The verbs are grouped by how often you reach for them, not alphabetically.

Every verb exits 0 on success and 1 on an error. Where a verb says more than that, its page carries an exit codes table. Two flags are global and every verb takes them: -v, --verbose and --debug.

In a normal week

The six you type without thinking.

• niwa — The home screen: everything the tool knows, in one screen
• niwa apply — Make the config true: plan, confirm, execute
• niwa plan — Show what apply would do. Exit 0 when in sync, 2 when changes are pending, 1 on an error
• niwa pull — Bring machine-side changes home to the config: the inverse of apply
• niwa add — Install something and write its config line, in one motion
• niwa undo — Reverse the most recent apply

When something changed

You reach for these when the machine, the fleet, or the config moved.

• niwa explain — The model, printed for one resource: declared, actual, acknowledged, and its history
• niwa check — Validate the config: it loads, every spec is well formed, and declarations do not conflict
• niwa update — Re-resolve the lockfile and show the diff before writing it
• niwa history — Browse the applies before the most recent one
• niwa machines — Every machine's stamp: who applied what, and who is behind
• niwa doctor — Is niwa itself healthy? The journal, the archives, the secrets, the lockfile, the watcher
• niwa export — Render this machine as a readable document
• niwa tag — Set, list, or remove this machine's tags
• niwa fmt — Normalize the config files' formatting

Rarely, on purpose

Once per machine, or once in the life of a config.

• niwa init — Write a starter config that describes this machine, install the editor types, and load the watcher. Once per machine
• niwa self — The tool updating itself, always as a decision
• niwa migrate — Rewrite deprecated config forms in place
• niwa seal-key — Back up or restore the sealing key through the repo's passphrase-protected escrow
• niwa uninstall — Remove niwa and leave the machine exactly as it stands

The rest of the reference

• The Luau API — state the three layers, the exported types, and how the types reach the editor
• File locations — say where every file lives and which are committed
• File formats — give the exact shape of niwa.lock, journal.json, state/<machine>.toml, and .luaurc
• Output, marks, and errors — fix the mark vocabulary, the color roles, terminal adaptivity, and the four-part error anatomy
• Environment variables — environment variables niwa uses and exports