grr GitHub
Six services · one login

Google tools,
at terminal speed.

Zero-config, maximum-performance Google tools from the terminal. One binary, six services, and output that plays nicely with jq.

GitHub releases Install grr

Configure one OAuth client ID. The CLI handles the rest.

grr // online A dimensional grr terminal workspace
one login · six services
public pulse

Small binary.
Real reach.

Build-time numbers from the public package and release channels, with a quiet optional refresh in your browser.

package version v0.4.0 the current published line
crates.io downloads 10 10 in the last 30 days
platforms 3 macOS · Linux · Windows
services 6 one namespaced binary
latest release v0.3.0
GitHub asset downloads 8 across all public releases
Snapshot refreshed Install the binary
six services · one login

The useful parts of your Google account, namespaced.

Keep commands close to the work they support. Every data command accepts JSON, JSONL, table, or pretty output; JSON is the default.

01 / inbox

Gmail

Search, read, compose, label, filter, route mail, and batch without leaving your shell.

  • Search and read messages
  • Compose, label, and route mail
  • Batch and filter messages
  • Manage threads, history, and send-as
Gmail workspace
Gmail illustration
grr gmail 
grr gmail message search "in:inbox" --max 5
More verified commands
  • grr gmail message search "in:inbox" --max 5
  • grr gmail msg filter-list
  • grr gmail thread list
  • grr gmail send-as verify alias@example.com
02 / time

Calendar

List calendars, manage events, watch changes, and check free-busy windows in one pass.

  • List calendars and events
  • Create, update, move, and delete
  • Watch changes and free-busy
  • Manage sharing, settings, and colors
Calendar workspace
Calendar illustration
grr calendar 
grr calendar events --max 10
More verified commands
  • grr calendar events --max 10
  • grr calendar patch <calendar-id> <event-id> --summary "Updated"
  • grr calendar watch <calendar-id> --webhook https://example.com/hook
03 / files

Drive

Find files, inspect metadata, manage sharing and comments, and control storage.

  • Find files and inspect metadata
  • Upload, download, and export
  • Manage sharing and comments
  • Restore, rename, and control storage
Drive workspace
Drive illustration
grr drive 
grr drive list --trashed --max 20
More verified commands
  • grr drive list --trashed --max 20
  • grr drive comment-add <file-id> --text "Note"
  • grr drive quota
04 / people

Contacts

Query people, organize groups, batch-read profiles, and keep photos close to your workflows.

  • Search and organize people
  • Create, update, and manage groups
  • Batch-read profiles and photos
  • Adopt contacts and keep photos close
Contacts workspace
Contacts illustration
grr contacts 
grr contacts list --max 20
More verified commands
  • grr contacts list --max 20
  • grr contacts get-batch --people people/123
  • grr contacts photo-set <people/123> --path photo.jpg
05 / rooms

Chat

Browse spaces, manage members, read messages, and react without context switching.

  • Browse spaces and members
  • Add and remove members
  • Read and send messages
  • React and unreact to messages
Chat workspace
Chat illustration
grr chat 
grr chat spaces --max 10
More verified commands
  • grr chat spaces --max 10
  • grr chat member-add <space-id> --user user@example.com
  • grr chat react <space-id> <message-id> --emoji "👍"
06 / signals

Forms

Read and update forms, pull responses, and manage watch channels for lightweight automation.

  • Read and update forms
  • Pull response data
  • Create and manage watch channels
  • Renew and delete watches
Forms workspace
Forms illustration
grr forms 
grr forms get <form-id>
More verified commands
  • grr forms get <form-id>
  • grr forms responses <form-id> --max 50
  • grr forms watch-renew <form-id> <watch-id>
complete 0.4 command surface

Every branch, still namespaced.

06 services
Gmail
message, label, draft, send, thread, history, send-as, profile, watch, import, msg; msg: label, trash, untrash, delete, batch-label, batch-delete, filter-list, filter, filter-create, filter-delete, forwarding-list, forwarding-create, forwarding-delete, autoforwarding, autoforwarding-set, pop, pop-set, imap, imap-set; thread: list, label, trash, untrash, delete; send-as: list, get, create, update, delete, verify
Calendar
list, events, get, new, create, update, delete, free-busy, set, instances, patch, move, watch, stop, colors, settings, share, shares, unshare
Drive
list, search, get, mkdir, trash, restore, copy, empty-trash, download, upload, rename, delete, export, share, shares, unshare, comments, comment, comment-add, comment-delete, revisions, revision, quota
Contacts
list, search, get, create, update, delete, groups, group, group-new, group-rename, group-delete, group-add, group-remove, get-batch, others, adopt, photos, photo-set, photo-remove
Chat
spaces, space, space-new, space-rename, space-delete, members, member, member-add, member-remove, messages, send, react, reactions, unreact
Forms
get, responses, new, update, watch, watches, watch-delete, watch-renew

Run grr <service> --help and grr schema for the exact flags. Gmail filters, forwarding, auto-forwarding, POP, and IMAP are under grr gmail msg; thread list, send-as verify, and paginated history are also available.

use it as a library

One crate. Only the services you need.

The published package is grr-cli. Its default features are default = ["cli", "http3"]; the cli feature enables the complete binary and all six services (the grr binary uses required-features = ["cli"]), while gmail, calendar, drive, people, chat, and forms can be selected independently. With default-features = false, the library builds on stable Rust over HTTP/2. HTTP/3 is the http3 feature and needs nightly Rust plus the reqwest_unstable cfg.

cargo · library 
[dependencies]
grr-cli = { version = "0.4.0", default-features = false, features = ["gmail"] }
built for the shell

Less glue.
More signal.

grr is deliberately small at the interface: predictable commands, fast transport, and no hidden service setup.

01

HTTP/3 when available

The transport probes authenticated QUIC at startup and falls back silently to HTTP/2 when it cannot negotiate.

02

nightly Rust

The CLI enables HTTP/3 through reqwest and QUIC support, which is gated behind Rust nightly and the reqwest_unstable cfg.

03

keyring tokens

PKCE is always enabled; tokens are kept in the operating system keyring, with a local file fallback for headless systems.

04

streaming output

Results go to stdout and logs go to stderr, so jq, scripts, and agents get predictable data by default.

one clean session

From inbox to insight, without the tab.

Search a message, fetch a bounded body, and keep the output parseable. The command tree is available as JSON for agents with grr schema.

Browse command examples
terminal · grr 
$ grr auth login
✓ browser consent complete

$ grr gmail message search "in:inbox" --max 1
[{"id":"191f8ab2","threadId":"191f8ab2","subject":"Build notes"}]

$ grr gmail message get 191f8ab2 --message-format metadata --body --max-length 2000
{"message":{...},"body":"..."}
machine-friendly by default

Your shell is the API client.

Use a human-readable table when you need it, or keep the default JSON and let the next tool take it from there.

pipe-friendly output 
$ grr gmail message search "from:github.com" --max 10 | jq -r '.[0].id'
191f8ab2

$ grr transport
{"http_version":"h3","fallback":"h2"}
go deeper
crates.io ↗ Package metadata, versions, and the published crate. docs.rs ↗ Generated API documentation for the published crates. GitHub ↗ README, releases, source, and the issue tracker.
questions, answered

No mystery meat.

The short version of the things people usually want to know before putting a Google account behind a terminal tool.

What is grr?
grr is a Rust CLI for Google services from the terminal. It combines Gmail, Calendar, Drive, Contacts, Chat, and Forms in one namespaced binary with machine-readable output and a single OAuth login.
How does OAuth work?
You create a Google Cloud Desktop OAuth client, put its client ID in ~/.grr/config.toml, and run grr auth login. PKCE is always enabled; tokens are kept in the operating system keyring, with a local file fallback for headless systems. grr auth login --device prints a URL and code for machines without a browser.
Do I need to log in again for 0.4?
Yes. Version 0.4 adds chat.delete, chat.memberships, chat.messages.reactions, and contacts.other.readonly scopes. Run grr auth login again to grant the expanded permissions; device flow is available for headless machines.
Is grr affiliated with Google?
No. grr is an independent project. It is not affiliated with, sponsored by, or endorsed by Google LLC. It uses public Google APIs and your own Google account credentials.
How do I install it?
Use a prebuilt GitHub Release, the documented Homebrew or winget package, or cargo install grr-cli from crates.io. The install page has the exact commands, including the nightly Rust setup needed by the CLI HTTP/3 build.
Why does it need nightly Rust?
The CLI enables HTTP/3 through reqwest and QUIC support, which is gated behind Rust nightly and the reqwest_unstable cfg. The repo pins the required toolchain and sets the cfg for in-repo builds; the CLI falls back to HTTP/2 at runtime if QUIC is unavailable.

Your Google workflows deserve a better terminal.

Grab a binary, point it at your own OAuth client, and let grr get out of the way.

Choose your install path

grr is an independent project and is not affiliated with, sponsored by, or endorsed by Google LLC.