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.

# 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.
$ grr gmail users messages list --user-id me --max-results 5
[{"id":"19f8ab2c","threadId":"19f8ab2c","snippet":"Build notes ..."}, ...]

$ grr transport
negotiated_protocol: HTTP_3
http3_requested: true
http3_effective: true
fell_back: false
cpus: 10
io_uring: false
http3_always_compiled: true
runtime: tokio multi-thread (auto-sized to cores)

A negotiated_protocol of HTTP_3 means QUIC worked end to end. HTTP_2 with fell_back: true is normal behind a proxy or on a network that blocks UDP; nothing is broken, you are just on the fallback path.

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 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 ten service APIs (gmail, calendar-json, drive, people, chat, forms, tasks, docs, sheets, slides) 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 consents to sixteen scopes. That set does not cover everything in the Discovery index — and every method reports the narrowest scope it accepts, so you can check before you rely on one.

Before a write, grr api call … --dry-run prints the exact URL, body, and scopes the method declares without sending anything. It is the cheapest way to find out whether a method is inside your consent boundary before you rely on it.

$ 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
}

Tasks is the one service that needs a scope this build does not hold (…/auth/tasks), so its methods are visible in grr api list and describable, but will not authorize until the scope set is extended and you re-run grr auth login. 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: 308 methods across ten 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.