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]

  intent [--json] <text>             Submit an intent and print the result.
  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.

  memory recent [--tier T] [-n N]
        [--json]                     List recent memory records.
  memory search <query>
        [--tier T] [-n N] [--json]   Cosine-similarity search via embeddings.
  memory purge [--tier T]
        (--before-ms M
         | --older-than-ms D) [--json]
                                     Delete records older than the threshold.

  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] [--json]    List recent settlement receipts.
  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.

  a2a status [-n N] [--min-lease-age-ms N] [--json]
                                     Inspect queued tasks, in-flight leases,
                                     and pending results.
  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] [--json]       List recent audit events as JSONL
                                     or one JSON envelope.
  audit verify                       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 [-n N] [--prefix B58] [--json]
                                     List peer registry summaries.
  peers revoke <token-prefix> [--json]
                                     Revoke a peer token by prefix.

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":"intent_resume","resumed_intent_id":"...","status":"error","result":null,"message":"budget exhausted: ..."}

Inspect daemon protocol metadata

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

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,"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","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,"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,"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}

Environment

Variable	Purpose	Default
`COVENANT_HOME`	Root of all on-disk state — socket, identity, memory, receipts, audit, capabilities, agents.	`$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.