Observability Commands

Genie provides seven command groups for observability: events for the audit log, sessions for Claude Code session history, metrics for machine state, schedule for cron triggers, qa for self-testing, log for a unified real-time feed, and brief for session startup context.

Events

The genie events command group queries the PostgreSQL audit event log. Events are structured as OTel-compatible records covering API costs, tool usage, task transitions, and errors. Thirteen subcommands group into three layers: reading (list, errors, costs, tools, timeline, timeline-v2, summary, scan), streaming (stream, stream-follow, subscribe), and operations (migrate, admin). Reading commands hit the table directly; streaming commands tail events in real time (with stream-follow and subscribe targeting the v2 enriched surface); operations commands are one-shot migrations and sentinel-audited incident response.

`genie events list`

List recent audit events. Pass --v2 to switch to the enriched genie_runtime_events surface with TraceId/SpanId/Severity/Duration columns.

genie events list [options]

Option	Description
`--type <type>`	Filter by `event_type`
`--entity <entity>`	Filter by entity type or entity ID
`--since <duration>`	Time window, e.g., `1h`, `30m`, `2d` (default: `1h`)
`--errors-only`	Show only error events
`--limit <n>`	Max rows to return (default: `50`)
`--json`	Output as JSON
`-f, --follow`	Follow mode — real-time streaming (alias: `genie events stream`)
`--v2`	Use enriched `genie_runtime_events` surface with TraceId/SpanId/Severity/Duration columns
`--kind <prefix>`	Filter v2 rows by kind/subject prefix (e.g., `mailbox`, `agent.lifecycle`)
`--severity <level>`	Filter v2 rows by severity (`debug`\|`info`\|`warn`\|`error`\|`fatal`)

genie events list --since 30m --errors-only
genie events list --v2 --kind agent.lifecycle --severity warn

genie events list defaults to the last hour. Widen with --since 1d or narrow with --since 5m when chasing a specific incident.

For a walkthrough of rot.* and detector.* events and triage, see Detectors.

`genie events stream`

Stream audit + runtime events in real-time (tail -f style). Reach for this when you want a live firehose across both the legacy audit_events and the enriched genie_runtime_events surfaces — for example, while watching a wish execute or debugging a noisy agent.

genie events stream [options]

Option	Description
`--type <type>`	Filter by `event_type`
`--entity <entity>`	Filter by entity type or entity ID
`--errors-only`	Show only error events
`--kind <kind>`	Filter runtime events by kind (`tool_call`, `message`, `prompt`, etc.)
`--agent <agent>`	Filter runtime events by agent
`--audit-only`	Stream only `audit_events` (skip runtime)
`--runtime-only`	Stream only runtime events (skip audit)
`--all`	Show all events including noisy ones (`command_success`, etc.)
`--json`	Output as JSON

genie events stream --runtime-only --kind tool_call
genie events stream --errors-only --agent engineer-1

`genie events stream-follow`

Follow-stream enriched genie_runtime_events via PostgreSQL LISTEN/NOTIFY with an id-cursor for resumable consumption (v2). Unlike stream, this command is built for long-running sidecars that need to survive reconnects — pass --consumer-id and it picks up where it left off. The --kind flag accepts * globs for subject-tree subscriptions. For example, --kind 'detector.*' follows every event emitted by the detector subsystem. See Detectors for the catalog of kinds (sibling PR — page lands alongside this one).

genie events stream-follow [options]

Option	Description
`--follow`	Continuously follow the stream (default: `true`)
`--kind <prefix>`	Filter by subject/kind prefix — supports `` globs (e.g., `detector.`)
`--severity <level>`	Filter by severity (`debug`\|`info`\|`warn`\|`error`\|`fatal`)
`--since <duration>`	Seed window (e.g., `5m`, `1h`)
`--consumer-id <id>`	Persistent consumer id for cursor resume
`--json`	Output as NDJSON

# Follow all detector events at warn-or-higher severity
genie events stream-follow --kind 'detector.*' --severity warn

# Resume from a previous cursor under a stable consumer id
genie events stream-follow --consumer-id sentinel-ingest --since 5m --json

Mint a signed subscription token for genie events stream --follow. Tokens carry an RBAC role and optional restrictions on event types, LISTEN channels, TTL, and tenant — letting subscriber agents connect without sharing long-lived credentials.

subscribe requires a running scheduler/issuer with HMAC keys configured. The --types and --channels flags narrow (never widen) the role’s default permissions.

genie events subscribe [options]

Option	Description
`--role <role>`	RBAC role: `events:admin`\|`events:operator`\|`events:subscriber`\|`events:audit`
`--types <csv>`	Comma-separated allowed event types (subset of role defaults)
`--channels <csv>`	Comma-separated allowed LISTEN channels (subset of role defaults)
`--ttl <duration>`	Token time-to-live (e.g., `30m`, `1h`, `24h`). Defaults to `1h`.
`--tenant <id>`	Tenant id. Defaults to `default`.
`--subscriber-id <id>`	Stable id for the subscriber agent
`--json`	Output as JSON

genie events subscribe \
  --role events:operator \
  --subscriber-id sentinel-ingest \
  --ttl 24h \
  --json

`genie events errors`

Show aggregated error patterns.

genie events errors [--since <duration>] [--json]

Treat genie events errors as an incident-response tool. A sudden spike in an error pattern usually means a provider outage, a credential rotation, or a broken agent — investigate before spawning more work on top.

`genie events costs`

Cost breakdown from OTel API request events.

genie events costs [options]

Option	Description
`--today`	Show costs from the last 24h
`--since <duration>`	Time window (default: `24h`)
`--by-agent`	Group by agent
`--by-wish`	Group by wish
`--by-model`	Group by model
`--json`	Output as JSON

genie events costs --today --by-agent
genie events costs --since 7d --by-model

Every genie events subcommand supports --json. Pipe into jq for ad-hoc analysis — e.g., genie events costs --since 7d --by-model --json | jq '.[] | select(.usd > 1)' surfaces only models that cost more than $1 in the last week.

`genie events tools`

Tool usage analytics from OTel tool events.

genie events tools [options]

Option	Description
`--since <duration>`	Time window (default: `24h`)
`--by-tool`	Group by tool name (default)
`--by-agent`	Group by agent
`--json`	Output as JSON

`genie events timeline`

Full event timeline for a task, agent, wish, or trace ID. Shows all events associated with a specific entity in chronological order.

genie events timeline <entity-id> [--json]

genie events timeline task-6c3a2cf2
genie events timeline engineer-1

`genie events timeline-v2`

Render a causal tree for a trace_id from the enriched genie_runtime_events surface. Unlike timeline, which walks any entity type, timeline-v2 expects a trace id and reconstructs spans with OTel-style parent/child relationships — use it when chasing causality across agent/tool boundaries.

genie events timeline-v2 <trace-id> [options]

Option	Description
`--json`	Output as JSON

genie events timeline-v2 01JABCDEF0123456789GHJKMN --json

`genie events summary`

High-level stats: agents spawned, tasks moved, costs, errors.

genie events summary [--today] [--since <duration>] [--json]

`genie events scan`

Full server cost scan via ccusage. Scans all Claude Code sessions on the machine, not just genie-spawned ones.

genie events scan [options]

Option	Description
`--since <date>`	Start date in `YYYYMMDD` format
`--json`	Output as JSON
`--breakdown`	Show per-model breakdown

genie events scan
genie events scan --since 20260330 --breakdown

`genie events migrate`

Backfill legacy audit_events rows into genie_runtime_events as a one-shot migration. Useful when adopting the v2 enriched surface on an existing installation or recovering from a gap in the ingestion pipeline.

Run with --dry-run first to inspect row deltas; re-run without --dry-run to commit.

genie events migrate [options]

Option	Description
`--audit`	Migrate `audit_events` → `genie_runtime_events` with sentinel source tag
`--dry-run`	Report row deltas without writing
`--since <duration>`	Only migrate rows created within this window
`--limit <n>`	Cap the number of rows migrated per run
`--json`	Output summary as JSON

genie events migrate --audit --since 7d --dry-run
genie events migrate --audit --since 7d --limit 10000 --json

`genie events admin`

Incident-response admin commands (sentinel H6 audited). Every subcommand emits its own audit event so operator actions remain traceable in the chain.

genie events admin <subcommand> [options]

Subcommand	Description
`export-audit`	Produce a signed audit-chain bundle (emits `audit.export`)
`list-revocations`	List revoked token ids for a tenant
`revoke-subscriber`	Add a subscription token to the revocation list
`rotate-redaction-keys`	Rotate redaction + audit HMAC keys, preserving prior versions for lookup
`un-hash`	Admin reverse-lookup for a Tier-A hash (emits `audit.un_hash`)
`verify-chain`	Quick chain-integrity check (no export)

genie events admin verify-chain
genie events admin export-audit --tenant default

Run genie events admin <subcommand> --help for per-subcommand flags.

Enriched (v2) surface

“Enriched” refers to the genie_runtime_events table — a v2 superset of the legacy audit_events stream that adds OTel-style columns (trace_id, span_id, severity, duration_ms) plus a hierarchical kind taxonomy. It has no dedicated subcommand; instead, the enriched surface is reached via:

genie events list --v2 — table listing with enriched columns and --kind/--severity filters
genie events stream-follow — resumable LISTEN/NOTIFY stream with glob-enabled --kind
genie events timeline-v2 — causal-tree rendering for a trace_id
genie events migrate --audit — backfill legacy rows into the enriched surface

Use the v2 surface whenever you need trace/span correlation or subject-tree subscriptions; fall back to the legacy commands for simple audit queries.

Log

The genie log command provides a unified observability feed that aggregates transcripts, DMs, team chat, tool calls, and system events into a single stream.

`genie log`

Unified observability feed for an agent or team.

genie log [agent] [options]

Option	Description
`--team <name>`	Show interleaved feed for all agents in a team
`--type <kind>`	Filter by event kind: `transcript`, `message`, `tool_call`, `state`, `system`
`--since <timestamp>`	Only events after ISO timestamp
`--last <n>`	Show last N events
`--ndjson`	Output as newline-delimited JSON (pipeable to jq)
`--json`	Output as pretty JSON
`-f, --follow`	Follow mode — real-time streaming

# Follow an agent's live feed
genie log engineer -f

# Show last 20 events for the whole team
genie log --team auth-rewrite --last 20

# Stream tool calls as NDJSON
genie log engineer --type tool_call --ndjson -f

Brief

genie brief shows an aggregated startup brief with context since the last session — useful for agents resuming work or operators reviewing what happened overnight.

`genie brief`

genie brief [options]

Option	Description
`--team <name>`	Team name (default: `GENIE_TEAM` env var)
`--agent <name>`	Agent name (default: `GENIE_AGENT_NAME` env var)
`--since <iso>`	Start timestamp (default: last executor end)

# Show brief for the current agent
genie brief

# Show brief for a specific team since midnight
genie brief --team auth-rewrite --since 2026-03-30T00:00:00Z

Sessions

The genie sessions command group provides history and search across Claude Code sessions. Session metadata and content are stored in PostgreSQL.

`genie sessions list`

List Claude Code sessions.

genie sessions list [options]

Option	Description
`--active`	Show only active sessions
`--orphaned`	Show only orphaned sessions
`--agent <name>`	Filter by agent
`--limit <n>`	Max rows returned
`--json`	Output as JSON

`genie sessions replay`

Replay a session — interleaves content and events in chronological order.

genie sessions replay <session-id> [--json]

`genie sessions search`

Full-text search across session content.

genie sessions search <query> [--limit <n>] [--json]

`genie sessions sync`

Sync session data from JSONL files into PostgreSQL.

genie sessions sync

Metrics

The genie metrics command group provides machine-level state snapshots and agent heartbeat data.

`genie metrics now`

Current machine state — CPU, memory, active agents, teams.

genie metrics now [--json]

`genie metrics history`

Machine snapshot history over time.

genie metrics history [--since <duration>] [--json]

Default time window is 1h. Supports durations like 6h, 1d.

`genie metrics agents`

Per-agent heartbeat summary — shows each agent’s last heartbeat, state, and uptime.

genie metrics agents [--json]

Schedule

The genie schedule command group manages cron-based scheduled triggers.

`genie schedule create`

Create a new schedule.

genie schedule create <name> [options]

`genie schedule list`

List schedules with next due trigger.

genie schedule list [options]

`genie schedule cancel`

Cancel a schedule and skip pending triggers.

genie schedule cancel <name> [options]

`genie schedule retry`

Reset a failed trigger to pending.

genie schedule retry <name>

`genie schedule history`

Show past executions for a schedule.

genie schedule history <name> [options]

QA

The genie qa command group runs self-testing specs against the Genie CLI itself.

`genie qa run`

Run QA specs — all, a domain, or a single spec.

genie qa run [target] [options]

Option	Description
`--timeout <seconds>`	Max seconds per spec (default: `3600`)
`--parallel <n>`	Max specs to run in parallel (default: `5`)
`--verbose`	Show all collected events
`--ndjson`	Machine-readable NDJSON output

`genie qa status`

Show QA dashboard with last results per spec.

genie qa status [options]

`genie qa history`

Show recent QA runs.

genie qa history

`genie qa check`

Evaluate a QA spec against current team logs and publish a qa-report.

genie qa check <specFile> [options]

Option	Description
`--team <name>`	Team name (defaults to `GENIE_TEAM`)
`--since <timestamp>`	Only consider events after this ISO timestamp
`--since-file <path>`	Read the lower-bound timestamp from a file

genie qa check specs/messaging.yaml
genie qa check specs/messaging.yaml --team auth-rewrite --since 2026-03-30T00:00:00Z

`genie qa-report`

Publish a QA result to the PostgreSQL event log. Called internally by the QA team-lead.

genie qa-report <json>

Spawn & Lifecycle

Spawn the agents whose events land in the audit log.

Messaging

Send instructions to agents instead of scraping terminal output.

Scheduling

Configure cron triggers whose runs surface through schedule history.

Database

Inspect the PostgreSQL store that backs every event, session, and metric.

​Observability Commands

​Events

​genie events list

​genie events stream

​genie events stream-follow

​genie events subscribe

​genie events errors

​genie events costs

​genie events tools

​genie events timeline

​genie events timeline-v2

​genie events summary

​genie events scan

​genie events migrate

​genie events admin

​Enriched (v2) surface

​Log

​genie log

​Brief

​genie brief

​Sessions

​genie sessions list

​genie sessions replay

​genie sessions search

​genie sessions sync

​Metrics

​genie metrics now

​genie metrics history

​genie metrics agents

​Schedule

​genie schedule create

​genie schedule list

​genie schedule cancel

​genie schedule retry

​genie schedule history

​QA

​genie qa run

​genie qa status

​genie qa history

​genie qa check

​genie qa-report

​See also

Spawn & Lifecycle

Messaging

Scheduling

Database

Observability Commands

Events

`genie events list`

`genie events stream`

`genie events stream-follow`

`genie events subscribe`

`genie events errors`

`genie events costs`

`genie events tools`

`genie events timeline`

`genie events timeline-v2`

`genie events summary`

`genie events scan`

`genie events migrate`

`genie events admin`

Enriched (v2) surface

Log

`genie log`

Brief

`genie brief`

Sessions

`genie sessions list`

`genie sessions replay`

`genie sessions search`

`genie sessions sync`

Metrics

`genie metrics now`

`genie metrics history`

`genie metrics agents`

Schedule

`genie schedule create`

`genie schedule list`

`genie schedule cancel`

`genie schedule retry`

`genie schedule history`

QA

`genie qa run`

`genie qa status`

`genie qa history`

`genie qa check`

`genie qa-report`

See also