Google Readonly CLI: A Secure Read-Only Tool for Google Services
Primary Purpose:
The Google Readonly Command-Line Interface (CLI) is designed to provide secure, read-only access to various Google services such as Gmail, Calendar, Contacts, and Drive. It enables users to search, view, and interact with their Google data without the ability to modify or delete it.
Key Features:
Secure OAuth Scopes: Utilizes restricted OAuth scopes (gmail.readonly, calendar.readonly, contacts.readonly, drive.readonly) ensuring that only read operations are permitted.
Gmail Support: Users can search for messages using Gmail's syntax, read email content, view conversation threads, list labels, and manage attachments.
Calendar Integration: Allows users to list calendars, view events, and utilize shortcuts like "today" or "week."
Contacts Management: Provides functionality to list contacts, perform searches, view contact details, and access groups.
Drive Access: Users can browse files, search for specific items, view file metadata, download files, and explore folder structures.
Secure Token Storage: OAuth tokens are securely stored in the system keychain on macOS/Linux, ensuring safe credential management.
Audience & Benefit:
Ideal for developers, system administrators, and anyone requiring scriptable access to Google data without write permissions. This tool enables efficient, read-only operations while adhering to secure practices, making it a reliable choice for automating tasks that involve Google services.
Installation via winget is available, providing a straightforward setup process for users on supported platforms.
README
google-readonly
A read-only command-line interface for Google services. Search, read, and view Gmail messages, threads, and attachments without any ability to modify, send, or delete data.
By default, new OAuth apps are in "Testing" mode, which causes tokens to expire after 7 days. To avoid frequent re-authentication:
Go to Google Auth Platform > Audience (or OAuth consent screen in older UI)
Find the Publishing status section
Click Publish app
For personal use with read-only scopes, publishing is straightforward and doesn't require Google verification. Once published, tokens will last until revoked or unused for 6 months.
> Note: If you skip this step, you'll need to run gro init every 7 days to re-authenticate.
Your browser will redirect to a localhost URL (the error page is expected)
Copy the entire URL or just the authorization code
Paste it back into the terminal
Your token will be saved securely (system keychain on macOS/Linux, or ~/.config/google-readonly/token.json as fallback).
Commands
Configuration Commands
# Guided OAuth setup
gro init
# Check configuration status
gro config show
# Test API connectivity
gro config test
# Clear stored OAuth token
gro config clear
# View cache status
gro config cache show
# Clear cached data
gro config cache clear
# Set cache TTL (in hours)
gro config cache ttl 12
# Show version
gro --version
Gmail Commands
All Gmail commands are under gro mail:
# Search messages
gro mail search "is:unread"
gro mail search "from:someone@example.com" --max 20
gro mail search "subject:meeting" --json
# Read a message
gro mail read
gro mail read --json
# View conversation thread
gro mail thread
gro mail thread --json
# List labels
gro mail labels
gro mail labels --json
# List attachments
gro mail attachments list
gro mail attachments list --json
# Download attachments
gro mail attachments download --all
gro mail attachments download --filename report.pdf
gro mail attachments download --all --output ~/Downloads
gro mail attachments download --filename archive.zip --extract
Calendar Commands
All Calendar commands are under gro calendar (or gro cal):
# List all calendars
gro calendar list
gro cal list --json
# List upcoming events
gro calendar events
gro cal events --max 20
gro cal events --from 2026-01-01 --to 2026-01-31
# Get event details
gro calendar get
gro cal get --json
# Today's events
gro calendar today
gro cal today --json
# This week's events
gro calendar week
gro cal week --json
Display cache status including location, TTL, and cached data status.
Usage: gro config cache show [flags]
Flags:
-j, --json Output as JSON
gro config cache clear
Remove all cached data. Cache will be repopulated on next use.
Usage: gro config cache clear
gro config cache ttl
Set the cache time-to-live in hours.
Usage: gro config cache ttl
gro mail search
Search for Gmail messages using Gmail's search syntax.
Usage: gro mail search [flags]
Flags:
-m, --max int Maximum number of results (default 10)
-j, --json Output as JSON
gro mail read
Read the full content of a Gmail message by its ID.
Usage: gro mail read [flags]
Flags:
-j, --json Output as JSON
gro mail thread
Read all messages in a Gmail conversation thread.
Usage: gro mail thread [flags]
Flags:
-j, --json Output as JSON
gro mail labels
List all Gmail labels including user labels and system categories.
Usage: gro mail labels [flags]
Flags:
-j, --json Output as JSON
gro mail attachments list
List all attachments in a Gmail message.
Usage: gro mail attachments list [flags]
Flags:
-j, --json Output as JSON
gro mail attachments download
Download attachments from a Gmail message.
Usage: gro mail attachments download [flags]
Flags:
-f, --filename string Download only this attachment
-o, --output string Output directory (default ".")
-a, --all Download all attachments
-e, --extract Extract zip files after download
gro calendar list
List all calendars the user has access to.
Usage: gro calendar list [flags]
Aliases: gro cal list
Flags:
-j, --json Output as JSON
gro calendar events
List events from a calendar.
Usage: gro calendar events [calendar-id] [flags]
Aliases: gro cal events
Flags:
-c, --calendar string Calendar ID to query (default "primary")
-m, --max int Maximum number of events (default 10)
--from string Start date (YYYY-MM-DD)
--to string End date (YYYY-MM-DD)
-j, --json Output as JSON
gro calendar get
Get the full details of a calendar event.
Usage: gro calendar get [flags]
Aliases: gro cal get
Flags:
-c, --calendar string Calendar ID containing the event (default "primary")
-j, --json Output as JSON
gro calendar today
Show all events for today.
Usage: gro calendar today [flags]
Aliases: gro cal today
Flags:
-c, --calendar string Calendar ID to query (default "primary")
-j, --json Output as JSON
gro calendar week
Show all events for the current week (Monday to Sunday).
Usage: gro calendar week [flags]
Aliases: gro cal week
Flags:
-c, --calendar string Calendar ID to query (default "primary")
-j, --json Output as JSON
Contacts Commands
All Contacts commands are under gro contacts (or gro ppl):
# List all contacts
gro contacts list
gro ppl list --max 20
gro contacts list --json
# Search contacts
gro contacts search "John"
gro ppl search "example.com" --max 20
# Get contact details
gro contacts get people/c123456789
gro ppl get people/c123456789 --json
# List contact groups
gro contacts groups
gro ppl groups --json
gro contacts list
List all contacts sorted by last name.
Usage: gro contacts list [flags]
Aliases: gro ppl list
Flags:
-m, --max int Maximum number of contacts (default 10)
-j, --json Output as JSON
gro contacts search
Search contacts by name, email, phone, or organization.
Usage: gro contacts search [flags]
Aliases: gro ppl search
Flags:
-m, --max int Maximum number of results (default 10)
-j, --json Output as JSON
gro contacts get
Get the full details of a specific contact.
Usage: gro contacts get [flags]
Aliases: gro ppl get
Flags:
-j, --json Output as JSON
gro contacts groups
List all contact groups (labels).
Usage: gro contacts groups [flags]
Aliases: gro ppl groups
Flags:
-m, --max int Maximum number of groups (default 30)
-j, --json Output as JSON
Drive Commands
All Drive commands are under gro drive (or gro files):
# List files in root or folder
gro drive list
gro files list --max 20
gro drive list --type document
# Search files
gro drive search "quarterly report"
gro files search --name "budget" --type spreadsheet
gro drive search --modified-after 2024-01-01
# Get file metadata
gro drive get
gro files get --json
# Download files
gro drive download
gro files download --output ./report.pdf
gro drive download --format pdf # Export Google Doc as PDF
gro drive download --stdout # Write to stdout
# Show folder tree
gro drive tree
gro files tree --depth 3
gro drive tree --files # Include files, not just folders
Shared Drives
gro supports Google Shared Drives (formerly Team Drives). By default, search includes files from all drives you have access to.
# List available shared drives
gro drive drives
gro drive drives --json
# Search all drives (default)
gro drive search "quarterly report"
# Search only your personal drive
gro drive search "quarterly report" --my-drive
# Search a specific shared drive by name
gro drive search "budget" --drive "Finance Team"
gro drive list --drive "Engineering"
gro drive tree --drive "Marketing"
The --my-drive and --drive flags are mutually exclusive. Shared drive names are cached locally for fast lookups. Run gro drive drives to refresh the cache.
gro drive list
List files in Google Drive root or a specific folder.
Usage: gro drive list [folder-id] [flags]
Aliases: gro files list
Flags:
-m, --max int Maximum number of files (default 25)
-t, --type string Filter by type (document, spreadsheet, presentation, folder, pdf, image, video, audio)
--my-drive List from My Drive only
--drive string List from specific shared drive (name or ID)
-j, --json Output as JSON
gro drive search
Search for files in Google Drive. By default, searches all drives you have access to.
Usage: gro drive search [query] [flags]
Aliases: gro files search
Flags:
-n, --name string Search by filename only
-t, --type string Filter by file type
--owner string Filter by owner (me, or email)
--modified-after string Modified after date (YYYY-MM-DD)
--modified-before string Modified before date (YYYY-MM-DD)
--in-folder string Search within folder ID
--my-drive Search only My Drive
--drive string Search specific shared drive (name or ID)
-m, --max int Maximum results (default 25)
-j, --json Output as JSON
gro drive get
Get detailed metadata for a file.
Usage: gro drive get [flags]
Aliases: gro files get
Flags:
-j, --json Output as JSON
gro drive download
Download a file or export a Google Workspace file.
Usage: gro drive download [flags]
Aliases: gro files download
Flags:
-o, --output string Output file path
-f, --format string Export format for Google Workspace files
--stdout Write to stdout instead of file
Export formats for Google Workspace files:
Documents: pdf, docx, txt, html, md, rtf, odt
Spreadsheets: pdf, xlsx, csv, tsv, ods
Presentations: pdf, pptx, odp
Drawings: pdf, png, svg, jpg
gro drive tree
Display folder structure as a tree.
Usage: gro drive tree [folder-id] [flags]
Aliases: gro files tree
Flags:
-d, --depth int Maximum depth to traverse (default 2)
--files Include files in addition to folders
--my-drive Show My Drive only (default)
--drive string Show tree from specific shared drive
-j, --json Output as JSON
gro drive drives
List all shared drives accessible to you.
Usage: gro drive drives [flags]
Aliases: gro files drives
Flags:
--refresh Force refresh from API (ignore cache)
-j, --json Output as JSON
gro supports tab completion for bash, zsh, fish, and PowerShell.
Bash
# Load in current session
source <(gro completion bash)
# Install permanently (Linux)
gro completion bash | sudo tee /etc/bash_completion.d/gro > /dev/null
# Install permanently (macOS with Homebrew)
gro completion bash > $(brew --prefix)/etc/bash_completion.d/gro
Zsh
# Load in current session
source <(gro completion zsh)
# Install permanently
mkdir -p ~/.zsh/completions
gro completion zsh > ~/.zsh/completions/_gro
# Add to ~/.zshrc if not already present:
# fpath=(~/.zsh/completions $fpath)
# autoload -Uz compinit && compinit
Fish
# Load in current session
gro completion fish | source
# Install permanently
gro completion fish > ~/.config/fish/completions/gro.fish
PowerShell
# Load in current session
gro completion powershell | Out-String | Invoke-Expression
# Install permanently (add to $PROFILE)
gro completion powershell >> $PROFILE
Configuration
Configuration files are stored in ~/.config/google-readonly/:
File
Description
credentials.json
OAuth client credentials (from Google Cloud Console)
token.json
OAuth access/refresh token (fallback if keychain unavailable)
config.json
User settings (cache TTL, etc.)
cache/
Cached API metadata for faster repeated lookups
Cache Settings
gro caches Drive metadata (like shared drive lists) to speed up repeated commands. The cache TTL is configured during gro init (default: 24 hours).
# View cache status
gro config cache show
# Clear cache
gro config cache clear
# Change cache TTL
gro config cache ttl 12 # Set to 12 hours
The cache is automatically repopulated when stale or after being cleared.
Security
This tool only requests read-only access to Google services
No write, send, or delete operations are possible
OAuth tokens are stored in system keychain (macOS Keychain / Linux secret-tool) when available
File-based storage uses 0600 permissions
Credentials never leave your machine
Zip extraction includes security safeguards (size limits, path traversal prevention)
Troubleshooting
"Unable to read credentials file"
Ensure credentials.json exists:
ls -la ~/.config/google-readonly/credentials.json
"Token has been expired or revoked"
Clear the token and re-authenticate:
gro config clear
gro init
"Access blocked: This app's request is invalid"
Your OAuth consent screen may not be properly configured. Ensure:
All required APIs are enabled (Gmail, Calendar, People, Drive)
Your email is added as a test user (for apps in testing mode)
The required scopes are added
"API has not been used in project" or "SERVICE_DISABLED"
The specific Google API hasn't been enabled in your Cloud project:
Check the error message for the activation URL
Visit the URL and click Enable
Wait a few minutes for propagation
Clear your token and re-authenticate:
gro config clear
gro init
"Request had invalid authentication credentials"
Your token may be missing scopes for a newly added service. Clear and re-authenticate:
gro config clear
gro init
Token expires every 7 days
Your OAuth app is likely still in "Testing" mode. See Publish Your OAuth App in the setup guide. Apps in testing mode have tokens that expire after 7 days.