What each command does to your folder
In a new repository, npx @groundrule/cli with nothing after it does the first three of these for you: it shows what the checks find today, asks once, and sets the repository up (Start in one command). This page takes the commands one at a time. A first day with Groundrule is six commands. Each one is described the same way: what it looks at, what it writes, and what you should see. Install the CLI once with npm install --global @groundrule/cli; then groundrule and gr are the same command. The examples below use npx, which works without installing.
| Command | Looks at | Writes | Sends anywhere? |
|---|---|---|---|
init |
Your files, to detect the stack | .groundrule/config.yaml and a sample rule |
No |
sync |
The rulebook | AGENTS.md, CLAUDE.md, Cursor and Copilot rules |
No |
check |
Your changed lines | Nothing | Counts per rule, in a connected repository |
scan |
Every file, against every catalog rule | Nothing | Only with --upload |
hooks |
Which agents the repository uses | .claude/settings.json and the like |
No |
mcp |
The same .groundrule folder |
Nothing | No |
1. init: give the folder a rulebook
Section titled “1. init: give the folder a rulebook”npx @groundrule/cli initLooks at your files, detects the languages and frameworks, and writes one file, .groundrule/config.yaml. With no options it starts you from the essentials: a short set of rules that are all checked, of which the ones for your languages apply. With --org <slug> it points the repository at your workspace instead, and the workspace decides the packs. Nothing else is touched.
You should see ✓ Created .groundrule/config.yaml, the packs or workspace it chose, and the stack it detected.
2. sync: write the agent files
Section titled “2. sync: write the agent files”npx @groundrule/cli syncReads the rulebook and writes the rules into AGENTS.md and CLAUDE.md, between markers, keeping anything you already wrote there. If the repository has a .cursor folder or Copilot instructions, those too. From the next session, the coding agent reads the rules before it writes code.
You should see each file listed as created or updated, and a reminder to commit them. Run sync again whenever the rulebook changes; in CI, sync --check fails if someone forgot.
3. check: find what breaks a rule
Section titled “3. check: find what breaks a rule”npx @groundrule/cli check --allRuns every rule that has a check. With --all it looks at every file; without it, only at the lines you changed since the last commit, which is the everyday mode. Each finding names the rule, the file and line, the evidence, and how to fix it.
You should see a summary like Passed ✓ 23 passed ◇ 12 guidance, not checked 1 not applicable. “Guidance, not checked” counts the rules that are instructions for coding agents and have no check. A red ✕ is a blocker and fails the run; a yellow ⚠ is a warning and does not. explain <ID> prints why a rule exists, with examples.
4. scan: see what the code already follows
Section titled “4. scan: see what the code already follows”npx @groundrule/cli scan --uploadDifferent from check: it runs every rule in the whole catalog, not only your packs, and enforces nothing. It reports which rules already pass, which have findings, and what the repository already says in agent files, lint settings and CODEOWNERS. Without --upload, the report stays in your terminal. With it, the results and one-line snippets go to your workspace, never your source.
You should see the counts, the packs that fit the repository, and with --upload a link to the scan page. The evidence page explains what to do with it.
5. hooks: let the agent check its own work
Section titled “5. hooks: let the agent check its own work”npx @groundrule/cli hooksWrites a small settings file for each coding agent it finds in the repository, for example .claude/settings.json for Claude Code. The file tells the agent: when you finish a task, run the check on what you changed; and, for Claude Code, before you edit a file, ask for the rules that apply to it. Commit the file so every teammate’s agent does the same. hooks --remove takes it out.
You should see one line per agent, and then silence: the hook speaks only when a blocker is found. The agents page shows what that looks like.
6. mcp: let the agent ask questions
Section titled “6. mcp: let the agent ask questions”claude mcp add groundrule -- npx -y @groundrule/cli mcpRegisters Groundrule as an MCP server for Claude Code; Cursor and VS Code take the same command in their MCP settings. The agent can then ask which rules apply, which cover the files it is about to change, and run a check, without you typing anything. Connected to a workspace, it can also propose a rule to the inbox.
You should be able to ask the agent “which Groundrule standards apply here?” and get the list.
Commit what you made
Section titled “Commit what you made”git add .groundrule AGENTS.md CLAUDE.md .claude && git commit -m "Connect Groundrule"Everything above is files in the repository. Once committed, every clone has the same rules, the same hook and the same server.