CLI Reference

Complete reference for the standalone engrams command-line interface.

Global Usage

engrams [options] <command> [args]

Global Options

Commands

1. `init`

Initialize the database schema at the resolved database path (creates engrams/context.db if missing).

engrams init

2. `migrate`

Migrate the database schema to the latest version.

engrams migrate

3. `product-context`

Manage the product context document.

engrams product-context get
engrams product-context update --content '<JSON>'
engrams product-context update --patch '<JSON>'

4. `active-context`

Manage named active-context tracks (current tasks, next steps, open questions). Each track is identified by a name — maintain separate tracks per workstream, branch, or focus area. The default track always exists.

engrams active-context get [--name <TRACK>]
engrams active-context update --name <TRACK> --content '<JSON>'
engrams active-context update --name <TRACK> --patch '<JSON>'
engrams active-context list

5. `history`

View historical revisions of context documents. For active-context, scope to a track with --name or list version counts across every track with --all.

engrams history <product-context|active-context> [--version <N>] [--limit <LIMIT>] [--name <TRACK>] [--all]

6. `decision`

Log, list, search, update, delete, or consolidate architectural decisions (ADRs). decision log checks for similar existing decisions by default and skips insertion on near-matches unless --force is passed. Always declare --contract when introducing an interface abstraction. Status is validated against a closed vocabulary — active, superseded, rejected, revisited; --force bypasses validation on updates, and decision supersede automatically flips the retired decision to superseded.

# Log a new decision with contract (fails if a similar summary exists)
engrams decision log --summary "Use Postgres" --contract "fn connect() -> Result<Conn>" --rationale "ACID required" --tags "db,sql"

# Log with an explicit initial status (default: active)
engrams decision log --summary "Use Postgres" --rationale "ACID required" --tags "db,sql" --status active

# Log a new decision unconditionally (also bypasses the similarity check)
engrams decision log --summary "Use Postgres" --rationale "ACID required" --tags "db,sql" --force

# List decisions (supports convention-aware --filter)
engrams decision list [--tags "db,sql"] [--filter "postgres"] [--limit 20]

# Search decisions using FTS5 (optionally returning snippets)
engrams decision search "Postgres" [--limit 10] [--snippets]

# Query decision curation stats (access frequency & dead knowledge audit)
engrams decision stats [--most-accessed] [--never-accessed] [--limit 10]

# Retrieve a decision by ID (reinforces access count)
engrams decision get <ID>

# Update a decision (supports --contract update)
engrams decision update <ID> [--status "superseded"] [--summary "New summary"] [--contract "New contract"] [--rationale "New rationale"] [--details "details"] [--tags "new,tags"] [--force]

# Delete a decision
engrams decision delete <ID>

# Consolidate two decisions (merges fields, contracts, repoints links, and deletes source)
engrams decision consolidate <SOURCE_ID> <INTO_ID>

# Supersede a decision with another (auto-sets the retired decision's status to 'superseded')
engrams decision supersede <ID> --by <REPLACEMENT_ID>

7. `progress`

Log and track tasks and subtasks. Status is validated against a closed vocabulary — Todo, InProgress, InReview, Blocked, Done, Dropped; --force bypasses validation. Use --check-similar to prevent logging duplicate entries for the same status and description.

# Log progress (status must be in the closed vocabulary)
engrams progress log --status "InProgress" --description "Database schema setup" [--parent-id <ID>] [--check-similar] [--force]

# List progress
engrams progress list [--status "Done"] [--parent-id <ID>] [--limit 20]

# Retrieve a task by ID
engrams progress get <ID>

# Update a task (--force bypasses status validation)
engrams progress update <ID> [--status "Done"] [--description "New description"] [--parent-id <ID>] [--force]

# Delete a task
engrams progress delete <ID>

8. `pattern`

Log and track design patterns and codebase conventions.

# Log a pattern
engrams pattern log --name "API response format" --description "Always return JSON with status code" --tags "api,rules"

# List patterns
engrams pattern list [--tags "api"] [--limit 20]

# Get a pattern by ID
engrams pattern get <ID>

# Delete a pattern
engrams pattern delete <ID>

9. `custom`

Store arbitrary key-value pairs grouped by category.

# Set a value (string or JSON)
engrams custom set --category "config" --key "api_host" --value "localhost:8080"
engrams custom set --category "config" --key "features" --value '{"auth": true}' --json

# Get a value
engrams custom get --category "config" [--key "api_host"]

# Search custom values using FTS5 (optionally returning snippets)
engrams custom search "localhost" [--category "config"] [--limit 10] [--snippets]

# Delete a value
engrams custom delete --category "config" --key "api_host"

10. `link`

Create and list relationships (edges) in the workspace knowledge graph. Canonical relationships (e.g. supersedes, depends_on, refines, conflicts_with, implemented_in) are validated against their declared domain/range and algebraic rules; link add rejects violations unless --force is passed. See the Knowledge Graph page for the full relationship vocabulary.

# Link two entities (canonical rels are validated; --force overrides violations)
engrams link add \
  --source-type system_pattern --source-id 1   --target-type decision --target-id 7   --rel implements \
  --description "Verify JWT middleware implements decision 7" [--force]

# List links
engrams link list --item-type decision --item-id 7 [--rel implements] [--linked-type system_pattern]

11. `graph`

Compute and query the derived knowledge + code graph. Files are nodes; edges are derived automatically from file anchors, co-anchored/tag-overlapping entities, and git co-change history. Declared inverse relationships (e.g. superseded_by, depended_on_by) are materialized on rebuild.

# Recompute all derived edges (run after structural changes or migrations)
engrams graph rebuild

# Incrementally ingest git co-change edges (resumes from the last commit seen)
engrams graph ingest

# Node/edge counts, density, connected components, orphans, degree stats
engrams graph stats

# PageRank centrality ranking of nodes
engrams graph central

# List connected components as clusters
engrams graph clusters

# Nodes with degree <= 1
engrams graph orphans

# Shortest path between two nodes (type:id)
engrams graph path --from decision:7 --to system_pattern:2

# Nodes within N hops of a node (type:id)
engrams graph neighbors --node decision:7 --depth 2

# Transitive closure over a canonical transitive relation
# ('what transitively breaks if I revisit X?')
# rel: supersedes | depends_on | part_of | refines
engrams graph chain --node decision:7 --rel depends_on
engrams graph chain --item-type decision --item-id 7 --rel supersedes

12. `activity`

Get a summary digest of all modifications across the database.

engrams activity [--hours <N>] [--limit-per-type <LIMIT>]

13. `report`

Generate a structured project knowledge report of active context, progress, decisions, patterns, and links. Output is always JSON. Can be filtered by a specific topic. Or, open a browser-based HTML dashboard using the open subcommand.

# Generate full report in JSON format
engrams report

# Show only decisions in JSON format
engrams report decisions

# Generate and open the interactive HTML dashboard with knowledge graph
engrams report open

# Generate the dashboard HTML file at a custom path without opening a browser
engrams report open --no-browser --out /path/to/report.html

14. `batch`

Perform bulk operations in a single atomic transaction.

# From JSON string
engrams batch --type decision --items '[{"summary": "A"}, {"summary": "B"}]'

# From stdin
cat items.json | engrams batch --type custom_data --items -

15. `export`

Dump the SQLite tables to Markdown files for Git versioning.

engrams export [--path <DIR>]

16. `import`

Import/update the database using exported Markdown files.

engrams import [--path <DIR>]

17. `pr`

Manage PR URLs and numbers associated with decisions and patterns. Supports automatic host mapping for PR numbers if a git repository is configured, and reverse lookup via pr find.

# Attach PR URLs/numbers
engrams pr add --type decision --id <ID> --pr <PR_NUMBER_OR_URL>

# Reverse lookup: find all decisions/patterns referencing a PR
engrams pr find <PR_NUMBER_OR_URL>

# List PRs attached to an item
engrams pr list --type decision --id <ID>

# Remove a PR URL from an item
engrams pr remove --type decision --id <ID> --url <PR_URL>

18. `anchor`

Manage file path anchors for decisions and patterns.

# Add file anchors
engrams anchor add --type decision --id <ID> --path <FILE_PATH>

# List anchors
engrams anchor list --type decision --id <ID>

# Remove an anchor
engrams anchor remove --type decision --id <ID> --path <FILE_PATH>

19. `relevant`

Find decisions and patterns relevant to specified paths or staged git files.

# Query relevant items by path
engrams relevant <PATH>

# Query relevant items using staged files
engrams relevant --staged [--all]

20. `prime`

Generate a briefing optimized for token budget. Lists every active-context track and expands the one matching your current scope, includes a compact graph summary (the first section dropped under a budget), and demotes superseded decisions into a compact annotated section. Progressively drops less critical sections to fit inside the budget.

# Generate briefing
engrams prime [--budget <TOKENS>]

21. `doctor`

Run database health audits: missing file anchors, dangling links, stale-decision drift detection, unlinked decisions, orphan graph nodes, graph-rebuild recommendations, cycles in canonical transitive relations (supersedes/depends_on/part_of/refines), and non-canonical relationship vocabulary linting.

engrams doctor

22. `query`

Unified query search across decisions, patterns, and custom data, with FTS5 highlighting and cross-convention matching (snake_case, camelCase, and kebab-case match identically). Pass --full to embed complete payloads. When a search matches 0 items, returns structured miss_guidance.

# Unified query
engrams query <QUERY> [--types decision,pattern,custom] [--tags <TAGS>] [--since <TIMESTAMP>] [--limit <LIMIT>] [--all]

# Full-payload query (kills 1+N decision get calls)
engrams query "auth" --full

23. `instructions`

Print agent onboarding instructions in raw markdown.

engrams instructions

24. `brief`

One-call composite architectural brief for a node reference or FTS query in under 200 tokens: returns decision text, contract, tags, PRs, anchors with extracted symbols/docstrings/lines, Git staleness drift, and 1-hop neighbors.

# Brief by query or node reference
engrams brief "payment provider"
engrams brief decision:62 [--depth 2]

25. `usage`

Retrieval telemetry and curation feedback. Tracks call counts, constraints fired, and zero-hit searches.

# Show aggregate retrieval counts
engrams usage [--since <TIMESTAMP|2w>] [--daily]

# Rank zero-hit queries (vocabulary gaps to curate)
engrams usage --misses

26. `coverage`

Audit anchored-knowledge coverage, dead anchors, and median hop distance for a file set or git diff.

# Audit paths
engrams coverage src/

# Audit changed files on a branch
engrams coverage --diff main...HEAD

27. `session`

Record session ROI rollups (reads skipped vs required) and enforce PR validation gates.

# Close session with PR validation gate
engrams session close --reads-skipped 14 --reads-required 2 --tokens-saved 70000 --pr 42 [--note "..."]

# View session history and cumulative savings
engrams session history

Engrams CLI automatically checks for new releases in the background (at most once every 24 hours). If a new version is available, a notification is printed to standard error.

To disable these update checks (for example, in CI environments or offline setups), set any of the following environment variables to any value:

ENGRAMS_NO_UPDATE_CHECK
NO_UPDATE_CHECK
CI

Option	Default	Description
`--db <PATH>`	Auto-detected	Direct path to the SQLite `.db` file.
`--workspace <PATH>`	Closest workspace root	Directory to treat as the workspace root.
`--compact`	false	Output compact JSON on a single line with nulls stripped.
`--fields <FIELDS>`	-	Comma-separated list of fields to retain in output.
`-h, --help`	-	Print help and usage information.
`-V, --version`	-	Print the version number.

CLI Reference

Global Usage

Global Options

Commands

1. init

2. migrate

3. product-context

4. active-context

5. history

6. decision

7. progress

8. pattern

9. custom

10. link

11. graph

12. activity

13. report

14. batch

15. export

16. import

17. pr

18. anchor

19. relevant

20. prime

21. doctor

22. query

23. instructions

24. brief

25. usage

26. coverage

27. session