Command-line interface

The covenant CLI talks to a running daemon over the Unix socket at $COVENANT_HOME/sock. Every subcommand is a single round-trip; the CLI does no caching and holds no state of its own.

Synopsis

covenant <subcommand> [args]

  intent <text>                      Submit an intent and print the result.
  ping                               Check the daemon is responsive.

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

  capabilities recent [-n N]         List recent capability tokens.
  capabilities grant <action>        Sign and persist a new capability.
  capabilities revoke <signature-b58>
                                     Tombstone a previously granted token.

  receipts recent [-n N]             List recent settlement receipts.

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

  ignore check <text>                Report whether text matches the
                                     .covenantignore rules.

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

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"
phase 0 echo (no agent matched): summarise recent work on agent memory

Inspect recent memory

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

Semantic search across all tiers

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

Grant and revoke a capability

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

$ covenant capabilities revoke 4qXP...8tF1
revoked 4qXP...8tF1 (removed=true)

Verify state

$ covenant verify --window 100
window: 100
checks:
  memory ↔ audit       PASS  0 memory orphan(s), 0 audit orphan(s)
  capability ↔ audit   PASS  0 capabilit(ies) without matching grant audit event
  memory ↔ receipts    PASS  20 memory record(s) vs 20 receipt(s); diff = 0
orphans_total: 0

Invoke a tool

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

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.
Capability tokens — what capabilities grant/revoke actually mints.