CLI

Every subcommand and every flag.

The nanook binary is the only thing you run. Every operation is a subcommand. Bare nanook is shorthand for nanook run.

Global flags

Flag	Default	What
`-c, --config <path>`	`nanook.toml`	Path to the config file
`--log-level <level>`	(config)	Override the configured log level

Subcommands

`nanook run`

Default. Boots every collector, adapter, rule, channel. Runs until SIGINT. Aliases: start, agent.

nanook run
nanook run --config /etc/nanook/nanook.toml --log-level debug
nanook run --watch

Flag	What
`-w, --watch`	Reload when the config file changes (debounced ~250ms). Same effect as `SIGHUP`.

Reload is also triggered by SIGHUP and by the admin server's reload endpoint. See Admin · Reload.

`nanook check`

Parse the config, build every piece, exit zero on success. Doesn't poll, doesn't fire, doesn't open the admin port. The deploy gate. Alias: validate.

nanook check

`nanook init`

Write a starter nanook.toml. Interactive picker by default. Alias: new.

By default the config lands in ~/.nanook/nanook.toml so a service unit's working directory finds it without -c. Pass --here for the per-project workflow (./nanook.toml), or -c <path> for an explicit location.

Flag	What
`--template`	Skip the picker, write the canned starter
`--force`	Overwrite an existing config at the target path
`--here`	Write `./nanook.toml` instead of the global `~/.nanook/nanook.toml`

`nanook schema`

Emit a JSON schema (draft 2020-12) describing the config.

nanook schema > nanook.schema.json
nanook schema --pretty > nanook.schema.json

Flag	What
`-p, --pretty`	Two-space indented output (default is compact one-line)

`nanook plugins`

Manage dynamic-library collectors / adapters / actions. Alias: plugin.

Subcommand	What
`ls`	List every kind, builtin and plugin
`inspect <name>`	Full doc, options, metrics, file path, ABI status
`check`	Validate every configured plugin loads with a matching ABI
`doctor`	`ls` + `check` + diff against config (default when no op given)
`where`	Print the effective plugin search paths
`new <name>`	Scaffold a new plugin crate

new flags:

Flag	What
`-k, --kind`	`collector`, `adapter`, or `action`. Default `collector`.
`--path`	Parent dir to scaffold into
`--nanook-path`	Override `nanook-plugin` dep with a local path
`--nanook-git`	Override `nanook-plugin` dep with a git URL
`--nanook-version`	Pin a specific crates.io version

See Plugins for the full plugin author flow.

`nanook probe <name>`

Read one collector once, print the metrics, exit. Doesn't open the admin port.

Flag	What
`--warmup <ms>`	Discard a first read after this many ms before measuring

nanook probe cpu
nanook probe api --warmup 500

`nanook pulse`

Inspect or transform pulse metric frames.

Subcommand	What
`decode <path>`	Decode a binary `.pulse` frame into canonical text (`-` reads stdin)
`encode <path>`	Encode a pulse text file into a binary frame on stdout
`cat <url>`	Scrape a pulse HTTP endpoint and render the batch (`-f text`/`-f wire`)

`nanook discover`

Auto-detect collectors on this host. Alias: scan.

Flag	What
`--print`	Print resulting TOML to stdout instead of writing to disk
`--merge`	Append to an existing config rather than refusing to overwrite
`--force`	Overwrite the config file even if it exists
`--yes`	Skip interactive picking, accept all suggestions
`--list`	List the available detector groups and exit
`--include <list>`	Comma-separated detector groups to keep
`--exclude <list>`	Comma-separated detector groups to drop

See Discovery for behaviour.

`nanook ctl`

Talk to a running agent's admin server. See ctl.

`nanook tui`

Live ratatui dashboard against a running agent. Aliases: dash, dashboard. See TUI.

`nanook keygen`

Generate an ed25519 identity (SSH-style). Alias: key. The same wire format covers admin auth and signing trust roots; the only difference between the two is which storage dir and config table the key ends up in. See Trust for the role table.

Flag	What
`--path <file>`	Output path. The public half is written to `<path>.pub`. Defaults from `--kind`.
`-k, --kind <role>`	`admin` (default, writes `~/.nanook/admin/id_ed25519`) or `signing` (writes `~/.nanook/signing/id_ed25519`)
`-m, --comment <text>`	Comment recorded next to the key (default `$USER@$HOSTNAME`)
`--force`	Overwrite an existing identity

`nanook self`

Operations that touch the nanook binary itself. Alias: this.

Op	What
`install` / `uninstall` / `update`	Self-installer (see below)
`sign`	Append a signed-manifest trailer to a nanook binary in place
`verify`	Verify the running (or named) binary against `[self.signature].signers`
`trust list` / `add <line-or-path>` / `remove <fingerprint>`	Manage `[self.signature].signers`

nanook plugins mirrors the trust ops: nanook plugins trust list / add / remove against [plugins.signature].signers. Both surfaces edit nanook.toml in place, preserving comments and unrelated keys. Full reference at Trust.

`nanook self install`

Install the running nanook binary into a $PATH directory.

Flag	What
`--to <path>`	Target dir or file. Default: first writable `$PATH` entry, preferring `$HOME`.
`--symlink`	Symlink instead of copying (useful for `cargo build` updates in place)
`--force`	Overwrite an existing binary at the target

`nanook self uninstall`

Remove the nanook binary. Aliases: rm, remove.

Flag	What
`--from <path>`	Target binary or directory. Defaults to the running binary.
`--force`	Confirm self-removal when the target is the running binary

`nanook self update`

Replace the running binary with the latest (or pinned) release. Aliases: up, upgrade.

Flag	What
`--version <tag>`	Pin a release tag (e.g. `v0.1.0`). Defaults to latest.
`--check`	Resolve the release URL and exit without downloading
`--force`	Apply even when the pinned version matches the current binary
`--skip-verify`	Skip sha256 verification of the downloaded tarball
`--preset <name>`	Override the preset to download (`full`, `server`, `slim`, `minimal`)

`nanook doc [topic]`

Print docs for a collector, adapter, action, DSL topic, or diagnostic code. With no argument, lists every registered kind plus the topic catalogue and a per-crate count of error codes. Aliases: docs, help.

nanook doc                                           # list everything
nanook doc cpu                                       # cpu collector reference
nanook doc filter                                    # filter DSL reference
nanook doc unknown_collector                         # match by slug across kinds
nanook doc nanook::engine::unknown_collector          # exact diagnostic code

Restrict the lookup to one category with --kind:

nanook doc unknown_collector --kind error            # only the error page
nanook doc webhook --kind adapter                    # webhook adapter, not the action
nanook doc --kind error                              # list every diagnostic code, grouped

--md prints the markdown body to stdout instead of styled terminal output (handy for piping).

--export <dir> walks every registry plus the diagnostic-code catalog and writes Markdown into <dir>/reference/<category>/<slug>.md and <dir>/errors/<crate>/<slug>.md. The docs site uses this via pnpm run build:docs. Hand-written prose lives next to each generated page as a .prose.md sidecar that survives exports. See Reference and Errors.

Exit codes

0 on success, non-zero on error. Errors are surfaced through miette diagnostics; usage and runtime errors are not separated today.

Environment variables

Var	What
`MIETTE_NARRATED`	Set to `1` to render diagnostics in prose form
`NO_COLOR`	Disable ANSI colours in diagnostics, terminal output, and the TUI
`NANOOK_IDENTITY`	Path to a default ed25519 client identity for `nanook ctl` / `nanook tui`