v0.4.8 Search docs… ⌘K
EN
EN

CLI reference

Work in progress — content may be incomplete.

The full surface of the warden command, grouped by subject.

What this is

A reference index for warden, the single binary that ships with purge-warden. It covers every top-level subcommand, the flags each accepts, and the exit codes a script can rely on. Per-entity verbs (warden device …, warden blocklist …, warden profile …) are documented inline in their own configure pages; this page collects the global and config-tree verbs that don’t fit a single entity.

The shape is intentional. Warden does not expose a generic config get <key> / config set <key> <value> grammar. The supported ways to mutate state are:

  • warden config edit for fields under [server] and [upstream] — the master TOML, opened in $EDITOR, validated at save.
  • Per-entity CRUD verbs for everything else (warden device add, warden blocklist set, warden profile remove, warden subnet add, warden local-dns add, warden schedule add, warden category …). Each of these triggers an automatic hot-reload of the running daemon.
  • warden config restore <archive> for restoring a known-good config tree as a single operation.

Conventions

  • Privilege. Anything that mutates the on-disk config requires write access to the master TOML. On a default install (/etc/purge-warden/) that means sudo. Read-only verbs (show, list, lint, diff) do not.
  • Discovery. With no --config flag, Warden resolves the master in this order: ./config.toml → $XDG_CONFIG_HOME/purge-warden/config.toml → /etc/purge-warden/config.toml → /var/lib/purge-warden/config.toml (legacy). Source: src/cli/config_discovery.rs:49-65.
  • Atomicity. Every write goes through atomic_write_and_validate: temp file in the same directory, validation, then a POSIX rename. The live file is untouched on failure. Source: src/config/atomic_write.rs.
  • Hot reload. Per-entity CRUD verbs reload the daemon automatically via authenticated IPC. warden config edit does not — you reload deliberately with warden reload.
  • Output. Most read verbs print to stdout in their natural format (TOML for config show, plaintext tables for device list). The --json flag is supported on a subset of read verbs (status, device list, stats *, logs --format json) but not on any warden config subcommand.

warden config

The whole config-tree surface lives under warden config. There are seven verbs and only seven — set and get do not exist. Source: src/cli/mod.rs:322-364, src/main.rs:189-227.

CommandPurpose
warden config showPrint the on-disk or effective config.
warden config editOpen the master in $EDITOR; validate at save.
warden config lintValidate without modifying.
warden config validateAlias for lint (kept for backwards compatibility).
warden config diffCompare two configs.
warden config backupSnapshot the config tree to tar.gz.
warden config restoreReplace the live tree from an archive, then SIGHUP.

warden config show

warden config show [--resolved] [--annotate] [--section <name>]

Prints the master TOML to stdout.

FlagDefaultEffect
--resolvedoffPrint the effective config after include resolution and default fill-in.
--annotateoffAnnotate each value with its source file and line.
--section <name>full filePrint only the named top-level section (e.g. server, upstream).

Output is always TOML; there is no --json. To machine-parse, pipe through tomlq, taplo, or yq -p toml. Source: src/cli/commands/config/show.rs.

warden config edit

warden config edit

No flags. Opens the master in $EDITOR (or $VISUAL, falling back to vi). On editor exit, the handler runs the full v1 validator (loader::load_config); if validation fails, the live file is unchanged and the error is printed with file:line.

Does not auto-reload. Run warden reload afterwards to apply.

Source: src/cli/commands/config/edit.rs.

warden config lint

warden config lint
warden config validate    # alias

Validates the on-disk config without changing anything.

ExitMeaning
0Clean.
1Validation errors. Each is printed with file:line.
2Reserved for warnings (currently same surface as 0).

Source: src/cli/commands/config/lint.rs.

warden config diff

warden config diff <other>

Compares the live master against <other>. The argument may be a file path, an extracted backup directory, or any TOML readable by the v1 loader.

ExitMeaning
0Identical.
1Differences printed.
2One side failed to load (typo, wrong schema, unreachable file).

Source: src/cli/commands/config/diff.rs.

warden config backup

warden config backup [--out <dir>]

Writes a tar.gz archive of the config tree (master + every existing *.d/ sibling) to <config-parent>/backups/config-<UTC-timestamp>.tar.gz. With --out <dir>, writes to <dir>/config-<UTC-timestamp>.tar.gz instead. The directory must exist.

The filename always uses YYYYMMDDTHHMMSSZ; only the parent directory is configurable. No --json, no encryption, no manifest.

For the included/excluded contents and a deeper walkthrough, see backup & restore.

Source: src/cli/commands/config/backup.rs.

warden config restore

warden config restore <archive>

Validates <archive> against the v1 loader, then atomically replaces the live master, recursively replaces every *.d/ sibling that the archive contains, and signals the daemon with SIGHUP if a PID file is present.

ExitMeaning
0Restored successfully. SIGHUP delivered if applicable.
1Validation failed. Live tree unchanged.
2I/O error: archive missing, malformed, or write-failed.

The pre-restore master is preserved as <live>.pre-restore-<UTC-timestamp> as a rollback path (master only — .d/ siblings are replaced, not backed up).

For semantics and recovery flows, see backup & restore.

Source: src/cli/commands/config/restore.rs.

warden reload

warden reload

Sends the daemon an authenticated IPC reload command. Use after warden config edit to apply the new master without a restart. Per-entity CRUD verbs already do this automatically — calling warden reload after them is a no-op but harmless.

Source: src/cli/commands/ipc_reload.rs.

See also