Skip to content
Open the dashboard
Developer docs

Start in one command

DevelopersEngineering leads3 min read

In a repository that has no Groundrule configuration, one command shows you what the rules find in your code today and then sets everything up. It needs no account and sends nothing anywhere. CLI 0.25.0 and later; from 0.26.0 it starts from the essentials set.

Terminal window
npx @groundrule/cli

groundrule start is the same thing by name.

First, a look at the repository. Nothing is written at this point.

groundrule · a first look at orders-api
Stack typescript
Rules 14 rules from essentials apply here
every one is checked on every change
What the checks find in this repository today
✕ SEC-015 Use parameterized queries, never string-built SQL
BLOCKER · deterministic (regex)
src/orders.ts:7
SQL built by interpolating into a template literal; pass values as bound parameters
7: const r = await db.query(`SELECT * FROM orders WHERE id = ${req.params.id}`);
→ Move every value out of the query text and pass it as a bound parameter: ...
→ groundrule explain SEC-015
5 findings in 4 rules. This is code that already exists: it is listed, and it never blocks.
Once set up, only what a change introduces is checked.
Line What it tells you
Stack The languages it detected, which decide the packs.
Rules How many rules apply to this repository. A new repository starts from the essentials, which are all checked. When a pack also brings rules that are instructions for your coding agents and are not checked, this line says how many of each.
What the checks find Every finding in the repository as it stands, each with the rule, the file and line, the evidence and the fix. There is no “passed” or “failed” here: it is a look, not a verdict.
The last two lines Existing code is listed and never blocks. After set-up, check looks only at what a change introduces.

Then one question:

Set this repository up? It writes:
.groundrule/config.yaml the rules this repository follows
AGENTS.md, CLAUDE.md the same rules, for your coding agents
.claude/settings.json hooks: the check runs when the agent finishes a task
Set it up now? [Y/n]

Press Enter or y to set up. Answer n and nothing is written; run the command again whenever you like.

You should then see “✓ Set up. Commit these files so your whole team gets the same rules”, followed by the paths. Commit them.

Option What it does
-y, --yes Set up without asking. For scripts and containers.
--no-hooks Leave the hooks out. The config and the agent files are still written.

When nobody is at the terminal, for example in CI or with input piped in, the command shows the first look, writes nothing, and prints “To set it up, run groundrule start –yes”.

It does what three commands do one at a time, with the same defaults:

Step The separate command
Detects the stack and writes .groundrule/config.yaml, starting from the essentials init
Writes the agent files for the agents the repository uses sync
Adds the hooks for Claude Code, and for Codex, Cursor and Copilot when the repository uses them hooks

Use the separate commands when you want to choose the packs or the agent formats yourself.

Terminal window
npx @groundrule/cli check # what you changed, before you push
npx @groundrule/cli check --all # the whole repository again
npx @groundrule/cli explain TS-002 # why a rule exists, and how to comply
npx @groundrule/cli scan # the rest of the catalog, and which rules already pass here

In a repository that already has a configuration, groundrule alone prints the list of commands, and groundrule start says “This repository is already set up”.

To check every pull request for the whole team, add the check to CI. To take the rules from a Groundrule workspace instead of local packs, follow the CLI quickstart; start sets up a local repository and does not connect one.