Riferimento CLI

Work in progress — content may be incomplete.

L’intera superficie del comando warden, raggruppata per argomento.

Cos’è

Un indice di riferimento per warden, il singolo binario che fa parte di purge-warden. Copre ogni sotto-comando di livello superiore, le flag che ognuno accetta, e gli exit code su cui uno script può fare affidamento. I verbi per-entità (warden device …, warden blocklist …, warden profile …) sono documentati nelle rispettive pagine “configure”; qui raccolgo i verbi globali e quelli del config tree che non appartengono a una singola entità.

La forma è intenzionale. Warden non espone una grammatica generica config get <chiave> / config set <chiave> <valore>. I modi supportati per mutare lo stato sono:

warden config edit per i campi sotto [server] e [upstream] — il TOML master, aperto in $EDITOR, validato al salvataggio.
Verbi CRUD per-entità per tutto il resto (warden device add, warden blocklist set, warden profile remove, warden subnet add, warden local-dns add, warden schedule add, warden category …). Ognuno triggera un hot-reload automatico del daemon in esecuzione.
warden config restore <archivio> per ripristinare un albero di configurazione noto come funzionante in un’unica operazione.

Convenzioni

Privilegi. Qualunque cosa muti la configurazione su disco richiede permesso di scrittura sul TOML master. In un’installazione di default (/etc/purge-warden/) significa sudo. I verbi di sola lettura (show, list, lint, diff) no.
Discovery. Senza flag --config, Warden risolve il master in questo ordine: ./config.toml → $XDG_CONFIG_HOME/purge-warden/config.toml → /etc/purge-warden/config.toml → /var/lib/purge-warden/config.toml (legacy). Sorgente: src/cli/config_discovery.rs:49-65.
Atomicità. Ogni scrittura passa per atomic_write_and_validate: file temp nella stessa directory, validazione, rename POSIX. Il file live è intatto in caso di fallimento. Sorgente: src/config/atomic_write.rs.
Hot reload. I verbi CRUD per-entità ricaricano il daemon automaticamente via IPC autenticato. warden config edit no — ricarichi deliberatamente con warden reload.
Output. La maggior parte dei verbi di lettura stampa su stdout nel suo formato naturale (TOML per config show, tabelle in chiaro per device list). Il flag --json è supportato su un sottoinsieme di verbi di lettura (status, device list, stats *, logs --format json) ma non su nessun sotto-comando di warden config.

`warden config`

L’intera superficie del config-tree vive sotto warden config. Ci sono sette verbi e solo sette — set e get non esistono. Sorgente: src/cli/mod.rs:322-364, src/main.rs:189-227.

Comando	Scopo
`warden config show`	Stampa la config su disco o effettiva.
`warden config edit`	Apre il master in `$EDITOR`; valida al salvataggio.
`warden config lint`	Valida senza modificare.
`warden config validate`	Alias di `lint` (mantenuto per retrocompatibilità).
`warden config diff`	Confronta due configurazioni.
`warden config backup`	Snapshot del config tree in `tar.gz`.
`warden config restore`	Sostituisce l’albero live da un archivio, poi SIGHUP.

`warden config show`

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

Stampa il TOML master su stdout.

Flag	Default	Effetto
`--resolved`	off	Stampa la config effettiva dopo risoluzione include e riempimento default.
`--annotate`	off	Annota ogni valore con il file e la linea da cui arriva.
`--section <nome>`	tutto il file	Stampa solo la sezione di livello superiore indicata (es. `server`, `upstream`).

L’output è sempre TOML; non c’è --json. Per il parsing automatico, fai una pipe con tomlq, taplo o yq -p toml. Sorgente: src/cli/commands/config/show.rs.

`warden config edit`

warden config edit

Nessuna flag. Apre il master in $EDITOR (oppure $VISUAL, con fallback su vi). All’uscita dall’editor, l’handler esegue il validatore v1 completo (loader::load_config); se la validazione fallisce, il file live è invariato e l’errore è stampato con file:linea.

Non ricarica da solo. Lancia poi warden reload per applicare.

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

`warden config lint`

warden config lint
warden config validate    # alias

Valida la config su disco senza modificarla.

Exit	Significato
`0`	Pulito.
`1`	Errori di validazione. Ognuno è stampato con file:linea.
`2`	Riservato a warning (oggi stessa superficie di 0).

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

`warden config diff`

warden config diff <altro>

Confronta il master live con <altro>. L’argomento può essere il path di un file, una directory di backup estratto, o qualsiasi TOML leggibile dal loader v1.

Exit	Significato
`0`	Identici.
`1`	Differenze stampate.
`2`	Un lato non si carica (refuso, schema sbagliato, file non raggiungibile).

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

`warden config backup`

warden config backup [--out <dir>]

Scrive un archivio tar.gz del config tree (master + ogni sorella *.d/ esistente) in <config-parent>/backups/config-<UTC-timestamp>.tar.gz. Con --out <dir>, scrive in <dir>/config-<UTC-timestamp>.tar.gz. La directory deve esistere.

Il filename usa sempre YYYYMMDDTHHMMSSZ; solo la directory padre è configurabile. Niente --json, niente cifratura, niente manifest.

Per i contenuti inclusi/esclusi e una guida più approfondita, vedi backup e ripristino.

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

`warden config restore`

warden config restore <archivio>

Valida <archivio> con il loader v1, sostituisce atomicamente il master live, sostituisce ricorsivamente ogni sorella *.d/ contenuta nell’archivio e segnala al daemon con SIGHUP se è presente un PID file.

Exit	Significato
`0`	Ripristinato. SIGHUP recapitato, se applicabile.
`1`	Validazione fallita. L’albero live è invariato.
`2`	Errore I/O: archivio mancante, malformato, o scrittura fallita.

Il master pre-restore viene conservato come <live>.pre-restore-<UTC-timestamp> come via di rollback (solo il master — le sorelle .d/ vengono sostituite, non salvate).

Per semantica e flussi di recupero, vedi backup e ripristino.

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

`warden reload`

warden reload

Invia al daemon un comando di reload IPC autenticato. Si usa dopo warden config edit per applicare il nuovo master senza riavvio. I verbi CRUD per-entità lo fanno già automaticamente — chiamare warden reload dopo di loro è un no-op innocuo.

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

Vedi anche

Backup e ripristino — guida operativa per i due verbi config.
Impostazioni globali — cosa va nel TOML master e come modificarlo.
Riferimento TOML — ogni campo che il validatore controlla.
Percorsi file — dove Warden legge e scrive su disco.
Variabili d’ambiente — $EDITOR, $XDG_CONFIG_HOME, e simili.