CLI reference

commitmind is the single binary you install with the quickstart. All commands accept --help for a concise inline summary; this page is the prose version.

Exit codes follow the Unix convention: 0 on success, non-zero on failure. Specific non-zero codes are noted per-command where they matter.

commitmind login

Pair this machine with your CommitMind account via OAuth 2.0 device flow.

commitmind login [--client-name NAME] [--backend-url URL]

Flags

• --client-name — display name for this device. Defaults to user@host.
• --backend-url — override the API base URL. Useful for self-hosted or staging. Defaults to https://api.commitmind.dev.

Example

commitmind login --client-name "work-laptop"

Prints a short user code, opens the verification URL in your browser, and polls until you approve. The token is stored under ~/.commitmind/auth.json (mode 0600).

commitmind onboard

Run the unified onboarding wizard — install.sh execs this after placing the binary on disk so a fresh machine flows from curl … | bash to "ready to use" in one continuous Bubble Tea flow.

commitmind onboard

Steps the wizard walks you through

1. Welcome — platform / arch / binary-path summary + step preview with ✓ markers next to anything already done on this machine.
2. PATH — appends the binary's directory to your shell rc files (zsh / bash / fish) when missing. Idempotent + opt-in per shell. Skipped silently when the rc file already references the dir.
3. Background indexer — installs the user-level launchd plist (macOS) or systemd user unit (Linux). No sudo. Skipped silently when the unit is already on disk.
4. Menubar tray (macOS only) — generates the .app wrapper + LaunchAgent so the menubar icon appears immediately. Auto-skipped on every other platform.
5. Sign in — OAuth 2.0 device flow (same as commitmind login). Skipped silently when a PAT already lives in your token store.
6. Init wizard — chains into the same flow commitmind init runs (project picker, editors, coaching, backfill, summary, live execute, done banner).

Every step is idempotent and gated on actual need — re-running commitmind onboard after a partial flow detects done steps and skips through them.

Non-TTY behaviour

When stdin / stdout aren't TTYs (CI, automated pipelines, headless shells), commitmind onboard skips the Welcome / PATH / daemon / tray / login screens and chains directly into commitmind init's inline-prompt path. To complete setup in headless environments, the canonical path is still:

commitmind login          # device-code OAuth
commitmind init           # connect this repo

commitmind init

Connect the current git repo to a CommitMind project. By default renders a Bubble Tea wizard (Welcome → Project → Editors → Coaching → Backfill → Summary → live execute) when stdin AND stdout are TTYs. Auto-disables and falls back to inline prompts when --no-tui, CI=non-empty, NO_COLOR=non-empty, or --mcp-config-only is set.

commitmind init [--org SLUG] [--project ID_OR_SLUG]
                [--token-name NAME] [--no-hook] [--force]
                [--no-tui] [--no-mcp-config | --mcp-config-only=KEYS]
                [--no-skills] [--no-coaching-hooks]
                [--coaching-hooks=project|user|skip]
                [--no-claude-md] [--no-copilot-instructions]
                [--no-vscode-settings] [--no-gitignore]
                [--no-sync-attach] [--no-backfill]
                [--backend-url URL]

What it does

1. Picks an org and project (auto-detect by canonical git remote URL first; falls back to the picker when nothing matches or the user chooses "different").
2. Mints a project-scoped agent token and stores it under ~/.commitmind/projects/.
3. Installs .git/hooks/post-commit (memory capture) and .git/hooks/pre-commit (review gate, threshold=high).
4. Wires the commitmind MCP server into selected editors' configs — Claude Code, Claude Desktop, Cursor, VS Code (Copilot Chat).
5. Installs agent-coaching hooks (project- or user-scope), routing skills, .claude/settings.json deny block, .vscode/settings.json terminal-tab keys, CLAUDE.md routing block, and .github/copilot-instructions.md.
6. Manages .gitignore so per-developer MCP configs aren't committed.
7. Attaches the repo to the local sync daemon's projects.json.
8. Runs the auto-backfill (skip / incremental / full based on the API's view of the project) with a live progress bar.
9. Auto-commits init's tracked-intent outputs as chore(commitmind): init.
10. Waits up to 30s for the local symbol index to populate.

Flags

• --org — org slug to connect (skips the picker if set).
• --project — project id or github_repo to connect.
• --token-name — display name for the new agent token. Defaults to the machine hostname.
• --no-hook — skip installing the git hooks.
• --force — overwrite an existing post-commit / pre-commit hook instead of bailing.
• --no-tui — use plain inline prompts instead of the wizard. Auto-on when stdin/stdout aren't TTYs, when CI or NO_COLOR is set, or when --mcp-config-only is passed.
• --no-mcp-config — skip wiring editor MCP configs entirely.
• --mcp-config-only=KEYS — non-interactive surgical mode: wire only the named editors (e.g. claude-code,cursor) and skip every other init step. Used by editor extensions + worktree scripts.
• --no-skills — skip the agent routing skills.
• --no-coaching-hooks / --coaching-hooks=SCOPE — skip / pre-pick the coaching-hooks scope (project / user / skip).
• --no-claude-md / --no-copilot-instructions / --no-vscode-settings / --no-gitignore — skip individual DX-polish steps.
• --no-sync-attach — skip registering the repo with the local sync daemon.
• --no-backfill — skip the auto-backfill + symbol-sync wait.
• --backend-url — override the API base URL.

Example

commitmind init --org acme --project acme/monolith

commitmind status

Show the active backend, your user identity, and (if run inside a linked repo) the connected project.

commitmind status [--json] [--repo-dir PATH]

Flags

• --json — print as JSON instead of human-readable text. Useful for scripts.
• --repo-dir — path to the repo. Defaults to the current working directory.

Exit codes

• 0 — user is logged in and (if inside a repo) the repo is linked.
• 1 — either not logged in, or inside an unlinked repo.

commitmind flush

Drain the local buffer of commits/observations that failed to post (usually because the API was unreachable during capture).

commitmind flush [--all] [--repo-dir PATH] [--verbose]

Flags

• --all — drain every project's queue, not just the current repo's.
• --repo-dir — path to the repo. Defaults to the current working directory.
• --verbose — print progress for each buffered entry.

Exit codes

• 0 — buffer drained cleanly (or was already empty).
• Non-zero — at least one entry failed to post; remaining entries stay in the buffer for the next flush or capture to pick up.

commitmind backfill

Walk git history oldest-first and ingest each past commit — plus a short summary observation — into CommitMind. Useful on a freshly-linked repo so the timeline isn't empty.

commitmind backfill [--repo-dir PATH] [--limit N] [--since DATE]
                    [--quiet] [--verbose] [--no-buffer] [--dry-run]

Flags

• --repo-dir — path to the repo. Defaults to the current working directory.
• --limit — max commits to ingest. 0 means unlimited. Defaults to a safe cap.
• --since — only ingest commits after this date (YYYY-MM-DD or full RFC3339).
• --quiet — suppress per-commit progress; still prints the final summary.
• --verbose — print per-commit progress to stdout.
• --no-buffer — fail loud on network errors instead of buffering. Use in CI-style one-shot environments where a partial buffer is worse than a loud exit.
• --dry-run — count commits that would be ingested without any API calls.

Examples

# Import the last 30 days.
commitmind backfill --since 2026-03-24
 
# Fast preview: how many commits would this touch?
commitmind backfill --dry-run

commitmind explain

Resolve a file path or symbol name and emit a fixed-schema envelope of decisions, observations, and commit summaries pertinent to the target — the why behind a piece of code. Pairs with xref (the where-lookup): xref answers "where is this defined / called", explain answers "why does this exist / what context shaped it" — without keyword-guessing into search_memory.

commitmind explain <file|symbol> [--format=json|markdown]
                                 [--synthesize] [--quiet] [--repo-dir PATH]

Default response is fast (~100ms): full source content (decision rationales + observation bodies + commit messages) inline so the caller can read directly. The MCP tool and PreToolUse hook share this same path — agents read raw content directly, no LLM call.

Pass --synthesize to layer an LLM-produced Why paragraph plus categorized Constraints / Risks at the top. Takes 4–8s for a hot file (Sonnet/Haiku-tier model generation time); useful for human reading from a terminal, not from agents.

Flags

• <file|symbol> — positional. A file path (with / or recognized extension) or an exact Go/TS/Python/etc identifier.
• --format — markdown (default) or json. JSON round-trips the full envelope shape for tooling.
• --synthesize — opt in to the LLM synthesis pass. Off by default.
• --quiet — suppress output when no envelope carries curated context (every Confidence == "low" with zero decisions). Designed for the PreToolUse hook so it stays silent on files with no memory surface yet.
• --repo-dir — path to the repo. Defaults to cwd.

Examples

# Quick context check on a file (raw content, sub-second).
commitmind explain apps/cli/internal/commands/explain.go
 
# Symbol lookup — resolves to the indexed file(s) it lives in.
commitmind explain RegisterTaskAdvance
 
# Human-friendly synthesis for a longer reading session.
commitmind explain pkg/explain/queries.go --synthesize
 
# JSON for tooling.
commitmind explain pkg/explain/queries.go --format=json

Exit codes

• 0 — envelope printed (or quietly skipped under --quiet).
• 1 — hard error (no daemon, no token, target didn't resolve).

commitmind doctor

Run a battery of probes against this machine's CommitMind install — daemon health, tokenstore + auth handshake, MCP wiring per editor, and hook installation. Pure diagnosis by default; pass --fix to apply the safe-to-fix subset.

commitmind doctor [--check NAME] [--fix] [--yes] [--json]

Flags

• --check — run a single probe by name instead of the full battery.
• --fix — apply auto-fixes for fixable probes.
• --yes — skip the confirmation prompt when --fix is set.
• --json — emit JSON output for scripts and CI.

commitmind update

Pull the latest CommitMind release. Fetches the manifest from commitmind.dev/dl/latest, downloads the platform-matched binary archive, verifies its SHA-256, and atomically replaces the running binary in place. The daemon is reloaded (launchctl on macOS, systemctl --user on Linux) so the new binary takes effect immediately.

commitmind update [--check] [--manifest-url URL]

Flags

• --check — print the available version and exit; don't download.
• --manifest-url — override the manifest URL. Useful for dev / staging.

commitmind prime

Print this project's CommitMind context as markdown. When stdout is a terminal, renders a scannable human card (recent commits, observations, open tasks). When piped or run with --hook-envelope, renders an agent-shaped payload designed to load into an AI session via a SessionStart hook — no manual prime_session MCP call required.

commitmind prime [--post-compact] [--hook-envelope]
                 [--quiet] [--no-color] [--repo-dir PATH]

Flags

• --post-compact — emit a focused post-compaction reprime (active task + contract reminder) instead of the full session-start prime.
• --hook-envelope — wrap output in Claude Code's SessionStart hookSpecificOutput JSON envelope and emit a one-line systemMessage summary.
• --quiet — print nothing when the repo isn't a CommitMind project.
• --no-color — disable ANSI color in the human card.
• --repo-dir — path to the repo.

Exit codes

• 0 — printed (or quietly skipped because the repo isn't connected).
• 1 — hard error (network / token / git inspect).

commitmind explain

Resolve a file path or symbol name and emit a fixed-schema envelope of decisions, observations, and commit summaries pertinent to the target — the why behind a piece of code. Pairs with xref (the where-lookup): xref answers "where is this defined / called", explain answers "why does this exist / what context shaped it" — without keyword-guessing into search_memory.

commitmind explain <file|symbol> [--format=json|markdown]
                                 [--synthesize] [--quiet] [--repo-dir PATH]

Default response is fast (~100ms): full source content (decision rationales + observation bodies + commit messages) inline so the caller can read directly. The MCP tool and PreToolUse hook share this same path — agents read raw content directly, no LLM call.

Pass --synthesize to layer an LLM-produced Why paragraph plus categorized Constraints / Risks at the top. Takes 4–8s for a hot file (Sonnet/Haiku-tier model generation time); useful for human reading from a terminal, not from agents.

Flags

• <file|symbol> — positional. A file path (with / or recognized extension) or an exact Go/TS/Python/etc identifier.
• --format — markdown (default) or json. JSON round-trips the full envelope shape for tooling.
• --synthesize — opt in to the LLM synthesis pass. Off by default.
• --quiet — suppress output when no envelope carries curated context (every Confidence == "low" with zero decisions). Designed for the PreToolUse hook so it stays silent on files with no memory surface yet.
• --repo-dir — path to the repo. Defaults to cwd.

Examples

# Quick context check on a file (raw content, sub-second).
commitmind explain apps/cli/internal/commands/explain.go
 
# Symbol lookup — resolves to the indexed file(s) it lives in.
commitmind explain RegisterTaskAdvance
 
# Human-friendly synthesis for a longer reading session.
commitmind explain pkg/explain/queries.go --synthesize
 
# JSON for tooling.
commitmind explain pkg/explain/queries.go --format=json

Exit codes

• 0 — envelope printed (or quietly skipped under --quiet).
• 1 — hard error (no daemon, no token, target didn't resolve).

commitmind dashboard

Open the local project dashboard served by the running sync daemon. Requires commitmind sync daemon (or the launchd / systemd unit installed via commitmind sync install) to be running.

commitmind dashboard [--print-url]

Flags

• --print-url — print the dashboard URL instead of opening a browser.

commitmind review

Run a structured review pass over the repository and print findings — symbol-level diff for the change-scoped modes, project rule violations across all of them. Each finding is severity-tagged (info / low / medium / high / critical).

commitmind review [--scope working|staged|head|all]
                  [--threshold info|low|medium|high|critical]
                  [--format text|json|jsonl-stream]
                  [--limit N] [--path PATH ...]

Scopes

• working (default) — working tree vs HEAD; catches dirty + staged.
• staged — git index vs HEAD (pre-commit semantics).
• head — HEAD vs HEAD~1 (post-commit retrospective).
• all — every tracked source file vs the current rule set (full-codebase audit; structural diff suppressed, only rule violations surface). Slower than the diff scopes — pass --limit=0 for unbounded.

Pre-commit gate

--threshold <sev> exits non-zero (code 7) when at least one finding has severity ≥ <sev>. Pair with commitmind install-hook to block commits on regressions.

Flags

• --format — output renderer:
  • text (default) — markdown to stdout, buffered until the run finishes. Good for human review.
  • json — single JSON document, buffered. Good for CI / dashboard consumers parsing the final report.
  • jsonl-stream — newline-delimited JSON emitted as the run progresses. Good for live UIs (the commitmind-code TUI's /scan dialog) and any consumer that wants to render progress without waiting 30-60s for --scope=all to finish. See the event shape below.
• --limit — max files in the report (1-200; pass 0 for unbounded).
• --path — repeatable path filter (relative to cwd).

jsonl-stream event shape

One JSON object per line. Events arrive in this order:

| event | When | Key fields | |-------------|--------------------------------------------|---------------------------------------------------| | progress | Stages: start once, file per file, done once | stage, done, total, path, findings, truncated | | finding | Each deduped finding from the rule pass | severity_label, Path, Line, Message, RuleID | | summary | Once at the end | scope, base_sha, head_sha, files_reported, truncated, counts (per-severity totals) | | error | On orchestrator failure (mid-run) | message |

When an error event lands, no further events follow.

Examples

# Live progress for a project-wide audit
commitmind review --format=jsonl-stream --scope=all
 
# CI gate (text + threshold pair):
commitmind review --threshold=high
 
# Pipe the streaming events into jq for ad-hoc filtering:
commitmind review --format=jsonl-stream --scope=all \
  | jq -c 'select(.event=="finding" and .severity_label=="critical")'

Exit codes

• 0 — review ran; no findings met the --threshold (when set).
• 7 — review ran; at least one finding meets the threshold. The report still printed before the exit.
• non-zero (other) — orchestrator error (e.g. --scope invalid, external-tool failure when not soft-skippable). For --format=jsonl-stream, the error event lands on stdout AND the exit is 0 so a streaming consumer parses it normally; for text / json the error returns a non-zero exit per cobra's standard.

commitmind rules

Print the project rules applicable to a repo-relative file path as markdown — same payload the get_rules_for_this_file MCP tool returns. Designed to fire from a Claude Code PreToolUse hook so an editing agent reads the applicable rules block before every Read / Edit / Write.

commitmind rules <file> [--quiet] [--repo-dir PATH]

Flags

• <file> — positional, repo-relative path.
• --quiet — suppress the "no rules apply" line when the file matches no rules.
• --repo-dir — path to the repo.

Exit codes

• 0 — printed (or quietly skipped because the repo isn't connected).
• 1 — hard error (no file argument, malformed git inspect).

commitmind check

Loads each file from disk, resolves the applicable hard rules, and evaluates them locally — file content never leaves your machine. Output is JSON in the same shape as the server-side POST /api/v1/rules/check response, so dashboard / CI integrations parsing the wire format keep working unchanged.

commitmind check <file>... [--no-lock] [--require-lock]
                           [--lockfile PATH] [--quiet] [--repo-dir PATH]

Rule source resolution (in order):

1. .commitmind/rules.lock.json at the repo root if present — offline-capable, deterministic, no network round-trip. Same artifact commitmind sync rules produces; CI runs identically.
2. GET /api/v1/rules/applicable per file — automatic fallback when no lockfile exists (or when --no-lock is set).

Flags

• <file>... — positional, one or more repo-relative paths.
• --no-lock — force the API path even when a lockfile exists.
• --require-lock — fail if no lockfile is present (CI gate).
• --lockfile — override the lockfile location.
• --quiet — suppress the empty-violations envelope when nothing fires.
• --repo-dir — path to the repo.

Exit codes

• 0 — no violations, OR only warn/info severities fired.
• 1 — at least one error-severity violation fired.
• 2 — hard error (no file argument, file not found, lockfile integrity mismatch).

commitmind install-hook

Render a git pre- or post-commit hook that runs commitmind review. The pre-commit hook gates git commit on a commitmind review --scope=staged pass; when the gate fires, the commit is blocked and the report prints inline. Bypass with git commit --no-verify.

commitmind install-hook [--threshold info|low|medium|high|critical]
                        [--post-commit] [--force]

Flags

• --threshold — severity gate for the pre-commit hook. Default high so only review-blocking findings interrupt the workflow. Lower thresholds are noisier; raise as your codebase tolerates. Ignored with --post-commit.
• --post-commit — render a post-commit hook instead. Runs commitmind review --scope=all AFTER each commit lands — informational only (git ignores its exit code), so it never blocks.
• --force — overwrite an existing hook.

commitmind sync

Manage the per-machine sync daemon. The daemon keeps each project's local SQLite cache fresh from the API so rule eval, symbol lookups, and other read paths run on-laptop in under 50ms.

commitmind sync <subcommand>

Subcommands

• daemon — run the daemon foreground (used by launchd / systemd / supervisors).
• start — background-start the daemon (writes pidfile, returns).
• stop — send SIGTERM to the running daemon.
• status — report whether the daemon is running.
• attach — add the current repo to the daemon's project list.
• detach — remove the current repo from the daemon's project list.
• logs — tail the daemon's log file.
• rules — generate or refresh .commitmind/rules.lock.json.
• resync — force a fresh GET /api/v1/rules into the daemon's cache.
• now — force-refresh every local cache (rules + playbooks + tasks + activity) plus the rules lockfile.
• install — render a launchd plist (macOS) or systemd user unit (Linux).
• uninstall — remove the launchd plist / systemd unit. Pass --purge to also wipe caches + tokens.

Pass --help to any subcommand for its specific flags.

commitmind mcp

Run the CommitMind MCP server that Claude Code, Cursor, and other editors spawn per session. The server reads the agent token minted by commitmind init and streams JSON-RPC over stdio. You shouldn't normally run this by hand — the Claude Code plugin wires it (or commitmind init --mcp-config-only=<editor> for Cursor / VS Code).

commitmind mcp <subcommand>

Subcommands

• serve — start the tasks/memory surface (mcp__commitmind__* tools).
• serve-code — start the code-intel surface (mcp__commitmind-code__* tools — xref, check_rules, get_rules_for_this_file, etc).

commitmind sweep

Compare the project's indexed files (every distinct path in project_symbol_index) against this repo's HEAD via git ls-files, then DELETE the index rows for any file no longer in HEAD. Companion to commitmind backfill --force — --force re-queues commits for the staleness worker; sweep cleans up symbol-index rows that no commit will ever re-touch.

commitmind sweep [--dry-run] [--yes] [--verbose] [--repo-dir PATH]

Flags

• --dry-run — print the ghost-file list without DELETing.
• --yes — skip the confirmation prompt before DELETing.
• --verbose — print every ghost path even when there are many.
• --repo-dir — path to the repo.

Exit codes

• 0 — index in sync OR sweep applied successfully.
• 1 — error (network, auth, mismatched repo, etc.).
• 2 — user declined confirmation.

commitmind tray (macOS only)

Launch the menu-bar tray — a read-only status surface for the local sync daemon. Polls the daemon's pidfile for at-a-glance state and tails the recent-events log for activity.

commitmind tray              # launch foreground
commitmind tray install      # install LaunchAgent (.app + plist)
commitmind tray uninstall    # remove LaunchAgent

Auto-started by the LaunchAgent installed via commitmind tray install. Run foreground for debugging or to test the menu without the LaunchAgent. Quit from the menu's "Quit Tray" item — the daemon keeps running.

commitmind uninstall

Wipe every CommitMind artifact on this machine. Iterates every repo recorded in ~/.config/commitmind/projects.json and removes project-scope artifacts (hooks, MCP entries, .gitignore block, agent skills) in each. Each per-repo wipe auto-commits ONLY the tracked files it touched, with message "chore: remove CommitMind integration" (explicit paths only). The commit is NOT pushed.

After per-repo cleanup, machine-scope artifacts are wiped: the sync daemon stops, launchd/systemd units unload, the menubar tray is removed, caches and ~/.config/commitmind (projects.json, every agent token, the user PAT) are removed, and finally the commitmind binary itself.

commitmind uninstall [--scope all|project|user] [--dry-run]
                     [--keep-binary] [--keep-daemon] [--keep-git-hook]
                     [--keep-mcp-config] [--keep-tokens]

Flags

• --scope — all (default), project (current repo only), or user (just user-scope hooks/MCP, no daemon, no per-repo work).
• --dry-run — print the plan, change nothing.
• --keep-binary — don't rm the commitmind binary itself. Useful when a distro package manager (Homebrew, etc.) owns the binary. Only meaningful with --scope=all.
• --keep-daemon — don't stop the sync daemon, unload its launchd / systemd unit, or remove the tray, cache dir, or ~/.config/commitmind.
• --keep-git-hook — don't touch .git/hooks/{post,pre}-commit.
• --keep-mcp-config — don't touch editor MCP config files.
• --keep-tokens — don't delete credentials in ~/.config/commitmind.

commitmind capture (hook-invoked)

Hidden from --help; documented here for operators. Reads the most recent commit via git show and posts it to the CommitMind API. commitmind init wires this into your .git/hooks/post-commit; you shouldn't normally run it by hand.

commitmind capture [--repo-dir PATH] [--quiet] [--verbose] [--no-buffer]

Flags

• --repo-dir — path to the repo. Defaults to the current working directory.
• --quiet — suppress all output (the default when running as a git hook).
• --verbose — print debug output to stdout.
• --no-buffer — fail loud on network errors instead of buffering to disk.