nuncio/docs/RUNNING.md

Running Nuncio (dogfooding guide)

How to build, run, and use the daemon + CLI locally. These steps are verified on Windows (the daemon boots and the CLI round-trips over real gRPC + the OS keyring). Commands use nuncio-cli.exe; on macOS/Linux drop the .exe.

Status: pre-alpha. The mail spine (accounts, sync, read, send) is real and works, but the IMAP/SMTP engines have so far only been exercised against mock servers — your first real mail sync is the first live-server test, and it may surface real-world issues (server quirks, auth methods, TLS). That's the point of dogfooding; report anything odd and it becomes a fix.

1. Build

cargo build-release          # alias for: build --release -p nunciod -p nuncio-cli

Produces two self-contained executables (copy them anywhere; they only need the network and the OS credential store):

• target\release\nunciod.exe — the daemon (the product)
• target\release\nuncio-cli.exe — the CLI (how you drive it)

(Use plain cargo build -p nunciod -p nuncio-cli for a faster debug build while we're iterating.)

2. Start the daemon

target\release\nunciod.exe

It runs in the foreground and:

• serves the gRPC API on 127.0.0.1:9420 (loopback only) — services System, Accounts, Mail, Filters, Export, Audit, all bearer-token authenticated;
• opens its database at %USERPROFILE%\.nuncio\nuncio.db (override with NUNCIO_DB_PATH); the ~/.nuncio directory is created on first run;
• provisions its keys + the CLI's bearer token in Windows Credential Manager (never on disk);
• the autonomous auto-updater is intentionally disabled (pending a Phase 4 fail-open fix).

Leave it running; Ctrl+C stops it. Use the CLI from a second terminal.

3. Use it

:: confirm the CLI reaches the daemon (verified):
nuncio-cli.exe system status                 ::  -> "Idle (nunciod v0.1.0, 127.0.0.1:9420)"

:: add your real account (defaults target mail.kof22.com:993/:465; prompts for the
:: password, which goes straight to the OS keyring):
nuncio-cli.exe account add --email you@kof22.com
        :: override if needed: --imap-host --imap-port --smtp-host --smtp-port --imap-mode --smtp-mode
nuncio-cli.exe account list

:: the real spine:
nuncio-cli.exe mail sync                      :: real IMAP fetch -> local store
nuncio-cli.exe mail list
nuncio-cli.exe mail read --id <message-id>
nuncio-cli.exe mail search --query "invoice"
nuncio-cli.exe mail send --to a@b.com --subject "hi" --body "test"

:: filters, folders, etc.:
nuncio-cli.exe filter list
nuncio-cli.exe folder list

Add --json to any command for machine-readable output. nuncio-cli.exe <noun> --help lists every verb and flag.

Following & auditing the daemon

nunciod runs a layered tracing subscriber (crates/nunciod/src/logging.rs); nuncio-cli runs its own, separate, stderr-only subscriber for its own logs. Neither ever writes a bearer token or an account password to a log line.

Daemon log levels

nunciod's console (stderr) and rotating file sinks share one filter, resolved once at startup with this precedence:

1. NUNCIO_LOG — a tracing-subscriber EnvFilter directive (e.g. info, debug, nunciod=debug,tower=warn). Wins over RUST_LOG if set to a non-blank value.
2. RUST_LOG — same directive syntax; used when NUNCIO_LOG is unset/blank.
3. Default: info.

A malformed directive never crashes the daemon — it falls back to the default and logs a warn! once the subscriber is live.

:: run the daemon at debug level for one session
set NUNCIO_LOG=debug
target\release\nunciod.exe

Log file location

The rotating file sink writes daily-rotated files next to the database, under a logs/ sibling directory: <data_dir>\logs\nunciod.log.<date> (e.g. %USERPROFILE%\.nuncio\logs\nunciod.log.2026-07-30). If the log directory cannot be created, the daemon degrades to stderr-only logging (with a warn!) rather than failing to start.

JSON log output

Set NUNCIO_LOG_FORMAT=json to switch the file sink to one JSON object per line, for machine ingestion (e.g. shipping to a log aggregator). The console sink always stays human-readable, since it's for an operator watching a terminal. Any other value (or unset) keeps the file sink human-readable too.

Correlating one request's logs (request_id)

Every gRPC call nunciod handles opens a root tracing span carrying a per-process request_id (<process-start-tag>-<counter>), the RPC method path, and the peer address; every log line emitted while that call is handled — auth accept/reject, handler-level events, the terminal gRPC request completed line with status + elapsed time — inherits it. To follow one request end-to-end, grep the daemon log for its request_id:

:: human-readable file sink
findstr "a1b2c3d4e5f6-00000017" "%USERPROFILE%\.nuncio\logs\nunciod.log.2026-07-30"

:: JSON file sink (NUNCIO_LOG_FORMAT=json), pick a request_id from the
:: completion line's fields, then filter every line for it:
findstr "\"request_id\":\"a1b2c3d4e5f6-00000017\"" "%USERPROFILE%\.nuncio\logs\nunciod.log.2026-07-30"

(On macOS/Linux, use grep in place of findstr.) There is currently no way to read a request's request_id back from the CLI's own output — it is visible only in the daemon's logs, since it is a server-side correlation identifier assigned when the RPC arrives.

CLI verbosity (-v/-vv/-vvv)

nuncio-cli logs to stderr only — command output (including --json payloads) always goes to stdout, so redirecting or piping stdout is never polluted by log lines. By default the CLI logs only warnings. Repeat -v to raise the level:

nuncio-cli.exe mail sync              :: warn only (default)
nuncio-cli.exe -v mail sync           :: info
nuncio-cli.exe -vv mail sync          :: debug
nuncio-cli.exe -vvv mail sync         :: trace

NUNCIO_LOG/RUST_LOG, if set (same precedence as the daemon: NUNCIO_LOG beats RUST_LOG), override the -v count entirely — useful for scoping a directive to a specific module (e.g. NUNCIO_LOG=nuncio_cli=trace) without turning on trace logging for every dependency -vvv would also enable.

The dogfooding loop

Use it for real; when something breaks or feels wrong, tell me (or I'll hit it too). I reproduce against the real path, fix it, commit, and you pull dev. Because the toolchain is pinned, every fix is validated locally exactly as CI would validate it — so fixes land without waiting on CI.