Skip to content
docs
Open the dashboard
Developer docs

Install the CLI

Developers4 min read

The Groundrule CLI is the npm package @groundrule/cli. It installs one command, groundrule. You can run it with npx without installing anything, install it globally, or add it to a project as a devDependency with a pinned version. This page covers all three, plus the Node.js requirement, versions, and updates.

Requirements

Section titled “Requirements”
Requirement Details
Node.js Version 22 or later. The package declares "node": ">=22".
git Needed to check only your changes, to find the repository name, and to fetch packs from GitHub. Without git, check audits every file.
Operating system macOS, Linux, or Windows.
Network Only for login, logout, whoami, propose, scan --upload, and for repositories connected to the platform. Offline repositories need no network after the package is installed.

Check your Node.js version:

Terminal window
node --version

If it prints v20.x or older, install a current release from nodejs.org or with your version manager (for example nvm install 22).

Section titled “Option 1: run it with npx (recommended)”

npx downloads the package on first use, caches it, and runs it. Every page in these docs uses this form:

Terminal window
npx @groundrule/cli --version

You should see the version number, such as 0.1.0.

Use this form for one-off commands, for trying Groundrule out, and in CI. In CI, add --yes so npx never stops to ask before downloading:

Terminal window
npx --yes @groundrule/cli check

Option 2: install it globally

Section titled “Option 2: install it globally”

A global install puts groundrule on your PATH:

Terminal window
npm install --global @groundrule/cli
groundrule --version

From then on, npx @groundrule/cli <command> and groundrule <command> do the same thing.

Option 3: add it to a project (pin a version)

Section titled “Option 3: add it to a project (pin a version)”

Add the CLI as a devDependency when everyone on the team, and CI, should run the same version:

Terminal window
npm install --save-dev --save-exact @groundrule/cli@0.1.0

With pnpm or Yarn:

Terminal window
pnpm add --save-dev --save-exact @groundrule/cli@0.1.0
yarn add --dev --exact @groundrule/cli@0.1.0

Then run it through your package manager, which finds the local copy:

Terminal window
npx groundrule check

You can also add scripts to package.json:

{
  "scripts": {
    "standards:sync": "groundrule sync",
    "standards:check": "groundrule check"
  }
}

The bundled packs (groundrule:packs/...) ship inside the CLI. Pinning the CLI version also pins the packs your offline repositories use.

Check the version

Section titled “Check the version”
Terminal window
npx @groundrule/cli --version
npx @groundrule/cli -v

groundrule doctor also prints your Node.js version and fails if it’s older than 22. See Inspect your rules.

Update

Section titled “Update”
How you run it How to update
npx @groundrule/cli npx reuses its cached copy. Ask for the newest one with npx @groundrule/cli@latest <command>.
Global install npm install --global @groundrule/cli@latest
Project devDependency Change the version in package.json (or run npm install --save-dev --save-exact @groundrule/cli@<version>) and commit the lockfile.

When a repository is connected to the platform and the CLI is older than a rule it receives, the CLI skips that rule and warns: “Skipped <ID> from the platform: it doesn’t match this CLI’s spec (upgrade @groundrule/cli).” Update the CLI to get the rule back.

Notes by operating system

Section titled “Notes by operating system”

macOS and Linux

  • Sign-ins are saved in ~/.config/groundrule/credentials.json, or in $XDG_CONFIG_HOME/groundrule/ when XDG_CONFIG_HOME is set.
  • groundrule login opens your browser with open (macOS) or xdg-open (Linux). On a server without a browser, use --no-browser and open the printed link on any device. See Sign in from the CLI.

Windows

  • Sign-ins are saved in %APPDATA%\groundrule\credentials.json, unless XDG_CONFIG_HOME is set.
  • groundrule login opens your default browser.
  • Run the commands in PowerShell, Command Prompt, or Git Bash. Quote arguments with spaces in the way your shell expects, for example npx @groundrule/cli propose "Never call Stripe directly".

Global options

Section titled “Global options”

These work with every command:

Option What it does
-C, --cwd <dir> Run as if the command started in <dir>. Useful in scripts and monorepos.
-v, --version Print the version and exit.
-h, --help Show help. groundrule <command> --help shows one command’s options.

Colors turn off when the output isn’t a terminal, or when NO_COLOR is set.

If something goes wrong

Section titled “If something goes wrong”
  • npx can’t find the package, or you see a permissions error on a global install. Use npx instead of a global install, or fix npm’s global folder permissions as the npm documentation describes.
  • “Unsupported engine” or a syntax error on start. Your Node.js is older than 22. Upgrade it.
  • The command prints (run groundrule --help for usage). An option or argument was wrong. The command exits with code 2. Run npx @groundrule/cli <command> --help.

Next

Section titled “Next”