Observability Commands
Reference for coven status, familiars, skills, memory, research, calls, logs prune, and vacuum.
5 min read
These commands are read-only views of the same state the daemon API serves. They work without a running daemon — they read the same ~/.coven files and SQLite store — and each takes --json for machine-readable output that carries the same body as the corresponding daemon API route.
| Command | Human view | --json body |
|---|---|---|
coven status | Ecosystem overview | Composition of GET /api/v1/health and GET /api/v1/overview |
coven familiars | Familiar roster table | GET /api/v1/familiars |
coven familiars <id> | One familiar's Ward surface (tiers, protected paths) | GET /api/v1/familiars/:id/ward |
coven skills | Skill inventory | GET /api/v1/skills |
coven memory | Familiar memory file table | GET /api/v1/memory |
coven research | Research loop log | GET /api/v1/research |
coven calls | Delegation ledger (pass an id for a detail view) | GET /api/v1/coven-calls |
Status
coven status (alias coven overview) is the "what is my coven doing" front door. It complements coven doctor — is my setup healthy? — with runtime state: daemon liveness, open sessions, active familiars, installed skills, research iterations, and hub node availability when executor nodes are registered.
coven status
coven status --json # { "health": ..., "overview": ... }Roster, skills, memory, research, calls
coven familiars # roster from ~/.coven/familiars.toml
coven familiars charm # one familiar's declared Ward surface (tiers)
coven skills # installed skills from ~/.coven/skills/
coven memory # familiar memory files from ~/.coven/memory/
coven research # research loop log from ~/.coven/research/
coven calls # Coven Calls delegation ledger
coven calls <call-id> # one call in detailEach command's empty state points at the file or flow that populates it, so a fresh install can navigate the ecosystem without reading source.
Relay configuration recovery
The optional mobile relay transport is experimental. coven memory mobile relay status --json reports saved configuration rather than live connectivity. If mobile/relay.json under COVEN_HOME is corrupt, oversized or uses an unsupported version, configuration commands fail closed and name the recovery command. JSON decoding errors report the category and line/column without reproducing saved field names or values.
In a Coven build that includes the relay reset command, inspect its help and explicitly confirm discarding relay settings:
coven memory mobile relay reset --help
coven memory mobile relay reset --yes
coven memory mobile relay status --json--yes confirms removing all relay endpoints and their configured certificate trust. Reset writes a disabled configuration with no endpoints; running relay connections close when the daemon reloads it. Device keys, host identity, paired devices, grants and direct gateway settings are retained. Without --yes, reset refuses to change configuration. Filesystem protections still apply: reset rejects symlinks, non-regular files and unsafe permissions. It does not repair those conditions.
After reset, add the intended WSS endpoint again with coven memory mobile relay add --endpoint wss://relay.example.test/ws. Relay access stays disabled until explicitly enabled with coven memory mobile relay enable, which requires an existing host identity. Restart the daemon to apply initial enablement. No relay endpoint is selected automatically.
Log retention
coven logs prune applies both local retention windows: raw artifacts (short window) and redacted session events.
coven logs prune --dry-run # report what would be pruned
coven logs prune # prune expired rows
coven logs prune --raw-days 3 --event-days 14 # override the windowsBoth windows are clamped to at least 1 day. Flags win over configured defaults.
Store repair
coven vacuum repairs and compacts the local session store (~/.coven/coven.sqlite3): it rebuilds the full-text event index when needed and runs a SQLite integrity check.
coven vacuumRun it when coven sessions search misbehaves or after unclean shutdowns.
Related
- Sessions for session listing and rituals.
- Doctor for setup checks rather than runtime state.
- Daemon observability for the daemon-side view.
- Sessions for status semantics and record management.
Create a familiar
coven familiar create <name> (also coven familiars create <name>) adds a familiar to the roster and creates its workspace. Inspect coven familiar create --help for current template and output options before creating one. Roster membership is declared identity, not an execution authority grant. Existing coven familiars listing and per-familiar inspection remain available.
For daemon-owned routine diagnostics and one-off familiar work, see Operator diagnostics and Familiar missions.
Experimental relay configuration
Source builds with returning-device transport can use outbound relays for already-paired devices. Relay access starts disabled, has no built-in endpoint, and requires explicit wss URLs with validated TLS. It does not enroll a device, rotate an identity, or widen a grant. An existing client first needs authenticated provisioning over its pinned channel; configuring a broker alone does not establish a working client connection.
coven memory mobile relay add --endpoint wss://relay.example.test/ws
coven memory mobile relay add --endpoint wss://private-relay.example.test/ws --ca-certificate /path/to/ca.pem
coven memory mobile relay enable
coven memory mobile relay status --json
coven memory mobile relay disable
coven memory mobile relay remove --endpoint wss://relay.example.test/wsAt most four endpoints are retained. An explicit CA list replaces public roots for that endpoint while retaining hostname checks; it never disables TLS verification or changes pinned device identities. add preserves current enablement, remove disables access when the last endpoint is removed, and enable requires an existing host identity. Enabling relay access on an already-running daemon requires restart; disable and endpoint/trust changes cancel affected live workers. Status reports configuration counts and enablement, not live connectivity, broker URLs, rooms, credentials, or successful device acceptance. Direct HTTPS listener configuration is separate. Native fixtures and the source transport contract do not establish real mobile/network acceptance or waive independent review.
Returning-device v2 and migration limits
Newer experimental source builds use durable per-device routing generations and counters for direct and relay transport. Once a pairing adopts v2, missing, corrupt or fenced state refuses access; it never falls back to legacy routing. The daemon uses a four-counter rendezvous window and one shared listener budget of at most 512 rooms. listenerLimit in the private version-1 relay configuration may reduce that ceiling, including to zero. A configured budget is a resource limit, not permission to connect or a guarantee of availability. Lowering the limit restricts new listener acquisition; existing listeners remain until released. Use coven memory mobile relay disable to close live relay access through the reload path. V2 prepare, acknowledge, resync and recover controls require authenticated direct ingress. The four-counter window has an accepted availability edge: sufficiently advanced or lost attempts can require explicit direct resync rather than seamless relay recovery.
An enabled pinned HTTPS gateway can also accept direct WSS at /ws, with fresh endpoint authentication and current-grant checks. Direct/relay migration retains one pairing and the exact signed pending operation. A failed candidate leaves the old channel selected; a successful handoff does not make an old-channel failure authoritative over the replacement. An exchange error leaves the operation outcome uncertain: reconcile its effect before deciding to retry. A replay refusal does not prove that the original operation had no effect. This interface supplies no automatic application retry, persistent client queue or automatic LAN discovery.
Private routing files intentionally retain restart material. CLI-owned zeroizing buffers do not erase copies inside the locked Noise dependency or plaintext HTTP/JSON serialization, swap, crash dumps or other system copies. Keep provisioning inside pinned authenticated transport and out of logs. These native helpers and controlled local fixtures are not a shipped mobile client, physical Wi-Fi/cellular acceptance or independent security certification. For an old snapshot, use the separate mobile authority restore procedure; copying files alone cannot establish current authority.
Last updated on