Files
nuncio/docs/RUNNING.md
James Maes 514f8eb15b docs: audit pass — align all docs and repo meta with reality
Sweep every README/doc for accuracy and remove fabricated or stale content:
- README/CLAUDE: add the live roadmap-page link and a rule to keep the rendered
  page in sync with docs/ROADMAP.md; fix the stale cov alias and the
  already-moved-shells note.
- .github/CONTRIBUTING+SECURITY: drop the fabricated nuncio.mx site link and the
  aspirational release/security claims; state honest pre-alpha status.
- docs/RUNNING, DEVELOPING, ARCHITECTURE, BACKLOG, Home, NSQL spec, corruption
  notes, proto/README: correct crate count/list, service list, CLI flags, phase
  status, and remove claims of unshipped/removed things (IPC-as-current,
  hardcoded-keys, unwired engines); mark superseded api-surface-draft historical.
- Remove the fabricated benchmark baked into nsql_pipeline.svg and delete the
  orphaned ipc_sequence.svg (depicted the removed IPC with a fake timing).
2026-07-28 10:49:48 -05:00

78 lines
3.0 KiB
Markdown

# 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.
## 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.