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
308 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": "20260921",
  "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.

Every service in the index has a full generated command namespace now — the cards above are the namespaces. grr api is not the only way into any of them; it is the flat alternative when you would rather compose an id than walk a path.

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.

Before sending, grr compares that narrowest scope against the consented set. When it is not there, it prints a note to stderr and attempts the call anyway, because the narrow scope is often a sibling of a broader one the build does hold — drive.readonly and drive.file are both satisfied by the consented auth/drive. A note on stderr is a heads-up, not a failure. Treat the exit status as the answer.

Where a method genuinely needs a scope nobody consented to, grr names it. A 403 comes back with the specific scope and the file to edit, rather than a bare permission error:

$ grr api list --service tasks
14 methods

$ grr api describe tasks.tasks.list
# leastPrivilegeScope: https://www.googleapis.com/auth/tasks.readonly
#   -> outside the scopes this build consented to

$ grr tasks tasks list --tasklist @default
note: tasks.tasks.list wants 'https://www.googleapis.com/auth/tasks.readonly',
      which is outside the scopes this build consented to. Attempting anyway;
      if Google answers 403, re-run 'grr auth login' after extending the scope
      set.
... HTTP 403 ...

Tasks is the one service that does not work out of the box. Its fourteen methods need .../auth/tasks or .../auth/tasks.readonly, and neither is in the sixteen consented scopes, nor is any broader scope that would cover them. They list and describe correctly, and --dry-run is accurate, but a live call returns 403 until the scope set in src/core/auth/mod.rs is extended and grr auth login is re-run.

A smaller tail behaves the same way for narrower reasons: Gmail CSE keypairs and S/MIME settings need gmail.settings.* scopes, directory people need directory.readonly, and most of the Chat admin surface (custom emoji, space import) needs scopes outside the consented set. Docs, Sheets, and Slides all work, because their methods accept the Drive scope the build already holds.