Sign in from the CLI

The CLI signs in to your Groundrule workspace through your browser. You never type a password into the terminal. This page covers login, whoami and logout, where the sign-in is saved, how to work with more than one workspace, and how CI signs in with a token instead.

You only need to sign in for repositories connected to the platform, and for propose and scan --upload. Offline repositories need no account. See Use Groundrule without the platform.

Sign in: login

npx @groundrule/cli login

login uses a device flow:

1. The CLI asks Groundrule for a one-time code, such as ZKRW-QJHD, and prints it with a link.
2. It opens your browser at https://app.groundrule.dev/cli/activate?code=ZKRW-QJHD.
3. You compare the code, choose a workspace, and approve.
4. The CLI, which checks every few seconds, receives a token and saves it.

 groundrule login · https://app.groundrule.dev

   Your one-time code:  ZKRW-QJHD
   Approve it at:       https://app.groundrule.dev/cli/activate?code=ZKRW-QJHD
   Opened your browser. Check the code matches, then approve.

   Waiting for approval…

 ✓ Signed in to Acme Payments (acme-payments) as maya@acme.example
   Saved to /Users/maya/.config/groundrule/credentials.json (only you can read it).

What login prints next depends on where you ran it:

• Outside a connected repository: it suggests groundrule init --org acme-payments, then groundrule sync.
• In a repository connected to the workspace you approved: it suggests groundrule sync.
• In a repository connected to another workspace: it warns “This repository uses <org>. Run login again and approve it for <org>.”

The approval page

If you aren’t signed in to the dashboard, sign in first. The page Approve this CLI? shows:

Row	What it shows
Code	The code to compare with your terminal.
Device	The computer that asked, such as “groundrule on MacBook-Pro-4.local”.
From	The network address the request came from.
Requested	How long ago the CLI asked.

Below it, Workspace lists every workspace you’re a member of. Pick one. Any role can approve the CLI.

The page warns: “Only approve if you just ran groundrule login yourself. For 90 days the CLI can then read this workspace’s rulebook, upload scan results, and propose rules to the inbox. It can’t change the rulebook or settings, and you can revoke it in API tokens.”

• Approve shows “You’re connected to <workspace>” and “Go back to your terminal. You can close this tab.”
• Deny shows “Request denied”. The terminal prints “The sign-in was declined in the browser. Nothing was saved.”

If the link has no code, the page Connect the CLI asks for it: type the code from your terminal in Code and choose Continue. If you have no workspace yet, the page says “You’re not in a workspace yet.” Create one, then run login again.

Caution

Approve only a code you just saw in your own terminal. If someone sends you a link to an approval page, choose Deny.

What the token can do

login creates an API token named “CLI login · groundrule on <hostname>”. It:

• acts as you, in the workspace you approved;
• can read the rulebook, upload scans, and propose rules;
• can’t change the rulebook, members, or settings;
• expires after 90 days.

Logging in again for the same workspace replaces the old token and revokes it. The token appears in Settings → API tokens with the label CLI login, and you can revoke it there at any time.

Options

Option	What it does
--no-browser	Print the link without opening a browser. Open it on any device where you can sign in.
--url <url>	Sign in to another Groundrule address. The default is https://app.groundrule.dev.

The CLI never opens a browser when its output isn’t a terminal, or when the CI environment variable is set. It prints the link instead.

When it goes wrong

Message	Meaning
The code expired. Run groundrule login again.	Codes last 10 minutes. Start over.
The sign-in was declined in the browser. Nothing was saved.	Someone chose Deny.
This code isn't valid. It may have expired; run groundrule login again.	Shown on the approval page for a wrong or used code.
Refusing to send credentials to http://…: use https (plain http is only allowed for localhost).	The address isn’t https. The command exits with code 2.
Couldn't reach Groundrule at … Check your connection or GROUNDRULE_URL.	Network problem, or a wrong address.

Check who you are: whoami

npx @groundrule/cli whoami

 ✓ Acme Payments (acme-payments) as maya@acme.example
   grt_…… · CLI login · groundrule on MacBook-Pro-4.local · expires 2027-01-07 · saved login · https://app.groundrule.dev

Each line names the workspace, your email, the start of the token, its name, its expiry (“never expires” when it has none), where it came from (saved login or GROUNDRULE_TOKEN), and the Groundrule address.

What whoami lists:

• Run outside a connected repository, with no --url and no GROUNDRULE_URL: every saved sign-in, on every address.
• Run inside a connected repository: the sign-ins for that repository’s address. It then adds either “This repository uses acme-payments.” or “! This repository uses acme-payments, which you’re not signed in to.”
• With GROUNDRULE_TOKEN set: only that token.

A token that was revoked or has expired shows as “<prefix>… is no longer valid (saved login). Run groundrule login.”

Option	What it does
--url <url>	Only sign-ins for this Groundrule address.
--json	Print { "url": …, "logins": [...] }. Each login has ok, url, source, and, when valid, org, user, and token (name, prefix, expiry, and permissions).

whoami exits with 0 when every sign-in it lists is valid, and 1 when none is saved (“Not signed in. Run groundrule login.”) or one is no longer valid.

Sign out: logout

npx @groundrule/cli logout

 ✓ Signed out of Acme Payments (acme-payments)

logout revokes the token on the server, so a copy of it stops working too, and deletes it from your computer. Without options, it signs you out of every workspace on the current Groundrule address.

Option	What it does
--org <slug>	Sign out of this workspace only.
--url <url>	Use this Groundrule address.

If the server can’t be reached, the CLI still forgets the token and says “couldn’t reach the server to revoke the token; revoke it in Settings → API tokens”. Do that. If there’s nothing to sign out of, it prints “Not signed in to any organization on <url>.”

Where your sign-in is saved

System	File
macOS, Linux	~/.config/groundrule/credentials.json
Any system with XDG_CONFIG_HOME set	$XDG_CONFIG_HOME/groundrule/credentials.json
Windows	%APPDATA%\groundrule\credentials.json

The file is written with mode 600 (only you can read and write it) in a folder with mode 700. It holds, for each Groundrule address and workspace, the token, the workspace’s name, your email, and when it was saved. Never commit it or copy it to another machine; run login there instead.

Tip

Changing or resetting your password doesn’t sign out the CLI. If you think a token is exposed, revoke it in Settings → API tokens, and revoke any token you don’t recognize.

Several workspaces

You can be signed in to several workspaces at once. Run login once per workspace and approve each one. The CLI picks the token like this:

1. GROUNDRULE_TOKEN, if it’s set, always wins.
2. In a connected repository, the sign-in for the workspace named in .groundrule/config.yaml.
3. Otherwise (for example scan --upload or propose outside a connected repository), the only saved sign-in for that address. With more than one, pass --org <slug>.

If a token belongs to another workspace than the repository’s, the CLI stops: “This token is for <org>, but this repository uses <org>. Run groundrule login and approve it for <org>.”

Which Groundrule address is used

The first of these that’s set wins:

1. the --url option;
2. the GROUNDRULE_URL environment variable (an empty value counts as unset);
3. platform.url in the repository’s .groundrule/config.yaml;
4. https://app.groundrule.dev.

The CLI sends tokens only over https. Plain http is allowed only for localhost, 127.0.0.1, and [::1].

In CI: GROUNDRULE_TOKEN

CI can’t approve a browser prompt. Create a token in Settings → API tokens → New token, store it as a secret, and expose it as GROUNDRULE_TOKEN:

GROUNDRULE_TOKEN=grt_… npx @groundrule/cli sync --check

When GROUNDRULE_TOKEN is set, the CLI uses it instead of any saved sign-in. If it’s invalid, you see “GROUNDRULE_TOKEN isn’t valid. It may have expired or been revoked; create a new one in Groundrule → Settings → API tokens.” The full setup, with the permissions each job needs, is in Run Groundrule in CI.

Related

• Connect a repository
• Environment and files