Developer docs

Propose a rule

Developers5 min read

When you notice something the whole team should do, propose it from the terminal. groundrule propose sends the rule to your workspace’s review inbox. Nothing changes in the rulebook until a reviewer accepts it. This page covers the command, its options, what reviewers receive, and the errors you may see.

npx @groundrule/cli propose "Never log full card numbers; mask all but the last four digits." \
  --why "PCI DSS" \
  --file src/http/refunds.ts:4

 ✓ Proposed to Acme Payments. Reviewers will see it in the inbox: https://app.groundrule.dev/acme-payments/inbox

Your coding agent can do the same through the MCP server’s propose_rule tool. See The MCP server.

Before you start

The repository is connected to a workspace (.groundrule/config.yaml has platform:), or you pass --org.
You’re signed in with npx @groundrule/cli login. A token from Settings → API tokens needs Propose rules checked.

Options

Argument or option	Required	What it does
`"<rule>"`	Yes	The rule, in one sentence. Quote it.
`--why <reason>`	No	Why the team should follow it, such as a standard, an incident, or a review comment.
`--example <code>`	No	A short example of the right or wrong way.
`--file <path[:line]>`	No	Where it came up, relative to the repository, such as `src/pay.ts:42`.
`--org <slug>`	No	The workspace. The default is `platform.org` from the config.
`--url <url>`	No	The Groundrule address.
`--json`	No	Print the result as JSON.

Write the rule the way you’d say it to a new teammate, and name the things involved: libraries, classes, folders. “Never call Stripe directly; use PaymentsGateway” is better than “Be careful with payments”.

Limits

Field	Limit
Rule	10 to 1,000 characters
`--why`	Up to 1,000 characters
`--example`	Up to 2,000 characters
`--file`	Up to 400 characters, relative to the repository
Proposals per person	30 per hour
Proposals per workspace	500 per day

What is sent

The proposal carries:

the rule;
your reason and example, if given;
the file and line, if given;
the repository’s name, from platform.repository or the origin git remote.

Nothing else from the repository is sent. Groundrule removes secrets from the rule, the reason, and the example before storing them.

Duplicates count as votes

If someone already proposed the same rule, or a scan already imported it, your proposal doesn’t create a second item. It’s added to the existing one, which records that it was seen again and cites you:

 ✓ Already proposed in Acme Payments; your vote is added. https://app.groundrule.dev/acme-payments/inbox

If a reviewer already rejected the same rule:

 ! A reviewer already rejected this rule in Acme Payments. Ask them to reopen it if things have changed.

When the catalog or your rulebook already has similar standards, the CLI lists them so you can check:

   Similar rules: SEC-006 (run groundrule explain <ID>)

What reviewers see

The proposal arrives in the Inbox as an instruction proposed by you, with a citation: who proposed it, from the CLI, and the repository, file, and line. People with an authoring role (Admin, Platform admin, Standard owner) can accept it, which turns it into a standard, mark it as covered by an existing standard, or reject it with a reason. If the category has an owner, it’s routed to them.

More: Proposals from developers and The review inbox.

JSON output

npx @groundrule/cli propose "Never log full card numbers; mask all but the last four digits." --json

Field	Meaning
`id`	The proposal’s ID.
`status`	`open`, `accepted`, or `rejected`.
`duplicate`	`true` when it was added to an existing proposal as a vote.
`similar`	Similar standards in the catalog or your rulebook: `id` and a `score` from 0 to 1.
`url`	The workspace’s inbox.
`org`	The workspace’s `slug` and `name`.

Errors

All errors exit with code 2.

Message	What to do
`Say the rule in a sentence.`	The rule is shorter than 10 characters.
`Use a path relative to the repository.`	`--file` starts with `/` or contains `..`.
`This repository isn't connected to Groundrule. Run groundrule init --org <your-org>, or pass --org.`	Connect the repository, or name the workspace.
`Not signed in to acme-payments on https://app.groundrule.dev. Run groundrule login first.`	Sign in.
`This sign-in can't propose rules yet. Run groundrule login again to refresh it.`	Your token lacks the permission. Log in again, or, in CI, use a token with Propose rules.
`Too many proposals. Wait a while and try again.`	You hit a limit above.