14 services, one generated tree.

json (default), jsonl, table, pretty. JSON is the default because the common consumer is a pipe, not a person.

jsonl emits one JSON document per line for array results, which is what you want when streaming into jq without loading everything. table renders arrays as one row per element with the union of keys as columns, a single object as a Field/Value table, and nested values as compact JSON inside a cell.

# Every command accepts -f/--format. JSON is the default. Google's list
# methods return their own wrapper object -- messages, files, items -- and
# grr prints it verbatim rather than unwrapping it, so table shows the
# object Field/Value and jsonl emits that one object:
$ grr gmail users messages list --user-id me --max-results 5 -f table
+--------------------+-------------------------------------------------+
| Field              | Value                                           |
+--------------------+-------------------------------------------------+
| messages           | [{"id":"19f8ab2c","threadId":"19f8ab2c"}, ...]  |
| resultSizeEstimate | 5                                               |
+--------------------+-------------------------------------------------+

$ grr gmail users messages list --user-id me -f jsonl
{"messages":[{"id":"19f8ab2c","threadId":"19f8ab2c"}],"resultSizeEstimate":1}

# grr api list is a bare array, so it tables one row per method and streams
# one element per line -- the shape jsonl is actually for:
$ grr api list --service docs -f jsonl
{"http":"POST","id":"docs.documents.batchUpdate","summary":"Applies one or more updates to the document."}
{"http":"POST","id":"docs.documents.create","summary":"Creates a blank document using the title given in the request."}
{"http":"GET","id":"docs.documents.get","summary":"Gets the latest version of the specified document."}

$ grr api list --service docs -f pretty

grr ask runs three small judgments against a System One provider, each one HTTP request: a Choice over the 14 services, then a Choice over the chosen service’s methods, then one typed question per required parameter. The CLI supplies every candidate from the embedded Discovery index, so the model can only select a service, a method, or a value it was handed — it cannot invent one. The plan is the default output; --run executes the resolved request through the same call path as grr api call.

The defaults point at TypeSafe’s hosted endpoint and its Jev model, so the only thing you must supply is a key. The provider is agnostic: any endpoint that speaks the same contract — POST a state plus typed questions, answer with an answers map — works by pointing endpoint and model at it.

# ~/.grr/config.toml -- every key is optional; the defaults are shown.
[systemone]
endpoint = "https://api.typesafe.ai/v1/systemone"
model = "jev-latest"
confidence-threshold = 0.6
# api-key = "..."   # avoid: prefer TYPESAFE_API_KEY so the key stays out of the file

Keys are kebab-case (api-key, confidence-threshold); snake_case aliases keep TS-era configs working, and any field left unset falls back to its default. The env route is preferred for the key, because a key in a config file can leak with the file:

# Preferred key route: it never sits in a file that can be committed.
export TYPESAFE_API_KEY="..."
grr ask "show my unread messages"          # prints the plan, sends nothing to Google
grr ask "show my unread messages" --run    # executes the resolved request

# The generic GRR_ prefix reaches the rest of the section too:
# GRR_SYSTEMONE__ENDPOINT, GRR_SYSTEMONE__MODEL, GRR_SYSTEMONE__API_KEY

• What the model decides: which service, which method, and which value for each required parameter — always a choice among code-supplied options — plus a confidence for each.
• What the CLI decides: the candidate sets, the parameter types and coercion, the scope note, and the safety gate. --readonly/--deny-service/--deny-verb fire the moment the method resolves, before the parameter judgment. A choice confidence below the threshold (default 0.6) is flagged on stderr, never blocked.
• The key rides only in the Authorization header — never in a request body, the plan output, or an error message. A missing key fails with the ways to supply one rather than a bare 401.
• Planning still needs the provider. Even without --run, the routing judgments are HTTP calls, so grr ask needs a reachable endpoint and a valid key; --service skips the first judgment and --method skips both, going straight to parameter fill.

Safety profiles, everywhere at once

--readonly, --deny-service (a service name) and --deny-verb (an HTTP verb) are global flags honored by the generated tree, grr api call and the MCP server alike. They parse before or after the subcommand, and turn a destructive method into an actionable error naming the method, the verb, and the way out.

# --readonly refuses every write verb, before or after the subcommand
grr --readonly gmail users messages delete --user-id me --id abc
# -> Error: 'gmail.users.messages.delete' is a DELETE (write); --readonly refuses writes.

grr --deny-service chat chat spaces list
# -> Error: 'chat.spaces.list' belongs to service chat, which --deny-service refuses.

# reads are never refused
grr --readonly gmail users messages list --user-id me --dry-run   # runs, JSON out

Conventions worth knowing

• Results on stdout, logs on stderr. The tracing subscriber is wired to stderr explicitly, so grr … | jq never receives a log line. The one stdout exception is grr auth login --device, which prints its human-readable URL and code before the final JSON.
• Paging is yours to drive. The tree does not follow page tokens: --max-results is the API’s own page size, and --page-token takes the nextPageToken from the previous response. That keeps a list command from turning into an unbounded crawl.
• Booleans are presence flags (--include-spam-trash), a deliberate change from value-taking booleans: a flag is either passed or absent, so a script never has to guess.
• Errors are actionable. A 403 names the missing scope, an unknown method id returns ranked suggestions, a missing required parameter names itself. Non-zero exit on failure, always.
• Three commands print plain text, not JSON: grr transport, grr skills install (a human install summary), and the device-login line above. grr skills list is JSON. --dry-run output is JSON, so it pipes.
• Timestamps are RFC 3339 (--time-min 2026-10-01T00:00:00Z), or a bare YYYY-MM-DD where the API accepts a date.
• grr --version is a banner. The semver is its first line, which is what the benchmark script and the Homebrew formula read; below it sits the crab mascot, drawn in 24-bit-colour pixel art on a terminal that advertises COLORTERM or direct colour and as plain ASCII everywhere else. A pipe, TERM=dumb or NO_COLOR all give you the ASCII crab — so scripts are never handed escape sequences. CLICOLOR_FORCE=1 forces the colour logo through a pipe.

Where the tree comes from

Every leaf above is generated from the committed Discovery index at build time and refreshed daily by a workflow PR. The same index drives the flat grr api surface, so the census never splits in two.

• Discovery API — the index behind the whole tree
• Agents and harnesses — output contract and discovery discipline
• Getting started — install, login, and verify