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 the active context document (current tasks, next steps, open questions).

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

5. `history`

View historical revisions of context documents.

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

6. `decision`

Log, list, search, update, delete, or consolidate architectural decisions (ADRs). To prevent knowledge duplication, decision log checks for similar existing decisions by default. If near-matches are found, it outputs them and skips insertion unless --force is passed.

# Log a new decision (fails if similar summary exists)
engrams decision log --summary "Use Postgres" --rationale "ACID required" --tags "db,sql"

# Log a new decision unconditionally
engrams decision log --summary "Use Postgres" --rationale "ACID required" --tags "db,sql" --force

# List decisions
engrams decision list [--tags "db,sql"] [--limit 20]

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

# Retrieve a decision by ID
engrams decision get <ID>

# Update a decision
engrams decision update <ID> [--summary "New summary"] [--rationale "New rationale"] [--details "details"] [--tags "new,tags"]

# Delete a decision
engrams decision delete <ID>

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

# Supersede a decision with another
# Supersede a decision with another
engrams decision supersede <ID> --by <REPLACEMENT_ID>

7. `progress`

Log and track tasks and subtasks. Use --check-similar to prevent logging duplicate entries for the same status and description.

# Log progress
engrams progress log --status "InProgress" --description "Database schema setup" [--parent-id <ID>] [--check-similar]

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

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

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

# 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.

# Link two entities
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"

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

11. `activity`

Get a summary digest of all modifications across the database.

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

12. `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

13. `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 -

14. `export`

Dump the SQLite tables to Markdown files for Git versioning.

engrams export [--path <DIR>]

15. `import`

Import/update the database using exported Markdown files.

engrams import [--path <DIR>]

16. `pr`

Manage PR URLs and numbers associated with decisions and patterns. Supports automatic host mapping for PR numbers if a git repository is configured.

# Attach PR URLs/numbers
engrams pr add --type decision --id <ID> --pr <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>

17. `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>

18. `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]

19. `prime`

Generate a briefing optimized for token budget. Progressively drops less critical sections to fit inside the budget.

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

20. `doctor`

Perform database audits for orphaned links, missing file anchors, and drift detection.

engrams doctor

21. `query`

Unified query search across decisions, patterns, and custom data, with FTS5 highlighting.

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

22. `instructions`

Print agent onboarding instructions in raw markdown.

engrams instructions

Automatic Update Checks

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. activity

12. report

13. batch

14. export

15. import

16. pr

17. anchor

18. relevant

19. prime

20. doctor

21. query

22. instructions