CLI reference

The engrym CLI is a terminal-native typed wrapper over the Engrym REST API. It composes with jq, grep, and the rest of your UNIX toolbox: every command supports --json for machine-parseable output and --quiet for IDs-only scripting mode.

npm install -g @engrym/cli

Global flags

These flags apply to every engrym command:

--json and --quiet are mutually exclusive — passing both exits with code 2.

Exit codes

Every non-zero exit prints a one-line message to stderr.

Configuration

The CLI reads ~/.engrym/config.yaml (created by engrym setup, file mode 600):

defaultProject: a1b2c3d4-e5f6-4a7b-8c9d-ef1234567890
projects:
  - id: a1b2c3d4-e5f6-4a7b-8c9d-ef1234567890
    apiKey: engrym_live_...
    apiUrl: https://api.engrym.com

The active project resolves in precedence order: the --project flag, then the ENGRYM_PROJECT environment variable, then defaultProject from the config.

Environment variables

Setup

engrym setup <tool>

Connect this machine to a project and register the Engrym MCP server with an AI tool, in one non-interactive command. This is the supported way to authenticate the CLI. Tools: claude-code, claude-desktop, cursor, gemini, codex — see MCP setup for what each target writes.

ENGRYM_SETUP_TOKEN=<your-token> engrym setup claude-code

engrym init, engrym login, engrym mcp init

These interactive commands appear in engrym --help but are not functional in the current release — they exit with a not wired in this build error. Use the setup-token flow above; interactive setup and browser-based device login are planned.

Documents

engrym doc list

List documents in the active project. Flags: --limit <n>, --cursor <c> (pagination).

engrym doc list
engrym doc list --json | jq '.items[].path'

engrym doc show <path>

Show a document by its filesystem-relative path.

engrym doc show docs/architecture/providers.md

engrym doc edit <path>

Open a document in $EDITOR; saves back on exit.

engrym doc edit docs/architecture/providers.md

engrym doc create <path>

Create a new document. Content via --content <text> or - for stdin.

engrym doc create docs/new.md --content "# Title"
echo "# Title" | engrym doc create docs/new.md -

Brain

engrym brain query <q>

Full-text search across atoms. Flags: --limit <n>, --cursor <c>.

engrym brain query "provider strategy"
engrym brain query "rate limits" --limit 5 --json

engrym brain context

Read the Brain context bundle — the composed view of atoms relevant to the project (what an agent sees via get_team_context). Flags: --scope <pattern>, --limit <n>, --cursor <c>.

engrym brain context
engrym brain context --scope "packages/api/**"

engrym brain add

Add a new atom. --title <t> is required; content via --content <c> or - for stdin. Optional: --kind <k>, --scope <s>.

engrym brain add --title "Error envelope convention" --content "All API errors use the envelope shape."

Decisions

engrym decisions list

List decisions in the active project. Flags: --limit <n>, --cursor <c>.

engrym decisions list

engrym log <decision>

Log a decision. Pass the decision text as a positional argument or - for stdin. Optional: --rationale <r>, --scope <s>.

engrym log "Switch to Postgres for the primary store" --rationale "Relational fits the model"

Intents

engrym intent <description>

Broadcast an intent — announce what you're about to work on so teammates' agents can avoid conflicts. Optional: --files <paths...> (the files you'll touch, used for conflict detection), --scope <s>.

engrym intent "Refactoring the auth module" --files packages/auth/src/index.ts

engrym intent --release <intentId>

Release (complete) a previously broadcast intent.

engrym intent --release <intentId>

Conflicts

engrym conflicts

List active conflicts. Flags: --status <s> (default active), --limit <n>, --cursor <c>.

engrym conflicts

engrym conflicts --check [files...]

Pre-commit check mode: report active intents touching the given files. Designed for Git hooks.

engrym conflicts --check src/auth.ts src/session.ts

Sessions

engrym session

Show the latest saved session checkpoint.

engrym session save

Save a session checkpoint. Summary via --summary <text> or - for stdin. Optional: --scope <s>.

engrym session save --summary "Finished the billing webhook; tests green"

Status

engrym status

Show the active project status — intents, decisions, and conflicts in one view (three parallel API calls).

engrym status
engrym status --json

Import

engrym import obsidian-vault <path>

Import an Obsidian vault from a local folder path. Prints the import id.

engrym import markdown-folder <path>

Import a generic folder of .md files from a local path. Prints the import id.

engrym import status <importId>

Report the status of an in-flight or finished import job.

engrym import cancel <importId>

Co-operatively cancel an in-flight import.

engrym import obsidian-vault ~/vaults/my-project
engrym import status <importId>

Git mirror

engrym mirror status

Show the configured Git mirror status.

engrym mirror configure

Configure the Git mirror remote. Flags: --remote-url <url> (required), --branch <b> (default main), --ssh-key <path>.

engrym mirror push

Trigger the mirror worker to push pending changes. Flag: --force (force-push even if the remote diverged).

engrym mirror configure --remote-url git@github.com:acme/knowledge-mirror.git
engrym mirror push

Shell completion

engrym completion <shell>

Print a completion script for bash, zsh, or fish to stdout; append it to your shell rc to enable.

engrym completion zsh >> ~/.zshrc

Next steps

• Getting started — five-minute on-ramp.
• MCP setup — wire Engrym into your AI tool.
• API reference — REST endpoint reference.