CLI reference

The loreqo CLI is a terminal-native typed wrapper over the Loreqo 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 @loreqo/cli

Global flags

These flags apply to every loreqo 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 ~/.loreqo/config.yaml (created by loreqo setup, file mode 600):

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

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

Environment variables

Setup

loreqo setup <tool>

Connect this machine to a project and register the Loreqo 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.)

LOREQO_SETUP_TOKEN=<your-token> loreqo setup claude-code

loreqo init, loreqo mcp init

Interactive setup, for when you'd rather be prompted than paste a token. loreqo init walks you through your Supabase URL, API key, default project, and sync folder; loreqo 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 loreqo setup <tool> token flow above.

loreqo 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 LOREQO_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/loreqo.md) as a delimited, non-clobbering managed block. See Agent instructions for the full walkthrough.

loreqo init --write-instructions

Auto path: write the managed block into every detected host config, plus a deep LOREQO.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.

loreqo init --write-instructions

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

loreqo init --print-instructions
loreqo init --print-instructions --copy

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

loreqo setup --print
loreqo setup --print --copy

loreqo setup (refresh)

Run bare loreqo 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.

loreqo setup

Documents

loreqo doc list

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

loreqo doc list
loreqo doc list --json | jq '.data.documents[].path'

loreqo doc show <path>

Show a document by its filesystem-relative path.

loreqo doc show docs/architecture/providers.md

loreqo doc edit <path>

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

loreqo doc edit docs/architecture/providers.md

loreqo doc create <path>

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

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

Brain

loreqo brain query <q>

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

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

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

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

loreqo brain add

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

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

Decisions

loreqo decisions list

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

loreqo decisions list

loreqo log <decision>

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

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

Intents

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

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

loreqo intent --release <intentId>

Release (complete) a previously broadcast intent.

loreqo intent --release <intentId>

Conflicts

loreqo conflicts

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

loreqo conflicts

loreqo conflicts --check [files...]

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

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

Sessions

loreqo session

Show the latest saved session checkpoint.

loreqo session save

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

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

Status

loreqo status

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

loreqo status
loreqo status --json

Import

loreqo import obsidian-vault <path>

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

loreqo import markdown-folder <path>

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

loreqo import status <importId>

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

loreqo import cancel <importId>

Co-operatively cancel an in-flight import.

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

Git mirror

loreqo mirror status

Show the configured Git mirror status.

loreqo mirror configure

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

loreqo mirror push

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

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

Shell completion

loreqo completion <shell>

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

loreqo completion zsh >> ~/.zshrc

Next steps

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