Guides · Getting started · CLI · Coding agents

From nothing to agents that follow your rules, in minutes.

Two complete paths on one page. The CLI only: no account, nothing leaves your machine, from install to CI and your own rules. Or your team's workspace: one rulebook across repositories, the inbox, evidence and the dashboard. Every step shows the command, what you'll see, and how you know it worked.

30 minFor developers, tech leads and standard ownersChecked against the product on 19 November 2026All guides
§ 01what you need

Install once; then every command starts with groundrule.

Three things, then one install.

Then choose a path. Path A uses only the CLI: no account, nothing leaves your machine, and it is a complete setup, not a trial. Path B adds your team's workspace: one rulebook across repositories, an inbox, evidence and the dashboard. A repository on Path A joins Path B later with one command.

01.1

Node.js 22 or later

node -v to check. If it prints v20 or older, install a current release from nodejs.org or with your version manager.

01.2

A git repository

Any language. A few source files are enough to see findings.

01.3

For Path B only

A work email, or an invitation to a workspace. The Free workspace never expires.

No terminal at hand? Sign up at app.groundrule.dev, pick one repository on GitHub, and Groundrule scans it in a sealed sandbox and shows the findings in about two minutes. Nothing is added to the repository. The steps are in Start on GitHub.

Install the CLI once.

One command puts groundrule on your path. Prefer not to install anything? Put npx @groundrule/cli in front of each command instead; it downloads the CLI on first use and runs the same thing.

terminalonce per computer
$ npm install --global @groundrule/cli$ groundrule --version # without installing: npx @groundrule/cli --version

To pin one version for a whole team, add it to the project instead: npm install --save-dev --save-exact @groundrule/cli, then run it through your package manager. Updating later is npm install --global @groundrule/cli@latest.

§ 02path A

Only the CLI. No account, nothing leaves your machine. Complete in itself.

The CLI only: a rulebook in the repository.

One command shows what the rules find and sets the repository up, in two minutes. Four more steps make it yours and put the check where it cannot be skipped. Everything lives in .groundrule/ and the files it writes; commit them and the whole team has it.

  1. 01

    Run one command 2 min

    In the repository's folder. In a repository that is not set up yet, groundrule on its own takes a first look and writes nothing: the stack it found, how many rules apply, and what the checks find in the code today, worst first. Then it asks one question. Answer yes and it writes the configuration, the files your coding agents read, and the hooks that make the agent check its own work.

    terminalstep 01
    $ groundrule groundrule · a first look at checkout-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-004  Do not disable TLS verification   BLOCKER · deterministic (regex)   src/payments.ts:3     TLS certificate verification is disabled   → Remove the override and fix the certificate or trust store instead.  ⚠ SEC-005  Commit a dependency lockfile   warning · deterministic (files)  2 findings in 2 rules. This is code that already exists: it is listed, and it never blocks. Once set up, only what a change introduces is checked.  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] y  ✓ Set up. Commit these files so your whole team gets the same rules:   .groundrule/  AGENTS.md  CLAUDE.md  .claude/settings.json

    It starts from essentials, a short set of rules that are all checked. Every finding names the rule, shows the evidence and says how to fix it; groundrule explain SEC-004 prints why the rule exists, with Do and Don't examples. Findings in code that already exists are listed and never block: from now on, groundrule check looks only at what a change introduces.

    Prefer to go step by step? The same thing is groundrule init, groundrule sync, groundrule check --all and groundrule hooks, in that order. To skip the question, groundrule start --yes; add --no-hooks to leave the hooks out. More packs: groundrule packs lists them, and each goes under extends in .groundrule/config.yaml.

    Done when the terminal says "Set up". Commit now: git add .groundrule AGENTS.md CLAUDE.md .claude && git commit -m "Connect Groundrule".

  2. 02

    Decide the findings: fix, except, or override 10 min

    The first audit is the rulebook's first real test on your code. Each finding is a decision. Fix it; or excuse specific files for a reason and a time in .groundrule/exceptions.yaml; or change a pack rule for this repository with an override in .groundrule/config.yaml.

    .groundrule/exceptions.yamlstep 02 · an exception
    apiVersion: groundrule.dev/v1alpha1
    kind: ExceptionList
    spec:
      exceptions:
        - id: EX-1001
          standard: TS-001
          paths: ["scripts/**"]
          reason: Build scripts print to the console on purpose.
          expires: "2027-04-30"
    .groundrule/config.yamlstep 02 · an override
    overrides:
      SEC-005:
        severity: blocker
      TS-004:
        disabled: true
        reason: We use @ts-ignore in generated code only.

    Every exception needs a reason and an expiry; there are no permanent ones. Excepted findings stop failing but stay visible with check --verbose, and agents still get the rule.

    Done when groundrule check --all passes, and the exceptions it lists are the ones you meant.

  3. 03

    Write one rule that is yours 10 min

    The packs are generic; the value shows with a rule only your team has. The sample left in .groundrule/standards/ is the shape. Give it a check and it is enforced; leave checks out and it is guidance the agents read.

    terminalstep 03
    $ mv .groundrule/standards/EXAMPLE-001.yaml.sample .groundrule/standards/ACME-001.yaml
    .groundrule/standards/ACME-001.yamla rule with a check
    apiVersion: groundrule.dev/v1alpha1
    kind: Standard
    metadata:
      id: ACME-001
      title: Use the shared HTTP client
      type: forbidden-tech
      owner: team:platform
    spec:
      severity: warning
      intent: One HTTP client means one place for retries, timeouts, and tracing.
      requirement: Use our shared HTTP client for outbound calls. Do not add axios or got.
      remediation: Replace the dependency with the shared client.
      checks:
        - evaluator: dependencies
          forbid: [axios, got]

    Then groundrule sync && groundrule check --all: the rule lands in AGENTS.md and in the check, and groundrule explain ACME-001 prints it back. Every field and every check type is in the documentation.

    Done when your rule appears in AGENTS.md and the check counts it.

  4. 04

    Check every pull request in CI 5 min · no token needed

    Two steps in your pipeline, with npx so the runner needs no install. The first fails the build if the agent files drift from .groundrule/; the second checks only what the pull request changed, fails on blockers, and writes the findings into the job summary. An offline repository uploads nothing, so there is no secret to create.

    .github/workflows/ci.ymlstep 04
          - run: npx --yes @groundrule/cli sync --check
          - run: npx --yes @groundrule/cli check --base "origin/${{ github.base_ref }}" --summary "$GITHUB_STEP_SUMMARY"

    GitLab and other CI: the same two commands. Add -f sarif -o groundrule.sarif and upload the file to put findings in GitHub code scanning.

    Done when a pull request's checks include Groundrule.

  5. 05

    Give the agent the MCP server 2 min

    Offline it gives Claude Code, Cursor and any MCP client three tools: list_standards, rules_for (the rules that apply to the files the agent is about to change) and check. Commit a .mcp.json to share it with the repository.

    terminalstep 05
    $ claude mcp add groundrule -- npx -y @groundrule/cli mcp# Cursor and VS Code: the same command in their MCP settings

    Done when the agent answers "which Groundrule standards apply here?" from list_standards.

    That is Path A in full. Keep it current with npm install --global @groundrule/cli@latest, and groundrule doctor explains anything that looks off. What it does not give you: one rulebook across repositories, rollout stages on evidence, the inbox and imports, the dashboard's numbers, hosted and AI checks. Those are Path B, and a repository joins it later with groundrule init --org; everything above keeps working.

§ 03path B

One rulebook for every repository, an inbox, evidence, and the dashboard.

Your team's workspace.

Eleven steps. The first happens in the browser; most of the rest in a terminal inside the repository, with the same commands as Path A. A repository already on Path A starts at step 02.

  1. 01

    Create the workspace 3 min · in the browser

    Go to app.groundrule.dev and choose Create an account (if someone invited you, open the invitation link instead). Sign up with GitHub, or with an email you then confirm. One screen names the workspace (its URL name becomes app.groundrule.dev/<name>); the name is filled in from your email. The next screen offers to scan a repository on GitHub straight away: do it, or choose Skip for now and carry on here. The workspace starts with the security baseline; add packs under Rules → Packs.

    Done when Home shows "N standards in effect". Nothing can block anyone yet: each rule starts where its author recommends, and nothing is checked in a repository until it is connected.

  2. 02

    Sign the CLI in 1 min

    Anywhere in a terminal. It prints a one-time code and opens the approval page; check the code matches, pick the workspace, approve.

    terminalstep 02
    $ groundrule login groundrule login · https://app.groundrule.dev     Your one-time code:  MGKC-TMFX    Approve it at:       https://app.groundrule.dev/cli/activate?code=MGKC-TMFX    Waiting for approval…  ✓ Signed in to Acme Payments (acme-payments) as maya@acme.example

    Done when the terminal says "Signed in to …". The token is saved only for your user and lasts 90 days.

  3. 03

    Connect the repository and write the agent files 1 min

    In the repository's folder. Use your workspace's URL name. init links the repository to the workspace (on a Path A repository it replaces the local packs with the workspace's rulebook); sync writes the organization's rules into the agent files.

    terminalstep 03
    $ groundrule init --org acme-payments ✓ Created .groundrule/config.yaml   Platform acme-payments on https://app.groundrule.dev   Agents   AGENTS.md, CLAUDE.md, .cursor/rules/ $ groundrule sync groundrule sync · 79 standards → agents-md, claude-code, cursor   + .cursor/rules/groundrule.mdc created   ~ AGENTS.md updated   ~ CLAUDE.md updated ✓ Done. Commit these files so every agent gets the same rules.

    A warning that the repository "isn't registered" is fine: the organization's rules apply. An admin registers it under Teams → Repositories later to give it its team's settings.

    Done when AGENTS.md carries your organization's rules.

  4. 04

    Add the hooks and commit 1 min

    The same hooks as Path A: the agent checks its own work and hears the rules for a file before editing it. In a connected repository the hook also reports the counts per rule to the workspace after each check (never a path or code), which is what the dashboard shows as flagged in the agent loop. Commit everything so every developer's agent gets the same.

    terminalstep 04
    $ groundrule hooks$ git add .groundrule AGENTS.md CLAUDE.md .cursor .claude$ git commit -m "Connect Groundrule"

    Done when the commit is on your branch.

  5. 05

    Scan the repository and open the inbox 2 min

    The scan runs every catalog rule against the repository without enforcing anything, and finds what the repository already says: agent-file instructions, lint settings, CODEOWNERS, and the architecture the code already keeps. It uploads results and one-line snippets, never your source.

    terminalstep 05
    $ groundrule scan --upload groundrule scan · acme/checkout-api · 14 files · 0.1s  Rules       183 in the catalog · 90 apply here             ✓ 35 already pass   ! 6 with findings   ◇ 49 guidance only Imports     4 instructions from agent files · 3 tool settings · 2 CODEOWNERS entries Layering    2 boundaries and 1 package gates this code already keeps             src/domain must not import src/infra · 9 files depend the other way · clean today  ✓ Uploaded to Acme Payments: app.groundrule.dev/acme-payments/scans/…

    Open the link, then Inbox. Everything found waits there as proposals: accept, edit or reject each one. Accepting an instruction creates a standard; accepting a boundary creates an architecture rule with its check already written.

    Done when you have accepted your first proposal and it appears under Rules.

  6. 06

    Write one rule of your own 2 min · in the browser

    Under Rules, choose Describe a rule and say it the way you would tell a new teammate: "We never call Stripe directly; everything goes through src/payments/gateway.ts." AI drafts the full standard with examples and a check it has tested against them (this needs AI on, under Settings → AI). Review it and save. Or write one yourself with New rule.

    Done when the rule shows Checked · Deterministic on its page.

  7. 07

    Check every pull request in CI 3 min

    The same two steps as Path A, plus --upload and a token, so every result appears on the Pull requests page and, with the GitHub App installed, on the pull request as the Groundrule check. Create the token under Settings → API tokens (tick Upload scans and check results) and set it as the GROUNDRULE_TOKEN secret.

    .github/workflows/ci.ymlstep 07
          - run: npx --yes @groundrule/cli sync --check
          - run: npx --yes @groundrule/cli check --base "origin/${{ github.base_ref }}" --upload
            env:
              GROUNDRULE_TOKEN: ${{ secrets.GROUNDRULE_TOKEN }}

    Done when a pull request shows the Groundrule check.

  8. 08

    Invite the team 1 min · in the browser

    Settings → Members → Invite. Standard owners write and accept rules; developers read the rulebook and connect the CLI. Each developer then runs groundrule login once; the repository is already connected.

    Done when the people who own rules have an owner's role, and the setup card on Home reads 5 of 5.

  9. 09

    Give the agent the MCP server 2 min

    Connected, the server adds propose_rule: when a developer corrects the agent and says the rule should apply to everyone, the agent proposes it to the inbox. Or use the hosted server at mcp.groundrule.dev for cloud agents and web IDEs, with nothing installed.

    terminalstep 09
    $ claude mcp add groundrule -- npx -y @groundrule/cli mcp

    Done when the agent answers "which Groundrule standards apply here?" from list_standards.

  10. 10

    Scan nightly, promote on evidence, read the effect ongoing

    A nightly scan --upload in CI keeps evidence fresh: each rule's page shows what it finds across repositories, and the inbox suggests Ready to move forward when a rule has been clean long enough. Promote what has been clean to Enforce; keep the rest at Advise. The Dashboard then shows where violations are stopped: in the agent loop before a commit existed, on pull requests, and what is still on main. The Compliance page exports the period as CSV with SOC 2 and ISO 27001 mappings.

    Done when the first rule you promoted to Enforce fails a pull request that breaks it, and nothing else does.

  11. 11

    Optional: hosted checks and AI checks 5 min · in the browser

    Hosted checks, for repositories without a CI step: an admin turns on Check pull requests on GitHub under Settings → Connections, and Groundrule checks each pull request in a sealed sandbox, deleting the code when done. AI checks, for the rules no pattern can express: add an llm check with a question; it is answered only on hosted pull requests, advisory, within the AI budget, once an admin turns on AI checks under Settings → AI.

    Done when a hosted run appears on the Pull requests page.

§ 04if something looks off

The things that trip people up, and what each means.

If something looks off.

groundrule doctor explains most of these on its own.

You seeWhat it meansDo this
groundrule: command not foundThe CLI isn't installed, or your shell hasn't picked up the global install yet.npm install --global @groundrule/cli and open a new terminal, or run the command as npx @groundrule/cli ….
An old Node, or npx: command not foundNode.js 22 or later is needed.node -v; install from nodejs.org or with your version manager, then retry.
"This repository has no Groundrule configuration"You are outside the repository, or init has not run there.cd into the repository and run groundrule.
"acme/checkout-api isn't registered in acme-payments"Only a warning: the organization's rules apply.Keep going. An admin registers the repository under Teams → Repositories to apply its team's settings.
The check passes but you expected a findingOnly blockers fail by default; rules set to Tell agents (Path B) are taught, not checked; and check without --all looks only at changed lines.Run check --all; raise the rule's severity with an override (Path A) or set its dial to Warn or Block on its page (Path B).
The hook says nothing when the agent finishesThe check passed, or found only warnings. The hook speaks only when a blocker is found.Working as designed. To see it act once, ask the agent to add a key-shaped literal; it refuses, or is stopped with SEC-003.
§ 05 · sign-off

One sitting, then it runs itself.

On its own, the CLI gives a repository a rulebook, agents that read it, a check, and an agent that checks itself. The workspace adds one rulebook for every repository, an inbox, evidence, and the numbers that show what it stopped. Start with whichever fits today; the other is one command away.