Command-line interface

The covenant CLI communicates with a running daemon over the Unix socket at $COVENANT_HOME/sock. Each subcommand is a single round-trip; the CLI performs no caching and holds no state of its own.

Synopsis

covenant <subcommand> [args]

  bootstrap [--json]                 Grant the union of every loaded
                                     agent's required capabilities (plus
                                     memory.write); idempotent — already
                                     granted actions are skipped.
  intent [--json] [--stream] <text>  Submit an intent and print the result;
                                     --stream opts into v2 streaming response framing.
  intents resume (<intent-id>|latest)
        [--json]                     Re-dispatch a budget-rejected intent.
  ping [--json]                      Check the daemon is responsive.
  version                            Print daemon protocol metadata as JSON
                                     (pre-auth; no operator token required).

  memory recent [--tier T] [-n N]
        [--json] [--stream]          List recent memory records;
                                     --stream opts into v2 streaming response framing.
  memory search <query>
        [--tier T] [-n N]
        [--min-relevance F] [--json] Cosine-similarity search via embeddings;
                                     --min-relevance F drops records below cosine F.
  memory purge [--tier T]
        (--before-ms M
         | --older-than-ms D) [--json]
                                     Delete records older than the threshold.
  memory compact --reason TEXT [--apply]
        [--detach-stale-parents]
        [tier deletion flags] [--json] Apply bounded multi-tier compaction.
  memory plan-compaction --reason TEXT
        [--detach-stale-parents]
        [tier deletion flags] [--json] Preview the compaction plan without mutating.
  memory plan-receipt-backfill
        [-n N] [--json]                Read-only plan for legacy uncorrelated receipts.
  memory repair detach-parent <id>
        --reason TEXT
        [--expected-parent UUID] [--apply]
                                     Clear a stale parent reference.
  memory repair delete <id>
        --reason TEXT [--apply]      Delete a confirmed invalid record.
  memory repair backfill-provenance <id>
        --reason TEXT --provenance JSON [--apply]
                                     Write provenance evidence under metadata.

  capabilities recent [-n N] [--json]
                                     List recent capability tokens.
  capabilities grant <action>
        [--scope <json>]
        [--expires-at <ms>] [--json] Sign and persist a new capability.
  capabilities revoke <signature-b58>
        [--json]
                                     Tombstone a previously granted token.
  capabilities purge
        (--before-ms M
         | --older-than-ms D) [--json]
                                     Delete old revoked capability tokens.

  receipts recent [-n N]
        [--since-ms <epoch_ms>] [--json]
                                     List recent settlement receipts;
                                     --since-ms drops events older than epoch.
  chain status [--json]               Print configured chain settlement state.
  chain flush-receipts [-n N] [--json]
                                     Batch local receipts into a receipt root.
  chain receipt-batches [-n N] [--json]
                                     List local receipt batches.
  chain register-agent
        --program-id BASE58
        --agent-key BASE58
        --metadata-hash HEX64
        --capability-hash HEX64
        [--keypair PATH]
        [--cluster NAME]
        [--rpc-url URL]
        [--confirm-timeout-ms N]
        [--json]                     Sign and submit a settlement
                                     register_agent transaction with the
                                     operator keypair.
  chain stake
        --program-id BASE58
        --agent-key BASE58
        --owner-covnt BASE58
        --stake-vault BASE58
        --amount U64
        --lock-until U64
        [--keypair PATH]
        [--cluster NAME]
        [--rpc-url URL]
        [--confirm-timeout-ms N]
        [--json]                     Sign and submit a settlement
                                     stake transaction with the operator
                                     keypair.
  chain buy-credits
        --program-id BASE58
        --owner-covnt BASE58
        --treasury BASE58
        --amount-covnt U64
        [--keypair PATH]
        [--cluster NAME]
        [--rpc-url URL]
        [--confirm-timeout-ms N]
        [--json]                     Sign and submit a settlement
                                     buy_credits transaction with the
                                     operator keypair; --treasury MUST
                                     equal config.treasury (fetch via
                                     chain status if unknown).

  settlement backfill-receipts
        [--dry-run] [--json]         Repair legacy settlement-receipt
                                     rows (--scope-pubkey reserved,
                                     not yet supported).

  a2a status [-n N]
        [--min-lease-age-ms N]
        [--deadline-within-ms N]
        [--state queued|in_flight]
        [--json]                     Inspect queued tasks, in-flight leases,
                                     and pending results;
                                     --deadline-within-ms keeps only tasks with
                                     deadline_ms within N ms from now;
                                     --state narrows to one queue state.
  a2a requeue <task-id>
        --reason <text>
        --duplicate-risk <idempotent|operator-accepted>
        [--lease-id <uuid>]          Return an in-flight task to queued.
  a2a force-error <task-id>
        --reason <text>
        --message <text>
        [--lease-id <uuid>]          Resolve an in-flight task as failed.
  a2a retry-stale [--enable]
        [--min-lease-age-ms N]
        [--max-attempts N]
        [--max-requeues N]
        [--scan-limit N]
        [--json]                     Scan stale leases; mutate only with --enable.
  a2a compact [--json]              Drop fully resolved A2A event rows.

  verify [--window N] [--json]       Cross-check audit log vs other state.

  audit recent [-n N]
        [--since-ms <epoch_ms>]
        [--json] [--stream]          List recent audit events as JSONL
                                     or one JSON envelope;
                                     --since-ms drops events older than epoch
                                     before --limit is applied;
                                     --stream opts into v2 streaming response framing.
  audit verify [--json]              Verify the local audit hash-chain.
  audit purge
        (--before-ms M
         | --older-than-ms D) [--json]
                                     Delete audit events older than the threshold.

  ignore check [--json] <text>       Report whether text matches the
                                     .covenantignore rules.

  tools list [--json]                List registered tools.
  tools call <name> [--args <json>] [--json]
                                      Invoke a registered tool.

  peers purge
        (--before-ms M
         | --older-than-ms D) [--json]
                                     Delete old revoked peer tombstones.
  peers rotate [--json]              Rotate the operator peer token.
  peers list [--limit N] [--prefix B58]
        [--live-only | --revoked-only] [--json]
                                     List peer registry summaries;
                                     filter by live or revoked status.
  peers revoke <token-prefix>
        [--force] [--limit-matches N] [--json]
                                     Revoke a peer token by prefix;
                                     --force allows ambiguous prefixes up to N.

Conventions

--tier T accepts working, episodic, or longterm (also long-term, long_term).
-n N sets the result count. Defaults to 10.
Time values are Unix milliseconds. --before-ms is an absolute epoch; --older-than-ms is a relative offset (now minus duration).
Daemon errors print to stderr and exit non-zero.

Exit codes

Code	Meaning
`0`	Success.
`1`	The daemon returned an error response, or a downstream call (e.g. socket connect) failed.
`2`	Usage error: bad subcommand, missing argument, malformed flag value.

covenant verify is the one exception: a non-zero exit signals drift between state files even when the call itself succeeded.

Examples

Submit an intent

$ covenant intent "summarise recent work on agent memory"
echo (no agent matched): summarise recent work on agent memory

$ covenant intent --json "summarise recent work on agent memory"
{"kind":"intent_result","intent_id":"...","status":"ok","text":"...","sources":[],"settlement":null}

Resume a budget-rejected intent

$ covenant intents resume latest --json
{"kind":"intents_resume","ok":false,"mode":"latest","intent_id":"...","error":{"code":"daemon_error","message":"budget exhausted; try again later"}}

Resume a checkpointed intent successfully

$ covenant intents resume latest --json
{"kind":"intents_resume","ok":true,"mode":"latest","intent_id":"...","status":"ok","text":"...","sources":[],"settlement":null}

Inspect daemon protocol metadata

$ covenant version
{"protocol":"covenant.ipc","version":1,"min_supported":1,"max_supported":2}

Probe daemon health

$ covenant ping --json
{"kind":"daemon_ping","status":"ok"}

Inspect recent memory

$ covenant memory recent -n 3
[1714938191234] working: echo (no agent matched): summarise...
[1714938018993] working: echo (no agent matched): index the...
[1714937883112] working: echo (no agent matched): list any open...

$ covenant memory recent -n 3 --json
{"kind":"memory_read","mode":"recent","tier":null,"limit":3,"query":null,"min_relevance":null,"records":[...]}

Semantic search across all tiers

$ covenant memory search "agent memory" -n 5
# (records ordered by cosine similarity, descending)

$ covenant memory search "agent memory" -n 5 --json
{"kind":"memory_read","mode":"search","tier":null,"limit":5,"query":"agent memory","min_relevance":null,"records":[...]}

Purge old memory records

$ covenant memory purge --tier working --before-ms 1714938191234 --json
{"kind":"memory_purged","tier":"working","before_ms":1714938191234,"purged":0}

Compact memory

$ covenant memory compact --delete-working-before-ms 1714938191234 --reason "maintenance window" --json
{"kind":"memory_compacted","outcome":{"mode":"dry_run","would_change":true,"changed":false,"deleted":[],"stale_marked":[],"parents_detached":[]}}

Grant and revoke a capability

$ covenant capabilities grant tool.web_search
granted: user@local → tool.web_search
signature: 4qXP...8tF1

$ covenant capabilities revoke 4qXP...8tF1
revoked: 4qXP...8tF1

$ covenant capabilities revoke 4qXP...8tF1 --json
{"kind":"capability_revoked","signature_b58":"4qXP...8tF1","removed":true}

Grant a scoped capability

$ covenant capabilities grant memory.write --scope '{"version":1,"tiers":["working"],"apply":true}'
granted: user@local → memory.write
signature: 4qXP...8tF1

$ covenant capabilities grant memory.write --scope '{"version":1,"tiers":["working"],"apply":true}' --json
{"kind":"capability_granted","subject_display":"user@local","action":"memory.write","signature_b58":"...","scope":{"version":1,"tiers":["working"],"apply":true},"expires_at":null}

Inspect active capabilities as JSON

$ covenant capabilities recent --limit 5 --json
{"kind":"capability_list","limit":5,"capabilities":[...]}

Purge old capability tombstones

$ covenant capabilities purge --before-ms 1714938191234 --json
{"kind":"capabilities_purged","before_ms":1714938191234,"purged":0}

Verify state

$ covenant verify --window 100
verify (last 100 records):
  ✓ memory ↔ audit — 0 memory orphan(s), 0 audit orphan(s)
  ✓ memory parent references — 0 stale parent reference(s)
  ✓ capability ↔ audit — 0 capabilit(ies) without matching grant audit event
  ✓ memory ↔ receipts — 20 memory record(s) vs 20 receipt(s); count diff = 0; exact drift = 0; legacy fallback = 0
orphans total: 0

$ covenant verify --window 100 --json
{"kind":"verify_report","window":100,"checks":[],"drift":[],"orphans_total":0}

Verify the audit chain

$ covenant audit verify
{"events":42,"anchors":42,"valid":true,"root_hash_hex":"...","failures":[]}

$ covenant audit verify --json
{"kind":"audit_integrity","report":{"events":42,"anchors":42,"valid":true,"root_hash_hex":"...","failures":[]}}

Read the audit feed

$ covenant audit recent --limit 5 --json
{"kind":"audit_recent","limit":5,"since_ms":null,"events":[...]}

Purge old audit events

$ covenant audit purge --before-ms 1714938191234 --json
{"kind":"audit_purged","before_ms":1714938191234,"purged":0}

Check ignore rules

$ covenant ignore check --json "summarise ~/.ssh/id_rsa"
{"kind":"ignore_report","ignored":true,"matched_pattern":"id_rsa","rules_loaded":5}

Purge old peer tombstones

$ covenant peers purge --before-ms 1714938191234 --json
{"kind":"peers_purged","before_ms":1714938191234,"purged":0}

Rotate the operator peer token

$ covenant peers rotate --json
{"kind":"peer_token_rotated","token_b58":"..."}

Inspect the A2A queue

$ covenant a2a status --min-lease-age-ms 300000 --json
{"kind":"a2a_status","limit":10,"min_lease_age_ms":300000,"deadline_within_ms":null,"state_filter":null,"tasks":[],"results":[]}

Scan stale A2A leases

$ covenant a2a retry-stale --json
{"kind":"a2a_auto_retry","report":{"policy":{"enabled":false,...},"considered":0,"requeued":[],"skipped":[]}}

Compact resolved A2A events

$ covenant a2a compact --json
{"kind":"a2a_compacted","dropped":0}

Invoke a tool

$ covenant tools list --json
{"kind":"tool_list","tools":[...]}

$ covenant capabilities grant tool.call.echo
$ covenant tools call echo --args '{"text":"hello"}'
hello

$ covenant tools call echo --args '{"text":"hello"}' --json
{"kind":"tool_result","name":"echo","content":[{"type":"text","text":"hello"}],"is_error":false}

Repair legacy settlement receipts

$ covenant settlement backfill-receipts --dry-run --json
{"schema":"covenant.settlement.backfill.v1","row_count":12,"rollback_path":null,"dry_run":true}

Repair legacy memory-receipt correlations

$ covenant memory backfill-receipt-correlation --dry-run --json
{"schema":"covenant.memory.backfill.v1","row_count":7,"savepoint_name":"memory_backfill_sp_001","dry_run":true}

Environment

Variable	Purpose	Default
`COVENANT_HOME`	Root of all on-disk state: socket, identity, memory, receipts, audit, capabilities, peers, budget, a2a, agents, and the runtime/gvisor scratch directory.	`$HOME/.covenant`
`COVENANT_HTTP_PORT`	Port the daemon binds for the HTTP gateway. The CLI itself does not use HTTP.	`8421`

HTTP API: same surface over HTTP, suitable for browser-facing UIs.
Local IPC: the wire protocol underneath the CLI.
Audit integrity: what audit verify checks.
Capability tokens: what capabilities grant/revoke actually mints.