Skip to content
docs
Open the dashboard
Developer docs

Scan a repository

Developers7 min read

groundrule scan measures a repository against every rule in the catalog without changing or enforcing anything. It shows which rules already pass, which would flag code, and which rules the repository already has in its agent files, tool settings, and CODEOWNERS. By default nothing leaves your computer. With --upload, the results go to your workspace. This page is the developer’s view; Scan repositories covers what the workspace does with a scan.

Terminal window
npx @groundrule/cli scan

What a scan runs

Section titled “What a scan runs”
  • Every catalog rule. All bundled packs, 171 standards today, whatever packs the repository or workspace adopted. Each rule runs as if it were at Observe: nothing fails.
  • Your workspace’s own rules, with --upload only. The rules your workspace wrote that have checks, drafts included, so their authors see what they would flag before publishing. A workspace rule replaces a catalog rule with the same ID.
  • Stack detection. Languages from file extensions, frameworks from manifests such as package.json.
  • Imports, unless you pass --no-import:
    • instructions in agent files (AGENTS.md, CLAUDE.md, Cursor rules, Copilot instructions), with their file and line. Sections called “Commands” are skipped, and so is the block sync wrote;
    • tool settings that match catalog rules, from ESLint, Biome, Ruff, golangci-lint, Checkstyle, PMD, and tsconfig;
    • CODEOWNERS entries, as owner suggestions.

A scan doesn’t need .groundrule/config.yaml. It works in any folder. If a config exists, the scan uses its tags, and its workspace for --upload.

Read the summary

Section titled “Read the summary”
 groundrule scan · acme/checkout-api · 14 files · 0.1s


 Stack       TypeScript, JavaScript, fastify
 Agent files AGENTS.md (495 lines, from sync), CLAUDE.md (10 lines, from sync)
 Tools       codeowners (2 rules), docker, eslint, github-actions, typescript (strict)


 Rules       171 in the catalog · 90 apply here
             ✓ 35 already pass   ! 6 with findings (6)   ◇ 49 guidance only


 Already passing · safe to adopt at Enforce today
   ✓ AGENT-010  agent-hygiene
   ✓ DOCKER-003 docker
   …
   … and 27 more


 Most findings · start these at Observe or Teach, or clean up first
   ! DOCKER-001 1 finding in 1 file, e.g. Dockerfile:1
   ! GHA-003    1 finding in 1 file, e.g. .github/workflows/ci.yml:8
   ! TS-001     1 finding in 1 file, e.g. src/http/refunds.ts:4
   …


 Packs       agent-hygiene, docker, github-actions, http-api, security-baseline, testing, typescript-node apply to this repository
 Imports     4 instructions from agent files · 3 tool settings that match catalog rules · 2 CODEOWNERS entries
             Already enforced by your tools: TS-001, TS-007


 Nothing left this computer. Run groundrule scan --upload to share it with your organization, or --json to see exactly what would be sent. Uploads include your agent files' instructions (redacted); --no-import leaves them out.
Line Meaning
Header Repository name, files scanned, and time taken.
Stack Languages and frameworks found.
Agent files Instruction files found, their length, and “from sync” when they contain a Groundrule block.
Tools Tools whose configuration was found, with facts such as “strict” or a rule count.
Rules How many rules ran and how many apply to this stack. Then: already pass (✓), have findings (!, with the number of findings), and guidance only, with no check (◇).
Your rules With --upload, when your workspace has rules with checks: how many, how many drafts, and whether they found anything here.
Already passing Up to eight rules with no findings. They’re safe to adopt at Enforce today.
Most findings Up to eight rules with the most findings, with an example location. Start these at Observe or Teach, or clean up first.
Packs Packs whose checks found files to look at in this repository.
Imports What was found to import. “Already enforced by your tools” lists catalog rules your linters already enforce.

Options

Section titled “Options”
Option What it does
--upload Send the report to your workspace.
--json Print the full report as JSON instead of the summary.
-o, --output <file> Also write the JSON report to a file.
--no-snippets Leave every code snippet out of the report.
--no-import Leave out instructions, tool settings, and owners found in the repository.
--repository <name> The repository’s name, such as acme/checkout-api.
--org <slug> The workspace to upload to.
--url <url> The Groundrule address.

The repository’s name comes from the first of: --repository, platform.repository in the config, the origin git remote, or the folder name. Use the same name as in Teams → Repositories, so the scan is linked to the right repository and team.

The workspace for --upload comes from --org, then platform.org in the config. Without either, the CLI uses your only saved sign-in for that address.

Upload the results

Section titled “Upload the results”
Terminal window
npx @groundrule/cli scan --upload

The summary ends with a link to the scan:

 ✓ Uploaded to Acme Payments: https://app.groundrule.dev/acme-payments/scans/38208a34-8dba-48dc-891f-07c8add82da9

In the workspace:

  • the rules’ Evidence shows how they do in this repository;
  • what the scan imported waits in the Inbox as proposals;
  • the scan counts toward promotions, which need at least 2 scans per repository.

Run scan --upload regularly, for example nightly in CI, so the evidence stays current. See Run Groundrule in CI.

Uploading needs a sign-in with permission to upload scans. groundrule login includes it. For CI, create a token with Upload scans checked.

Limit Value
Uploads per token 60 per hour
Uploads per workspace 1,000 per day
Report size 2 MB
Scans kept per repository The latest 20

What leaves your computer

Section titled “What leaves your computer”

Without --upload, nothing. The scan runs locally and prints a summary.

With --upload, the report contains:

  • the repository’s name, commit, branch, and file count;
  • the stack, the agent files’ names and sizes, and the tools found;
  • for each rule: its outcome, counts of findings and files, and up to three examples, each a file, a line, a short message, and a one-line snippet of at most 200 characters;
  • with imports: the instruction texts from agent files and their locations, the tool settings that matched, and CODEOWNERS patterns and owners.

It never contains whole files or your source code beyond those one-line snippets. Also:

  • Secrets are redacted from snippets and instructions before they’re sent: known key formats, credentials in URLs, and long random-looking strings become [redacted].
  • Security rules never send snippets, only the file, line, and message.
  • --no-snippets sends no code at all.
  • --no-import sends no instructions, tool settings, or owners. Earlier imports in the workspace stay as they are.

To see exactly what would be sent, run:

Terminal window
npx @groundrule/cli scan --json

More: What we store.

The JSON report

Section titled “The JSON report”

--json and --output produce a ScanReport document:

Field Contents
apiVersion, kind groundrule.dev/v1alpha1, ScanReport
metadata generatedAt, cliVersion, durationMs, and snippets (whether snippets were included)
repository name, commit, branch, files
stack languages, frameworks
agentFiles Each file’s path, kind, lines, bytes, whether it’s managed by sync, and its heading and bullet counts
tools Each tool’s id, path, and facts
rules Each rule’s id, version, pack, severity, outcome, findings, filesInScope, filesAffected, up to 3 examples, and a reason when it doesn’t apply
imports instructions, toolSettings, owners. Absent with --no-import
summary rules, clean, violations, guidance, notApplicable, notEvaluable, findings

With --json --upload, the JSON goes to standard output and the “Uploaded” line to standard error, so you can pipe the JSON.

Exit codes and errors

Section titled “Exit codes and errors”

A scan never fails because of findings. It exits with 0 when it ran (and uploaded, if asked), and 2 when it couldn’t.

Message What to do
Not signed in to acme-payments on https://app.groundrule.dev. Run groundrule login (or set GROUNDRULE_TOKEN in CI). Sign in, or pass --org when you have several sign-ins. The CLI checks this before scanning.
Upload failed: this token can't upload scans. Run groundrule login again, or create a token with "Upload scans" in Settings → API tokens. The token lacks the permission.
Upload failed: This token is for … but the upload is for … The token belongs to another workspace. Sign in to the right one.
Upload failed: Too many scans uploaded. Try again later. You hit a limit above.
! Scanning the catalog only: … The workspace’s own rules couldn’t be fetched. The scan continues with the catalog.
Section titled “Related”