Skip to content

cli-core-functionality.md

Latest commit

 

History

History
157 lines (118 loc) · 9.69 KB

cli-core-functionality.md

File metadata and controls

157 lines (118 loc) · 9.69 KB
Raw
title Coven CLI core functionality for developers
summary The command ownership map, access contract, and verification loop for maintaining Coven's core CLI and daemon surfaces.
read_when
Changing a core coven command or flag
Debugging whether a local Coven installation can reach its core runtime
Updating CLI, daemon, or workflow documentation
description Developer guide to Coven CLI command ownership, local runtime access, safe verification, and documentation maintenance.

Coven CLI core functionality for developers

This is the maintainer map for the CLI paths that make Coven useful: discover a ready environment, reach the local daemon, launch a project-scoped harness session, and inspect or manage the resulting session. It complements the user-facing CLI reference, not replaces it.

Core access contract

Core functionality is reachable when all of these are true:

  1. coven doctor can inspect a writable COVEN_HOME and reports at least one usable harness.
  2. coven daemon status --json can reach the same-user local socket. A stopped daemon is an expected first-run state; a stale daemon is not.
  3. A command runs from an explicit project root, and any --cwd remains inside that root after canonicalization.
  4. The selected harness is available in the same shell environment as Coven. Provider authentication stays with that harness; Coven does not own provider credentials.
  5. The session ledger can persist metadata and events beneath COVEN_HOME.

Do not call the CLI healthy merely because --help renders. A healthy core path proves readiness, daemon reachability, and a read of the session ledger. A harness launch is a separate, intentional operation because it may cause model work.

Command ownership

User outcome CLI entry point Primary Rust owner Contract to preserve
Discover commands and route free-text input coven, coven chat, coven tui, coven help crates/coven-cli/src/main.rs, help.rs, tui/, engine.rs Bare Coven opens the interactive route; default top-level help stays concise (doctor, run, sessions, attach, daemon, status, help); coven help --all exposes the full public command map without leaking internal entrypoints.
Check local readiness coven doctor [--json] main.rs, harness.rs, paths.rs, daemon.rs Human output gives repair hints; JSON stays a single machine-readable document.
Control the daemon coven daemon start/status/restart/stop daemon.rs, api.rs, paths.rs One same-user local daemon owns the socket and state directory.
Launch work coven run <harness> <prompt> session_launch.rs, harness.rs, pty_runner.rs, store.rs Validate project root and cwd in Rust, construct argv safely, then record session/events.
Inspect and manage history coven sessions, coven attach, coven archive, coven summon, coven sacrifice, coven kill store.rs, daemon.rs, tui/ Archive is reversible; sacrifice and other destructive actions keep explicit confirmation.
Read runtime state coven status, coven familiars, coven skills, coven memory, coven research, coven calls, coven hub, coven scheduler, coven travel observe.rs, hub.rs, control_plane.rs Read surfaces do not silently become write paths.
Coordinate parallel work coven wt, coven claim, coven hooks parallel_protocol.rs Claims are shared through git's common directory and remain TTL-bounded.
Repair or diagnose a machine coven patch, coven pc, coven logs, coven vacuum patch.rs, pc.rs, store.rs Keep inspection separate from explicit write/repair confirmation.

main.rs is the authoritative parser and dispatch map. When a command changes, start there and follow its delegated module before changing documentation.

Progressive help is part of that parser contract:

  • coven --help and coven help stay focused on the core workflow while still documenting the bare interactive coven route above the command list.
  • coven help --all is the public inventory: every public top-level command appears once, grouped by user task, plus the machine-readable --json view.
  • coven help <command> should stay equivalent in useful content to coven <command> --help.
  • Hidden/internal entrypoints such as process-supervisor and coven daemon serve stay absent from the public help surfaces and JSON catalog.

JSON help contract

coven help --all --json prints the public command catalog as a single deterministic JSON document on stdout. Automation parses this document instead of scraping human help output. The example below is abbreviated; the real document lists every public command across all six groups.

{
  "schemaVersion": 1,
  "groups": [
    {
      "id": "start-and-launch",
      "title": "Start and launch",
      "commands": [
        {
          "name": "doctor",
          "summary": "Check local setup and print next steps (exits 1 when a blocking problem is found)",
          "docsUrl": "https://docs.opencoven.ai/docs/cli/doctor"
        }
      ]
    }
  ]
}

The contract to preserve:

  • schemaVersion is a number, currently 1. The key set of a given schema version is exact: no missing fields and no extras. Changing the shape or field semantics means shipping a new schema version, not mutating this one.
  • groups is a non-empty array. Group ids are lowercase kebab-case and fixed in this order: start-and-launch, configure-and-extend, session-lifecycle, observe-your-coven, coordinate-parallel-work, repair-and-administer.
  • Each command carries a kebab-case name, a one-line summary, and an absolute docsUrl on the stable https://docs.opencoven.ai/docs/ origin with no query parameters and a lowercase kebab-case fragment when one is present.
  • Output is byte-identical across runs and machines: fixed group and command ordering, no ANSI escapes even under --color=always, no machine-specific paths, and no dependence on locale, clock, or environment. stderr stays empty on success.
  • Coverage is complete and leak-free: every public top-level command appears exactly once, and internal entrypoints such as process-supervisor and coven daemon serve never appear.

Drift fails loudly instead of silently: crates/coven-cli/src/help.rs errors at render time when a public command lacks catalog metadata or when the catalog names an unknown command, so adding, renaming, or hiding a public command requires updating HELP_GROUPS in the same change. scripts/export-cli-help-contract.mjs validates a catalog snapshot's shape, leak checks, and URL constraints from a built binary, which keeps packaged consumers and CI honest:

node scripts/export-cli-help-contract.mjs --binary target/debug/coven --output help-contract.json

Access paths developers should exercise

Run these from a clean, representative project directory. They are ordered from read-only inspection to daemon activation; the final launch is intentionally opt-in.

# Concise discovery plus the grouped public inventory: no daemon or harness execution.
coven --help
coven help --all

# Readiness envelope: succeeds only when a usable local path exists.
coven doctor --json | jq -e '.ok'

# Daemon reachability and socket identity.
coven daemon status --json

# Session ledger read without opening the interactive browser.
coven sessions --json

If the daemon is stopped, start it deliberately and repeat the status check:

coven daemon start
coven daemon status --json

Only after those checks should a developer launch a harness session:

coven run codex "explain this repository in five bullets" --permission read-only

Use the harness selected by doctor; codex is an example, not a requirement. The core access guide gives the equivalent operator walkthrough.

Failure classification

Symptom Boundary to inspect First safe action
doctor reports no usable harness Shell PATH and harness-owned login Run the printed harness install/login hint, then rerun coven doctor.
daemon status is stale or cannot connect COVEN_HOME, socket, daemon lifecycle Read coven daemon status; then follow daemon troubleshooting.
Launch rejects a cwd Project-root and canonical-path guard Run from the intended project root; ensure --cwd resolves inside it.
Sessions cannot be listed Daemon/store reachability Check coven doctor --json, then coven daemon status --json.
JSON consumer breaks Command-specific serialization contract Verify the exact command's --json reference before changing stdout or stderr.

Never document a maintainer's absolute path, real session id, token, or provider environment dump. Use /path/to/project, session-1, and synthetic output in examples.

Documentation change checklist

When a CLI behavior changes, update the matching layer in the same change:

  1. docs/reference/cli.md for the command inventory and flags.
  2. The focused docs/reference/cli-*.md page for semantics and examples.
  3. A docs/guides/ workflow when the change affects an end-to-end task rather than one flag.
  4. README.md when it changes the first path a developer should discover.
  5. docs/API-CONTRACT.md for a socket/API compatibility change.
  6. scripts/onboarding-docs-test.mjs when a discovery link or core workflow must not regress.

For docs-only work, run:

node scripts/onboarding-docs-test.mjs
python scripts/check-secrets.py
git diff --check

Related