DocsReference
CLI reference
Every grapim command and option, generated from the CLI's own help text.
Install it once with npm install -g grapim and run grapim <command>. Install it globally rather than through npx: the agent hooks call grapim on every edit, and npx runs packages from a cache npm may clear. It needs Node 22.13 or newer; undo and the provenance commands also need git.
This page is generated from the help text of the Grapim version this site runs. For the version you have installed, run grapim help.
Get started
grapim init [--agents <list>] [--no-intents]- record every edit your coding agents make in this repo: sets up the agents found here (Claude Code, Codex, Cursor, Gemini CLI; --agents claude,codex,cursor,gemini or all to choose) and, in a git repo, the git hooks that keep AI provenance as git notes (--no-intents: notes without prompts)
grapim sync [--watch] [--hub <url>]- send this repo's runs to your team's hub for review (default https://app.grapim.com; machine token from $GRAPIM_HUB_TOKEN)
Agent runs: AI review, approval, undo
grapim runs- every agent run: intent, turns, files, +/- lines, still in the tree?
grapim review --ai [<base>..<head>] [--json] [--fail-on blocker|never]- AI review of a branch with the model your env credentials point at (ANTHROPIC_API_KEY, Bedrock, Vertex, Foundry); deepest on agent-written lines. Exit 1 on a blocker (unless --fail-on never)
grapim review <run> --approve|--reject|--pending [--note "..."]- approve or reject a run on this machine (without a flag, show its approval). The pull request check counts approvals in the hub only
grapim undo <run> [--turn N] [--yes]- remove one run's (or one turn's) changes, keep everyone else's. <run> is a run id, label or session id prefix. Without --yes it only prints the plan. Needs git (for git merge-file).
grapim branch <run>- put one run's changes on a new git branch (grapim/<label>) from HEAD, without touching your working tree, index or HEAD
grapim restore <file> <sha> [--yes]- put a file back to a version from its history (a sha prefix from /api/files/history or the desk). Without --yes it only prints the plan. Recorded as its own run, so it can be undone
grapim blame <file>- which run and turn wrote each line that differs from HEAD
grapim blame <file> --history- every line, committed or not: agent run, turn and prompt, or human
grapim provenance record [<commit>] | show [<commit>] | stats [<rev-range>] | push [<remote>]- AI provenance notes (refs/notes/grapim): write one for a commit, print one, AI share per agent and file, push the notes
grapim provenance pr <base>..<head> [--json]- the summary a pull request gets: its agent runs, their review and lines (git blame + notes)
- runs, review, undo, branch, restore, blame, provenance and status take --json
Coordinate agents
grapim status [--watch]- who is active, what they are doing, which files they hold
grapim log [-n 30]- recent claims, edits (+/- lines), blocks and undos
grapim claim <files..> [--intent "..."] [--ttl 30]grapim release [files..]- release files (all of yours if none given)
grapim intent "<text>"- say what you are working on
Servers and integrations
grapim mcp- run the MCP server (for agents without hooks: they call claim_files and release_files themselves)
grapim serve [--port 7420] [--host 127.0.0.1] [--open]- the review desk, JSON API, agent workspace (/fs) and MCP over HTTP (/mcp). A --host other than loopback needs $GRAPIM_TOKEN
grapim hub- run the team hub server (from a source checkout only; configured from env, see .env.example)
grapim folder <workspace-url> <dir> [--watch] [--once] [--force] [--token-env NAME]- keep a local folder and a workspace in sync both ways (token from $GRAPIM_WORKSPACE_TOKEN; edits on both sides merge or keep both)
grapim mount <workspace-url> [drive-letter | mount-point]- the workspace as a network drive (WebDAV): on Windows with a letter it runs net use, elsewhere it prints the steps (token from $GRAPIM_WORKSPACE_TOKEN, never the command line)
grapim hook [--from codex|cursor|gemini]- the agent hook entry point (reads JSON on stdin; grapim init sets it up)
Options
--agent <name>- act as this agent (default: $GRAPIM_AGENT, or human:<your user name>)
--version- print the version
GRAPIM_MODE=warn- warn after the edit instead of blocking it
GRAPIM_TTL_MINUTES- how long a claim lasts without edits (default 30)
No telemetry: grapim connects to a server only when you run sync, folder or mount.