Skip to content

cli-sessions.md

Latest commit

 

History

History
88 lines (69 loc) · 3.02 KB

cli-sessions.md

File metadata and controls

88 lines (69 loc) · 3.02 KB
Raw
summary Browse, filter, and act on sessions.
read_when
Looking up sessions
title coven sessions
description Reference for coven sessions: list, inspect, filter, and export Coven harness sessions from the local SQLite ledger and append-only event log.

Usage

coven sessions [--manage | --plain | --json] [--all]
coven sessions search <query> [--json]
coven sessions show <session-id> [--json]
coven sessions events <session-id> [--after-seq <SEQ>] [--limit <N>] [--json]
coven sessions log <session-id> [--json]

coven sessions is the safest way to find a session id before attaching, archiving, summoning, or sacrificing. It reads the local store under COVEN_HOME and shows session records newest first.

Modes

Mode Use when
coven sessions You are in an interactive terminal and want the browser with actions.
coven sessions --manage You want to force the interactive browser even when auto-detection would choose text.
coven sessions --plain You need a copyable table for scripts, terminals, or diagnostics.
coven sessions --json You need machine-readable output for clients or dashboards.
coven sessions --all You need archived records as well as active records. Combine with --plain or --json when needed.

The plain table includes the full session id, status, harness, ritual state, and title. Empty active lists print the next commands to try:

coven doctor
coven run codex "explain this repo in 5 bullets"
coven sessions --all

Searching events

coven sessions search "migration OR release"
coven sessions search "session stuck" --json

coven sessions search runs full-text search over recorded event payloads. Use the JSON form when a client needs stable fields instead of terminal snippets.

Inspecting one session

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

These are the non-interactive counterparts to coven attach: they print and exit, so scripts and CI can read a session without a PTY. events --json returns the same paginated envelope as GET /api/v1/sessions/:id/events (events, nextCursor.afterSeq, hasMore). See observability commands for the full read-path surface.

Lifecycle commands

After copying a session id:

coven attach <session-id>
coven archive <session-id>
coven summon <session-id>
coven sacrifice <session-id> --yes

Archive hides a non-running session from active lists while preserving its record. Summon restores an archived session and replays it. Sacrifice is the permanent delete path.

Related