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, windsurf, gemini, codex — see MCP setup for what each target writes. (ChatGPT connects as a hosted remote connector, not a setup target — see MCP setup.)

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

engrym init, engrym mcp init

Interactive setup, for when you'd rather be prompted than paste a token. engrym init walks you through your Supabase URL, API key, default project, and sync folder; engrym mcp init runs interactive setup and registers the MCP server with Claude Code. Both prompt for real — secrets are entered with masked input and never echoed or logged — and require an interactive terminal (they refuse on piped/non-TTY stdin). For unattended or scripted onboarding, prefer the non-interactive engrym setup <tool> token flow above.

engrym login

Browser-based device login (RFC 8628 device-code grant). Not yet wired to the live API — the command implements the client-side polling flow, but the API device-code endpoints are not exposed in the current release, so use the ENGRYM_SETUP_TOKEN flow above to authenticate for now.

Agent instructions

Connecting the MCP server gives your agent the tools; the agent-instruction flags write the usage contract — the four practices — into your AI tools' config files (CLAUDE.md / AGENTS.md / GEMINI.md / .cursor/rules/engrym.md) as a delimited, non-clobbering managed block. See Agent instructions for the full walkthrough.

engrym init --write-instructions

Auto path: write the managed block into every detected host config, plus a deep ENGRYM.md reference at the repo root. Idempotent and non-clobbering — re-running refreshes the block in place and leaves your out-of-marker content untouched.

engrym init --write-instructions

engrym init --print-instructions [--copy]

Paste path: print the block (writes nothing) so you can place it yourself. Add --copy to also put it on your clipboard.

engrym init --print-instructions
engrym init --print-instructions --copy

engrym setup --print

Print the latest managed block for paste users — the same output as init --print-instructions, handy when a staleness nudge tells you to re-paste. Add --copy to also place it on the clipboard.

engrym setup --print
engrym setup --print --copy

engrym setup (refresh)

Run bare engrym setup (no tool argument) to refresh the managed block in place across every host config — re-rendering the contract to the latest version while preserving your own content outside the markers. Run it after upgrading the CLI.

engrym setup

Documents

engrym doc list

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

engrym doc list
engrym doc list --json | jq '.data.documents[].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.