Install, log in once, and read some mail.

PKCE is always enabled. The browser flow binds a loopback listener on port 3434 and completes when Google redirects back; --device prints a URL and a code instead, for SSH sessions and containers.

Tokens are written to the operating system keyring — Windows Credential Manager, macOS Keychain, or the Linux Secret Service over D-Bus. On a headless machine with no keyring daemon, grr falls back to <cache dir>/grr/token.json and imports it back into the keyring later. Check which one you got from the token_backend field that grr auth login prints. GRR_TOKEN_STORE=file skips the keyring altogether — what a script, an agent, or CI wants, since an OS approval prompt is a hang rather than a question.

# 1. Log in once. Release binaries ship with an OAuth client compiled in.
$ grr auth login
{"authenticated":true,"token_backend":"os-keyring","token_preview":"ya29.a0AfH6SMBx..."}

# 2. Prove the credential works.
$ grr auth status
{"authenticated":true,"email":"you@example.com","messages_total":48213,...}

# 3. Do something real. gmail list returns the API's own wrapper object.
$ grr gmail users messages list --user-id me --max-results 5
{"messages":[{"id":"19f8ab2c","threadId":"19f8ab2c"}],"resultSizeEstimate":5}

Headless and CI

Two commands behave differently when there is no terminal, and both refuse to hang rather than block forever on a prompt.

• grr auth login --device prints the verification URL and a user code, then polls until you approve. It is the only login path that works over plain SSH.
• GRR_TOKEN_STORE=file keeps grr away from the OS keyring: the token goes to <cache dir>/grr/token.json, with no approval dialog that only a human at the keyboard can clear — the right default for a script, an agent, or CI.
• grr auth setup needs --client-id and --client-secret when stdin is not a TTY, and exits with an error instead of waiting for input. Add --print-only to get the recipe and the config path without writing anything.
• grr auth setup --force overwrites an existing ~/.grr/config.toml. Without it, an existing file is never replaced.
• --enable-apis shells out to gcloud services enable for the service APIs behind every command in the index (gmail, calendar-json, drive, people, chat, forms, tasks, docs, sheets, slides, script, analyticsadmin, analyticsdata, searchconsole) when gcloud is on PATH. It is best-effort: a failure warns and setup still succeeds.

# Headless machine: print a URL + code instead of opening a browser.
$ grr auth login --device
Visit https://google.com/device and enter code: ABCD-EFGH

# Bring your own OAuth client (source builds only; needs a TTY otherwise).
$ grr auth setup --print-only
{"instructions":"grr needs one Google OAuth client. ...","config_path":"...","wrote_config":false,...}

Client ids are shape-checked before anything is written: the value must end in .apps.googleusercontent.com and the secret must be at least ten characters. A truncated paste is caught immediately rather than becoming an opaque 400 from Google’s token endpoint later.

Where configuration comes from

Three sources, highest priority first:

• Environment variables: GRR_OAUTH__CLIENT_ID and GRR_OAUTH__CLIENT_SECRET (double underscore nests, single underscore becomes a dash).
• ~/.grr/config.toml, or whatever GRR_CONFIG_PATH points at.
• The OAuth client compiled into the binary at build time. This is the zero-config path, and it only applies when nothing else supplied a client id.

There is no transport, concurrency, or output setting to tune. Those are compile-time constants; the only runtime knob is the OAuth client.

Know which scopes you actually hold

A release build asks for a small default scope set at grr auth login — Gmail, Drive, Calendar, Tasks, Docs, Sheets, Slides, and the sign-in scopes — and widens it with grr auth login --service <name> when a task needs more (--all-scopes requests the whole index). The default is small on purpose: Google’s consent screen stops submitting past roughly 27 ticked boxes on an unverified project, so requesting everything makes a first-time login impossible. Consent is still not per-method, and every login merges with the account’s existing grant, so widening never drops access.

Before a write, grr api call … --dry-run prints the exact URL, body, and scopes the method declares without sending anything. Scope is reported for inspection, not consulted as a gate — the dry run is still the cheapest way to see what a call touches.

$ grr api call gmail.users.messages.list --param userId=me --dry-run
{
  "method": "GET",
  "url": "https://gmail.googleapis.com/gmail/v1/users/me/messages",
  "body": null,
  "scopesRequested": ["https://mail.google.com/", "..."],
  "leastPrivilegeScope": "https://www.googleapis.com/auth/gmail.readonly",
  "dryRun": true
}

The default grant covers Gmail, Calendar, Drive, Tasks, Docs, Sheets, Slides and sign-in; every other service — People, Chat, Forms, Apps Script, Search Console, Analytics Admin, Analytics Data, the admin surfaces — is one grr auth login --service <name> away, and a live call succeeds as soon as the API is enabled on your Cloud project. A 403 names the scope: widen the grant with that service command, or check the API is enabled. Discovery API has the full breakdown.

Where to go next

• Commands — the generated tree: naming rule, typed flags, and per-service examples
• Discovery API — the index behind the whole tree: 402 methods across 14 APIs
• Agents and harnesses — the output contract for driving grr programmatically
• Install page — archive sizes and channel details

And when you are ready to check a flag rather than trust a page: grr schema dumps the whole command tree as JSON, and grr <service> --help is authoritative.