google-workspace-cli

Lightweight CLI for Google Workspace APIs (Docs, Drive). Designed for scripting, automation, and Claude Code skills — no MCP context bloat.

Setup (2 minutes)

1. Install gcloud SDK

# macOS
brew install google-cloud-sdk

# Linux
curl https://sdk.cloud.google.com | bash

# Or see https://cloud.google.com/sdk/docs/install

2. Authenticate

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/documents,https://www.googleapis.com/auth/drive

This opens your browser once. Tokens are stored locally and refreshed automatically.

3. Install gwcli

pip install google-workspace-cli
# or
uv add google-workspace-cli

That's it. No GCP project, no client IDs, no .env files.

Usage

Google Docs

# Read a doc (by ID or URL)
gwcli docs read 1Ez3iDf3j_tOrFuodrcO60mQfHrg2Ny-eimjXF10L4m8
gwcli docs read "https://docs.google.com/document/d/1Ez3.../edit"

# Read as JSON (full API response)
gwcli docs read DOC_ID --format json

# Create a new doc
gwcli docs create "Meeting Notes" --body "## Agenda\n\n- Item 1"

# Append text
gwcli docs append DOC_ID "New paragraph at the end"

# Pipe from stdin
echo "Appended from pipe" | gwcli docs append DOC_ID -

# Find and replace
gwcli docs replace DOC_ID --find "old text" --replacement "new text"

# Insert at position
gwcli docs insert DOC_ID "Inserted text" --index 1

# Add a comment
gwcli docs comment DOC_ID "This needs revision"

# List comments
gwcli docs comments DOC_ID
gwcli docs comments DOC_ID --include-resolved

Google Drive

# Search files
gwcli drive search "quarterly report"
gwcli drive search "name contains 'budget' and mimeType = 'application/vnd.google-apps.spreadsheet'"

# List files
gwcli drive list
gwcli drive list --folder FOLDER_ID --max 50

# Export a Google Doc as text
gwcli drive export DOC_ID --format txt

# Export as PDF
gwcli drive export DOC_ID --format pdf --output report.pdf

# Download an uploaded file (.docx, etc.)
gwcli drive export FILE_ID --output document.docx

# File metadata
gwcli drive info FILE_ID

Auth without gcloud

If you don't have gcloud installed, you can use OAuth directly:

1. Create a GCP project and OAuth client ID (Desktop app type)
2. Download the client secret JSON
3. Save it as ~/.config/gwcli/client_secret.json
4. Run gwcli auth login

Tokens are stored in ~/.config/gwcli/token.json and refreshed automatically.

As a Claude Code Skill

This CLI is designed to be called from Claude Code skills via Bash. No MCP server registration needed — just document the commands in a SKILL.md and call them.

See SKILL.md example for a ready-to-use skill definition.

License

MIT