CLI Reference

The CLI is a convenience tool for common workflows. The primary interface is still the TypeScript API, but the CLI is useful for bootstrapping a store, adding facts quickly, inspecting current state, and wiring lightweight operational scripts.

Usage

edicts [--path FILE] [--format yaml|json] <command> [options]

Global flags

`--path FILE`

Path to the edicts file. Defaults to ./edicts.yaml.

edicts --path ./config/edicts.yaml list

`--format yaml|json`

Select the on-disk store format. If omitted, the store infers format from the file extension.

edicts --path ./edicts.json --format json list

`edicts add`

Add a new edict.

edicts add --text TEXT --category CAT [options]

Flags:

--text TEXT — required
--category CAT — required
--tags TAG1,TAG2 — comma-separated tags
--confidence verified|inferred|user
--ttl ephemeral|event|durable|permanent
--key KEY — stable supersession key
--source SRC — provenance string
--expiresAt DATE — explicit ISO timestamp
--expiresIn DURATION — relative duration such as 30m, 2h, 7d, or numeric seconds

Example:

edicts add \
  --path ./edicts.yaml \
  --text "Public launch date is April 15, NOT earlier." \
  --category product \
  --confidence verified \
  --ttl event \
  --key launch_date \
  --source roadmap_review \
  --expiresAt 2026-04-16T00:00:00.000Z \
  --tags launch,public

Example output:

{
  "action": "created",
  "id": "launch_date",
  "edict": {
    "id": "launch_date",
    "text": "Public launch date is April 15, NOT earlier.",
    "category": "product",
    "tags": ["launch", "public"],
    "confidence": "verified",
    "source": "roadmap_review",
    "key": "launch_date",
    "ttl": "event",
    "expiresAt": "2026-04-16T00:00:00.000Z",
    "created": "2026-03-21T18:00:00.000Z",
    "updated": "2026-03-21T18:00:00.000Z"
  },
  "pruned": 0
}

`edicts list`

List active edicts.

edicts list

Default output is plain text:

- Public launch date is April 15, NOT earlier. ([verified], product, launch, public)
- Do not name unannounced partners publicly. ([verified], compliance)

Use --json for programmatic output:

edicts list --json

Example JSON output:

[
  {
    "id": "launch_date",
    "text": "Public launch date is April 15, NOT earlier.",
    "category": "product",
    "tags": ["launch", "public"],
    "confidence": "verified",
    "source": "roadmap_review",
    "key": "launch_date",
    "ttl": "event",
    "expiresAt": "2026-04-16T00:00:00.000Z",
    "created": "2026-03-21T18:00:00.000Z",
    "updated": "2026-03-21T18:00:00.000Z"
  }
]

`edicts stats`

Print store statistics as JSON.

edicts stats

Example output:

{
  "total": 6,
  "history": 2,
  "tokenCount": 148,
  "tokenBudget": 4000,
  "tokenBudgetRemaining": 3852,
  "byCategory": {
    "product": 3,
    "compliance": 2,
    "operations": 1
  },
  "byConfidence": {
    "verified": 5,
    "inferred": 1,
    "user": 0
  },
  "byTtl": {
    "durable": 3,
    "permanent": 2,
    "event": 1,
    "ephemeral": 0
  },
  "byTag": {
    "launch": 1,
    "public": 2,
    "migration": 1
  }
}

Other commands currently available

The CLI also currently ships these commands:

get <id>
remove <id>
update <id>
search <query>
review [--stale-days N] [--include-permanent] [--json]
compact <id>... --text TEXT [--tags TAGS] [--confidence CONF] [--ttl TTL] [--source SRC] [--dry-run]
export [--format json|yaml] [--output FILE]
import <file> [--merge|--replace]
init [--path FILE]

Compacting duplicate edicts

When the same fact has been recorded in multiple edicts, compact merges them into a single replacement — preserving history and keeping your store lean.

# Preview what would be merged (no writes)
edicts compact 12 15 --text "API rate limit is 1000 req/min per tenant" --dry-run

# Merge edicts 12 and 15 into one
edicts compact 12 15 --text "API rate limit is 1000 req/min per tenant" \
  --category limits \
  --confidence verified

Rules:

All source edicts must belong to the same category
At least 2 source IDs are required
Source edicts are removed after the merged edict is created
--dry-run shows the operation plan without modifying the store

Not yet fully covered in this CLI guide

We are intentionally keeping this page focused on the most common day-one commands.

For deeper workflows such as:

targeted get
mutation via update
deletion via remove
text lookup with search
hygiene checks with review
compaction with compact
migration flows with export / import

refer to the API Reference, which documents the underlying behaviors in more detail.