Skip to content

cli-observe.md

Latest commit

 

History

History
196 lines (157 loc) · 8.75 KB

cli-observe.md

File metadata and controls

196 lines (157 loc) · 8.75 KB
Raw
summary Read-path observability commands: status, familiars, skills, memory, research, calls, hub, scheduler, travel, and session inspection.
read_when
Checking what your coven is doing from a terminal
Scripting against Cave-parity read views
title coven observability commands
description Reference for coven status, familiars, skills, memory, research, calls, hub, scheduler, travel, and sessions show/events/log: terminal parity with the CovenCave dashboard and the daemon API.

Observability commands

Everything the CovenCave dashboard reads is also visible from the terminal. The commands in the table below are read-only and each takes --json for machine-readable output that carries the same body as the corresponding daemon API route. Most read persisted ~/.coven files and SQLite state without a running daemon; coven hub status requires the daemon's live hub snapshot. coven memory open is a separate local-dashboard launcher described after the table.

Command Human view --json body
coven status Ecosystem overview { "health": …, "overview": … } composition of GET /api/v1/health and GET /api/v1/overview
coven familiars [<id>] Roster table, or one familiar's Ward surface (tiers, protected paths, principal binding) GET /api/v1/familiars[/:id/ward]
coven skills Skill inventory GET /api/v1/skills
coven memory Memory file table GET /api/v1/memory
coven research Research loop log GET /api/v1/research
coven calls [<id>] Delegation ledger (list or detail) GET /api/v1/coven-calls[/:id]
coven hub status Hub role, nodes, queue depth (requires a running daemon) GET /api/v1/hub/status
coven hub nodes Executor node table GET /api/v1/hub/nodes
coven hub jobs [--state <s>] Job table GET /api/v1/hub/jobs[?state=s]
coven hub routing Routing decisions GET /api/v1/hub/routing
coven sessions show <id> One session's record GET /api/v1/sessions/:id
coven sessions events <id> Recorded events (redacted) GET /api/v1/sessions/:id/events
coven sessions log <id> Log lines GET /api/v1/sessions/:id/log

coven memory open

coven memory open starts or reuses the local Coven daemon, then launches the opt-in @opencoven/coven-memory-dashboard companion on a validated loopback address. The companion installs separately from the npm wrapper; when it is not installed the command prints the install instruction and exits. It does not require the dashboard source repository or a separate coven daemon start step. It does not accept --json; coven memory and coven memory --json retain the read-only list behavior above. The npm wrapper requires Node.js 24 or newer for the dashboard only, while other wrapped Coven commands continue to support Node.js 18 or newer.

coven status

The "what is my coven doing" front door. Complements coven doctor (is my setup healthy?) with runtime state. This is a Unix-like example:

Coven status

  daemon     running (pid 63321, socket /path/to/coven.sock)
  version    0.1.7
  sessions   3 open
  familiars  1 active / 2 total
  skills     4 installed
  research   12 iterations (last Δ 2)
  hub        1/2 nodes available (details: coven hub status)

Next: coven sessions · coven familiars · coven run <harness> "<task>"

On Windows, the daemon line reports diagnostic named-pipe metadata instead of a .sock path. Clients needing a connection path use state.daemon_ipc from coven config paths --json.

  • The familiars line counts a familiar as active when it has an open session; the roster comes from ~/.coven/familiars.toml.
  • The research line appears only when the research log has rows; the hub line appears only when executor nodes are registered — a fresh single-host install stays quiet instead of alarming.
  • coven overview is an alias for readers coming from the API route name.

coven status --json prints a CLI-level composition of the two stable API bodies (this shape is owned by the CLI, like coven daemon status --json):

{
  "health": { "ok": true, "apiVersion": "coven.daemon.v1", "…": "…" },
  "overview": { "open_sessions": 3, "total_familiars": 2, "…": "…" }
}

The health.daemon block reflects a live daemon only; a stale status file shows up as daemon: null here, while coven daemon status --json reports the stale state explicitly.

Ward surface inspection

coven familiars <id> reads the same ward.toml the daemon's Ward-enforced write path (POST /api/v1/familiars/:id/edits) adjudicates — one source of truth for what a familiar's principal has protected:

Familiar sage — Ward surface

  workspace  /path/to/familiar-workspace
  principal  SHA256:principal-key
  unmatched  tier 2 (logged)

  tier              path
  0      protected  SOUL.md
  2      logged     memory/
  3      free       scratch/

  protected: SOUL.md

Tiers: 0 protected (Gate-1 principal signature required), 1 reviewed (held for Gate-3 coherence), 2 logged (written with a Gate-4 audit record), 3 free. unmatched is the tier assigned to paths no surface entry matches. An unknown id fails with familiar_not_found; a familiar without a ward.toml fails with ward_not_configured — the same fail-closed shapes the write path returns.

Session inspection without a PTY

coven attach replays and follows interactively. For scripts, CI, and quick glances, the sessions subcommands read the same ledger non-interactively:

coven sessions show 9099                   # metadata; unique id prefixes work
coven sessions events 9099 --limit 100     # recorded events, redacted payloads
coven sessions events 9099 --after-seq 42  # resume from a cursor
coven sessions log 9099                    # replay-style log lines, then exit

events --json returns the paginated envelope { "events": [...], "nextCursor": { "afterSeq": n }, "hasMore": bool } — the same contract as GET /api/v1/sessions/:id/events, so a shell loop can page with --after-seq exactly like an API client. Event payloads are redacted by default before display, matching the API.

Hub operations without curl

coven hub replaces hand-rolled curl --unix-socket calls for the read side of hub operations (see HUB-OPERATIONS for the write-side protocol, which stays machine-to-machine):

coven hub status                 # role, hubId, node availability, queue depth
coven hub nodes                  # registered executors with capabilities
coven hub nodes <id>             # one node: transport, health, capabilities
coven hub jobs --state queued    # global queue by state
coven hub jobs <id>              # one job: state, route, payload preview
coven hub dispatch <jobId>       # executor dispatch record + result envelope
coven hub routing                # job→node routing decisions

Every verb takes --json, which prints the matching /api/v1/hub/* response body unchanged, so scripts and humans read the same contract.

Scheduler and travel debugging without curl

coven scheduler and coven travel follow ids the hub views hand out — coven hub routing rows carry a DECISION column, and redispatch responses carry a loopId — so operators can chase a routing decision without curl --unix-socket. The write side (decisions, redispatch, profiles, deltas) stays machine-to-machine, like the executor protocol:

coven scheduler decision <id>       # one decision: job, target, reason, inputs
coven scheduler loop <loopId>       # loop recovery state + preserved subqueue
coven travel state --client <id>    # travel/handoff state machine view
coven travel state --client <id> --profile <profileId>   # + profile freshness

Each verb takes --json and prints the matching /api/v1/scheduler/* or /api/v1/travel/state response body unchanged. Unknown ids fail closed with the structured API error (scheduler_decision_not_found, scheduler_loop_not_found, travel_profile_not_found).

Empty states teach setup

Each command's empty state points at the file or flow that populates it, so a fresh install can navigate the ecosystem without reading source:

$ coven familiars
No familiars configured.
Add [[familiar]] entries to ~/.coven/familiars.toml to build your roster.

In the interactive surfaces

The same views are reachable without leaving the interactive surfaces: the Cast composer and the chat UI accept /status (alias /overview), /familiars, /skills, /memory, /research, /calls, and /hub, plus the bare words (status, familiars, roster, …). Every card shows the scriptable coven <view> spelling so the terminal form stays discoverable. status in a composer means this ecosystem overview; setup checks stay on doctor/health.