The index behind the whole tree.

grr api list prints an array of { id, http, summary }. The count goes to stderr and the array to stdout, so grr api list | jq stays valid JSON. --service narrows to one service, --filter is a case-insensitive substring match over both method ids and descriptions, and --grouped nests the methods under their service with a per-service count.

$ grr api list
402 methods                                  # to stderr
[{"id":"calendar.acl.delete","http":"DELETE","summary":"Deletes an access control rule."}, ...]

$ grr api list --service sheets
$ grr api list --filter list --grouped
$ grr api list --service gmail --filter "batch"

grr api describe takes one method id and returns everything needed to call it: the HTTP verb, the raw path template, the full scope list, the narrowest scope, and every parameter with its type, required flag, repetition, and enum values. The hint field is a ready-made invocation using the method’s first parameter.

$ grr api describe gmail.users.messages.list
{
  "id": "gmail.users.messages.list",
  "service": "gmail",
  "apiVersion": "v1",
  "discoveryRevision": "20260928",
  "httpMethod": "GET",
  "path": "gmail/v1/users/{userId}/messages",
  "urlTemplate": "https://gmail.googleapis.com/gmail/v1/users/{userId}/messages",
  "description": "Lists the messages in the user's mailbox.",
  "scopes": ["https://mail.google.com/", "..."],
  "leastPrivilegeScope": "https://www.googleapis.com/auth/gmail.readonly",
  "parameters": [
    {"name":"userId","type":"string","required":true,"repeated":false,...},
    {"name":"q","type":"string","required":false,"repeated":false,...},
    {"name":"maxResults","type":"integer","required":false,...}
  ],
  "hint": "grr api call gmail.users.messages.list --params '{\"userId\": "..."}'"
}

grr api refresh [--service X] fetches fresh Discovery documents into the local cache between releases, for the rare method you need before the next daily PR lands. The embedded index keeps working offline regardless.

A missing required parameter is caught before anything is sent, and the error names the parameter and lists the rest, rather than letting Google answer with a 404 or a confusing 400.

• --params JSON takes a whole object. Must be a JSON object; an array or a bare value is rejected with a message saying so.
• --param KEY=VALUE is repeatable and wins over --params, so you can override one field of a large blob. Values are coerced to real JSON types: --param pageSize=10 is a number, not the string "10".
• Only the first = splits, so --param 'q=name=a.pdf' and Gmail search strings survive intact.
• --body-file PATH reads the body verbatim from a file, or from stdin with -, and wins over anything --params would have synthesised. This is the path for nested bodies.
• --query KEY=VALUE appends raw query pairs for parameters Discovery does not describe, such as alt=json or fields.
• --method-override VERB replaces the verb from the Discovery document, for the rare endpoint where the published method is behind the live API.

For POST, PATCH, and PUT without --body-file, the non-path parameters are collected into a JSON body automatically — and they are also appended as query pairs, which the dry-run output above shows honestly. For read verbs no body is sent at all. Path values are percent-encoded, so Drive ids and Gmail labels containing spaces or slashes are safe.

# Path parameters are substituted into the URL; the rest become
# query parameters (GET) or the request body (POST/PATCH/PUT).
$ grr api call gmail.users.messages.list --param userId=me --param 'q=is:unread' --param maxResults=5
$ grr api call drive.files.list --params '{"pageSize": 10, "q": "name contains \'report\'"}'

# Values are coerced to real JSON types, so numbers and booleans need no quoting.
$ grr api call sheets.spreadsheets.values.get \
    --param spreadsheetId=1a2b3c --param range=A1:D10

# A body from a file ("-" reads stdin), sent verbatim.
$ grr api call chat.spaces.messages.create \
    --param parent=spaces/AAAA --body-file ./message.json

# Endpoints whose parameters Discovery does not describe take raw query pairs.
$ grr api call drive.files.list --query alt=json --query fields=files(id,name)

# Override the verb when the Discovery document is behind the live API.
$ grr api call tasks.tasks.list --method-override GET

# Sheets: read a range, write a range, append a row.
$ grr sheets spreadsheets values get --spreadsheet-id 1a2b3c --range Sheet1!A1:D10
$ grr sheets spreadsheets values update --spreadsheet-id 1a2b3c --range Sheet1!A1 \
    --body-file ./values.json
$ grr sheets spreadsheets values append --spreadsheet-id 1a2b3c --range Sheet1!A:A \
    --value-input-option USER_ENTERED

# Docs: create, read, and batch-update.
$ grr docs documents get --document-id 1a2b3c
$ grr docs documents create --body-file ./new-doc.json
$ grr docs documents batchUpdate --document-id 1a2b3c --body-file ./requests.json

# Slides: presentations, pages, and thumbnails.
$ grr slides presentations get --presentation-id 1a2b3c
$ grr slides presentations pages getThumbnail \
    --presentation-id 1a2b3c --page-object-id g1

Note the colon-verb path templates — values/{range}:append, documents/{documentId}:batchUpdate. The braces are path placeholders, so --range Sheet1!A1:D10 substitutes into the URL and is percent-encoded for you, colons and all.

Sheets and Slides writes need the request body as a nested structure, which is what --body-file is for. Generating that JSON in a heredoc and piping it through stdin (--body-file -) keeps it out of shell-quoting hell. And camelCase methods keep their casing as leaf aliases: getThumbnail, not get-thumbnail.

Discovery lists each method’s accepted scopes from broadest to narrowest, usually with https://mail.google.com/ or .../auth/drive first. grr api describe reports the narrowest entry as leastPrivilegeScope, which is the right thing to show a human deciding what a call touches.

Reporting is the only place scope shows up during a call, though. There is no per-method consent gate: grr auth login asks for a small default set and --service <name> widens it from the same index, so a call is never compared against the set or annotated when a narrow scope differs from a broader one you hold — and a service you have not asked for yet is one command away.

That leaves one honest failure mode: the scope a method declares may not be in the credential’s grant yet. grr names the scope it asked for and points at the remedy:

$ grr api list --service tasks
14 methods

$ grr api describe tasks.tasks.list
# leastPrivilegeScope: https://www.googleapis.com/auth/tasks.readonly
#   -> in the default grant: Tasks is one of the services login covers

$ grr tasks tasks list --tasklist @default
GET https://tasks.googleapis.com/tasks/v1/users/@me/lists -> HTTP 403: this
method needs the `https://www.googleapis.com/auth/tasks.readonly` scope.
Tasks is inside the default grant this build asks for, so a 403 here means the
API is not enabled on the Cloud project, or the grant was narrowed. Services
outside the default set (chat, forms, searchconsole) need
`grr auth login --service <service>` to widen it.

A service outside the default set is one command away. Tasks, Analytics Admin, Analytics Data, Search Console, and Apps Script (including scripts.run) all declare scopes that grr auth login --service <name> requests, so a live call succeeds as soon as the API is enabled on your Cloud project. Gmail CSE keypairs, S/MIME settings, directory people, and the Chat admin surface come in the same way. The one deliberate exception is Chat’s app-authentication surface (chat.bot, chat.app.*, chat.import): Google grants those to a service account, and a consent screen that asks for one is rejected outright, so they are filtered out — the methods behind them authenticate as the app, never as you. A residual 403 names the scope it wanted and the widening command for it.

The trade-off sits on the consent screen, and it flipped: a small list to approve, plus one command when a task reaches past it. --all-scopes still asks for the whole index in one go, which is the right call on a verified project where a long list is only a long page.