# niwa

> niwa grows a complete macOS setup from one readable Luau file.

- [niwa](https://niwa.rs/): State what niwa is, show one real config and one real screen, and route to three places

## Start

- [Install](https://niwa.rs/start/): Get the binary on the machine and say what the installer touched
- [Your first config](https://niwa.rs/start/first-config/): Run niwa init, read what it wrote, understand the four files that matter
- [Your first apply](https://niwa.rs/start/first-apply/): Run plan, read the plan, run apply, read what happened
- [Adopt a machine you already use](https://niwa.rs/start/adopt/): Point niwa at a lived-in Mac without losing anything
- [Set up a second machine](https://niwa.rs/start/second-machine/): Clone the config on a new Mac and reach the same state

## Concepts

- [Concepts](https://niwa.rs/concepts/): Say what these pages are for and in what order to read them
- [Declared, actual, acknowledged](https://niwa.rs/concepts/model/): Teach the three states and the four comparisons they produce
- [The apply loop](https://niwa.rs/concepts/apply/): Explain the three phases, the two passes, and the overwrite ladder
- [The checklist and manual steps](https://niwa.rs/concepts/checklist/): Explain why some work is a checklist item and never a prompt
- [Drift and the write-back loop](https://niwa.rs/concepts/drift/): Explain proposals, the four answers, and why pull is apply's inverse
- [The watcher](https://niwa.rs/concepts/watcher/): Explain a stateless launchd job whose whole vocabulary is notify
- [Safety and undo](https://niwa.rs/concepts/safety/): Explain the archive rule, the journal, and why there is no world rollback
- [Secrets](https://niwa.rs/concepts/secrets/): Explain typed opaque secrets, resolution order, and the masking rule
- [Many machines](https://niwa.rs/concepts/machines/): Explain the git boundary, the stamp, machine identity, and the lockfile
- [The config and its modules](https://niwa.rs/concepts/config/): Explain structure-from-layout, modules as groups, hosts as override
- [The config language](https://niwa.rs/concepts/luau/): Explain why Luau, the sandbox, and where types are actually enforced
- [What niwa will not do](https://niwa.rs/concepts/limits/): State the refusals and the honest limits, in the tool's own words

## Guides

- [Guides](https://niwa.rs/guides/): Route to the task the reader came for
- [Manage system settings](https://niwa.rs/guides/system-settings/): Declare defaults, dock, and finder, and know what restarts
- [Manage dotfiles](https://niwa.rs/guides/dotfiles/): Copy files, link files, render templates, and know which is which
- [Manage packages](https://niwa.rs/guides/packages/): Install formulae, casks, global npm packages, tools, and release binaries
- [Manage services](https://niwa.rs/guides/services/): Declare a launchd agent with exactly one schedule
- [Write a custom resource](https://niwa.rs/guides/custom-resource/): Define a kind with check, apply, reverse, and describe
- [Share a module](https://niwa.rs/guides/share-modules/): Publish a module, pull one in with niwa.use, and read its lock entry
- [Schedule convergence](https://niwa.rs/guides/schedule-convergence/): Declare a service that runs apply --yes on a schedule, and decide whether to
- [Recover a machine](https://niwa.rs/guides/recover/): Rebuild after a failure: restore the sealing key, apply, verify
- [Store and use a secret](https://niwa.rs/guides/secrets/): Add a secret, reference it, render it into a file, escrow the key
- [Capture a change you made by hand](https://niwa.rs/guides/capture-a-change/): Flip something in System Settings and keep it

## Commands

- [niwa](https://niwa.rs/reference/cli/niwa/): The home screen: everything the tool knows, in one screen
- [check](https://niwa.rs/reference/cli/check/): Validate the config: it loads, every spec is well formed, and declarations do not conflict
- [plan](https://niwa.rs/reference/cli/plan/): Show what apply would do. Exit 0 when in sync, 2 when changes are pending, 1 on an error
- [apply](https://niwa.rs/reference/cli/apply/): Make the config true: plan, confirm, execute
- [undo](https://niwa.rs/reference/cli/undo/): Reverse the most recent apply
- [pull](https://niwa.rs/reference/cli/pull/): Bring machine-side changes home to the config: the inverse of apply
- [add](https://niwa.rs/reference/cli/add/): Install something and write its config line, in one motion
- [fmt](https://niwa.rs/reference/cli/fmt/): Normalize the config files' formatting
- [seal-key](https://niwa.rs/reference/cli/seal-key/): Back up or restore the sealing key through the repo's passphrase-protected escrow
- [explain](https://niwa.rs/reference/cli/explain/): The model, printed for one resource: declared, actual, acknowledged, and its history
- [machines](https://niwa.rs/reference/cli/machines/): Every machine's stamp: who applied what, and who is behind
- [doctor](https://niwa.rs/reference/cli/doctor/): Is niwa itself healthy? The journal, the archives, the secrets, the lockfile, the watcher
- [update](https://niwa.rs/reference/cli/update/): Re-resolve the lockfile and show the diff before writing it
- [init](https://niwa.rs/reference/cli/init/): Write a starter config that describes this machine, install the editor types, and load the watcher. Once per machine
- [history](https://niwa.rs/reference/cli/history/): Browse the applies before the most recent one
- [export](https://niwa.rs/reference/cli/export/): Render this machine as a readable document
- [tag](https://niwa.rs/reference/cli/tag/): Set, list, or remove this machine's tags
- [migrate](https://niwa.rs/reference/cli/migrate/): Rewrite deprecated config forms in place
- [self](https://niwa.rs/reference/cli/self/): The tool updating itself, always as a decision
- [uninstall](https://niwa.rs/reference/cli/uninstall/): Remove niwa and leave the machine exactly as it stands

## Luau API

- [The Luau API](https://niwa.rs/reference/api/): State the three layers, the exported types, and how the types reach the editor
- [Packages and tools](https://niwa.rs/reference/api/packages/): Install and manage packages, casks, and binaries
- [Files and links](https://niwa.rs/reference/api/files/): Manage files, symlinks, and rendered templates
- [System settings](https://niwa.rs/reference/api/settings/): Manage macOS system settings and defaults
- [Services](https://niwa.rs/reference/api/services/): Manage launchd services and scheduled jobs
- [Manual steps](https://niwa.rs/reference/api/human/): Manage manual steps and checklist items
- [Luau utilities](https://niwa.rs/reference/api/functions/): Utility functions and generic resource definition
- [Facts](https://niwa.rs/reference/api/facts/): Computed values available in config

## Reference

- [Reference](https://niwa.rs/reference/): Index the twenty verbs by how often you reach for them, and route to the rest
- [File locations](https://niwa.rs/reference/files/): Say where every file lives and which are committed
- [File formats](https://niwa.rs/reference/formats/): Give the exact shape of niwa.lock, journal.json, state/\<machine\>.toml, and .luaurc
- [Output, marks, and errors](https://niwa.rs/reference/output/): Fix the mark vocabulary, the color roles, terminal adaptivity, and the four-part error anatomy
- [Environment variables](https://niwa.rs/reference/environment/): Environment variables niwa uses and exports