Google Workspace CLI (gws) — One CLI for Drive, Gmail, Calendar & More

The Google Workspace CLI (gws) is a Rust-based command-line tool that provides unified access to all Google Workspace APIs — Drive, Gmail, Calendar, Sheets, Docs, Chat, and more. Unlike traditional CLIs with static commands, gws reads Google's Discovery Service at runtime and builds its entire command surface dynamically. When Google adds a new API endpoint, gws picks it up automatically.

Key features:

• Dynamic command generation from Google's Discovery Service (no hardcoded API list)
• Structured JSON output for all responses (human-readable tables also available)
• 100+ AI agent skills included for Claude Code, OpenClaw, and Gemini CLI
• OAuth 2.0 authentication with encrypted credential storage
• Auto-pagination, dry-run mode, and schema introspection
• Helper commands for common workflows (e.g., +send, +triage, +agenda)

Before installing gws, ensure you have:

• Node.js 18+ — required if installing via npm (or download pre-built binaries)
• A Google Cloud project — required for OAuth credentials (can be created via Google Cloud Console, gcloud CLI, or gws auth setup)
• A Google account with access to Google Workspace
• Rust toolchain (optional) — only needed if building from source via cargo

Choose the installation method that best fits your environment. The recommended approach is downloading pre-built binaries from GitHub Releases.

After installation, verify that gws is available in your PATH and check the version.

The fastest way to authenticate is using gws auth setup, which automates Google Cloud project creation, API enablement, and initial login. This requires the gcloud CLI to be installed and authenticated.

Credentials are encrypted at rest using AES-256-GCM with the encryption key stored in your OS keyring (macOS Keychain, Windows Credential Manager, or Linux Secret Service).

If you don't have gcloud installed or want explicit control over the OAuth setup, you can configure credentials manually via the Google Cloud Console.

Once authenticated, you can start using gws to interact with Google Workspace APIs. All commands follow the pattern: gws <service> <resource> <method> [flags]

gws includes hand-crafted helper commands (prefixed with +) for common workflows. These provide a simpler interface than raw API calls and handle complex logic like threading, metadata, and timezone awareness.

Run gws <service> --help to see both Discovery methods and helper commands.

The repository includes 100+ AI agent skills as SKILL.md files — one for every supported Google Workspace API plus 50+ curated recipes for common workflows. These skills can be integrated into Claude Code, OpenClaw, or Gemini CLI.

For CI/CD pipelines or headless servers, you can export credentials from an authenticated machine and use them elsewhere via environment variables.

Multipart Uploads:

gws drive files create --json '{"name": "report.pdf"}' --upload ./report.pdf

Pagination:

# Auto-paginate (NDJSON output, one page per line)
gws drive files list --page-all

# Limit pages
gws drive files list --page-all --page-limit 5

# Add delay between pages
gws drive files list --page-all --page-delay 200

Google Sheets Range Escaping:

# Always wrap ranges in single quotes (! triggers bash history expansion)
gws sheets spreadsheets values get \
  --params '{"spreadsheetId": "ID", "range": "Sheet1!A1:C10"}'

Model Armor (Response Sanitization):

# Scan API responses for prompt injection
gws gmail users messages get --params '...' \
  --sanitize "projects/P/locations/L/templates/T"

Understanding the underlying technology helps with troubleshooting and customization.

Core Language: Rust (Cargo workspace with 2 crates: google-workspace-cli and google-workspace)

Key Dependencies:

• clap (v4) — CLI framework with derive macros for dynamic command generation
• tokio (v1) — Async runtime for concurrent HTTP requests
• reqwest (v0.12) — HTTP client with rustls-tls, JSON, streaming, and SOCKS proxy support
• yup-oauth2 (v12) — OAuth 2.0 flow implementation
• aes-gcm (v0.10) — AES-256-GCM encryption for credential storage
• keyring (v3.6) — OS-level keyring integration (macOS Keychain, Windows Credential Manager, Linux Secret Service)
• serde + serde_json — JSON serialization/deserialization
• ratatui + crossterm — Terminal UI for interactive prompts
• chrono + chrono-tz — Timezone-aware date/time handling
• dotenvy — .env file loader

Architecture:

1. Parse argv[1] to identify service (e.g., drive)
2. Fetch service Discovery Document from Google (cached 24h)
3. Build clap::Command tree from resources/methods
4. Re-parse remaining arguments against dynamic schema
5. Authenticate, build HTTP request, execute, return structured JSON

All environment variables are optional. They can be set in your shell or in a .env file in the working directory.

"Access blocked" or 403 during login: Your OAuth app is in testing mode and your account is not listed as a test user. Fix: Open the OAuth consent screen → Test users → Add users → enter your email.

"Google hasn't verified this app": Expected for testing mode apps. Click Advanced → "Go to <app name> (unsafe)" to proceed. Safe for personal use.

Too many scopes / consent screen error: Unverified apps are limited to ~25 scopes. The recommended preset has 85+ scopes. Fix: gws auth login --scopes drive,gmail,calendar

redirect_uri_mismatch: OAuth client was not created as "Desktop app" type. Delete the client, create a new one with type "Desktop app", and re-download.

API not enabled (accessNotConfigured): The required Google API is not enabled for your GCP project. Enable it in the API Library or run the command again — gws will print the exact enable link.

gws uses structured exit codes so scripts can branch on failure types without parsing error output.

• 0 — Success
• 1 — General error
• 2 — Authentication error
• 3 — API error (e.g., 404, 403)
• 4 — Network error
• 5 — Configuration error
• 6 — User cancellation

Example:

if ! gws drive files list; then
  case $? in
    2) echo "Auth failed. Run: gws auth login" ;;
    3) echo "API error. Check permissions." ;;
    4) echo "Network error. Check connectivity." ;;
  esac
fi

Email Automation:

# Triage unread emails
gws gmail +triage

# Watch for new emails and process with jq
gws gmail +watch | jq -r 'select(.from | contains("boss@")) | .subject'

# Send automated reports
gws gmail +send --to team@example.com --subject "Daily Report" --body "$(./generate-report.sh)"

Drive File Management:

# Upload files in bulk
find ./reports -name "*.pdf" -exec gws drive +upload {} \;

# List shared files
gws drive files list --params '{"q": "sharedWithMe=true"}' --page-all | jq -r '.files[].name'

Calendar Integration:

# Daily standup: show today's agenda
gws calendar +agenda --today

# Create meeting from script
gws calendar +insert \
  --summary "Team Sync" \
  --start "2026-05-23T14:00:00-07:00" \
  --end "2026-05-23T15:00:00-07:00"

Sheets Data Pipeline:

# Append CSV rows to a sheet
cat data.csv | while IFS=, read -r name score; do
  gws sheets +append --spreadsheet SHEET_ID --values "$name,$score"
done

• Explore the API surface: Run gws <service> --help for any service (e.g., gws drive --help, gws gmail --help) to see available resources and methods
• Read the Skills Index: Check docs/skills.md for the full list of 100+ AI agent skills
• Join the community: Star the repo on GitHub, file issues, or contribute helper commands
• Integrate with Claude Code: Install the skills and use gws in your development workflow for automated Google Workspace interactions
• Build automation: Use gws in CI/CD pipelines, cron jobs, or serverless functions to automate Workspace tasks