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>

The one setup command. Run it in your repo folder, the folder where your .git lives. It connects this machine to a project, registers the Engrym MCP server with your agent, and writes the files your agent needs into the folder it runs in. This is the supported way to authenticate the CLI. <tool> is your agent: claude-code, cursor, codex, gemini, windsurf, plus claude-desktop, which has no project folder and gets the MCP registration only. (ChatGPT connects as a hosted remote connector, not a setup target; see MCP setup.)

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

What it writes. First the registration: the token goes once into ~/.engrym/config.yaml, and the server is registered in your agent's own MCP config (see MCP setup for each one). Then, in the current folder:

The engrym-extract file is the command you run in your agent to extract your documents on its own model: /engrym-extract, or $engrym-extract in Codex. It is written so that only you start it. Nothing is written outside the folder, and the command sends Engrym nothing about the files it finds there.

Ask first. A file that is missing, empty, or already Engrym's is written without a question. Any other file is one with writing in it that Engrym did not put there, and the command asks once, listing them all:

These files already have content that Engrym did not write:

  CLAUDE.md  add the Engrym block; your own text stays as it is

Change them? [y/N]

Yes writes them all. No writes none of them and prints the block and the paths, so you can place it yourself. --yes answers yes ahead of time. With no terminal to ask in, the command writes only the files it can write freely, prints one Skipped <file> line for each of the others naming --yes, and exits 0.

Run it again at any time: a second run changes nothing that is already current. Run it in each project you use with Engrym.

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, with secrets entered as masked input and never echoed or logged, and both require an interactive terminal (they refuse on piped/non-TTY stdin). For unattended or scripted onboarding, prefer the 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 instructions block tells it how to use them. engrym setup <tool> writes that block for the agent you name. The commands below write or print it on their own, 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. It is 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 agent argument) in your repo folder to refresh the blocks Engrym wrote there, with engrym setup <tool> or init --write-instructions, to the latest version while preserving your own content outside the markers. A block you pasted yourself is left as it is. 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.