Google CLI

A command-line interface for Google services (Gmail, Calendar) designed for LLMs and developers. JSON output by default.

Installation

Requires Bun.

bun install -g @stephendolan/google-cli

# Or run without installing
bunx @stephendolan/google-cli auth status

sudo apt-get install libsecret-1-dev  # Ubuntu/Debian
sudo dnf install libsecret-devel      # Fedora/RHEL
sudo pacman -S libsecret              # Arch

Without libsecret, use environment variables instead.

Setup

1. Create a Google Cloud project
2. Enable the Gmail API and Calendar API
3. Create OAuth2 credentials (Desktop application)
4. Add http://localhost:8089/callback as an authorized redirect URI
5. Authenticate:

google auth login --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

Commands

Authentication

google auth login --client-id <id> --client-secret <secret>
google auth login --client-id <id> --client-secret <secret> --name work
google auth status
google auth logout
google auth current                             # Show active profile
google auth list                                # List all profiles
google auth switch <name>                       # Switch to profile
google auth delete <name>                       # Delete a profile
google auth export                              # Export credentials to stdout
google auth export -o credentials.json          # Export to file
google auth import -f credentials.json          # Import from file
google auth import --name work -f creds.json    # Import with custom profile name

Use -p, --profile with status, logout, and export to target a specific profile:

google -p work auth status
google -p work auth export -o work-creds.json

Or use environment variables:

• GOOGLE_CLIENT_ID (or GMAIL_CLIENT_ID)
• GOOGLE_CLIENT_SECRET (or GMAIL_CLIENT_SECRET)
• GOOGLE_TOKENS (or GMAIL_TOKENS) - JSON string of OAuth tokens

Calendar

google calendar calendars                    # List all calendars
google calendar today                        # Today's events
google calendar week                         # This week's events
google calendar list --from 2026-01-01 --to 2026-01-31  # Date range
google calendar search "meeting"             # Search upcoming events
google calendar event <event-id>             # Get specific event

Messages

google messages list                         # List recent messages
google messages list --limit 50              # Limit results
google messages list --query "is:unread"     # Filter with Gmail search
google messages list --label INBOX           # Filter by label

google messages read <message-id>            # Read a specific message
google messages read <id> --format full      # Full/metadata/minimal format
google messages search "from:[email protected]"  # Search messages
google messages attachment <msg-id> <att-id>   # Download attachment
google messages attachment <msg-id> <att-id> -o file.pdf  # Save to file

Inbox

google inbox list                            # List inbox messages
google inbox list --unread                   # Only unread messages
google inbox search <query>                  # Search within inbox

Drafts

google drafts list                           # List all drafts
google drafts read <draft-id>                # Read a draft

google drafts create \
  --to [email protected] \
  --subject "Hello" \
  --body "Message body"

Labels

google labels list                           # List all labels

MCP Server

Run as an MCP server for AI agent integration:

google mcp

MCP Tools

Gmail

| Tool | Description | |------|-------------| | check_auth | Check authentication status | | list_messages | List inbox messages | | read_message | Read a specific message | | search_messages | Search with Gmail syntax | | list_labels | List all labels | | list_drafts | List drafts | | read_draft | Read a draft | | create_draft | Create a draft | | get_attachment | Download attachment | | current_profile | Get active profile | | switch_profile | Switch to profile | | list_profiles | List all profiles |

Calendar

| Tool | Description | |------|-------------| | list_calendars | List all calendars | | calendar_today | Get today's events | | calendar_week | Get this week's events | | calendar_events | Get events in a date range | | calendar_search | Search upcoming events | | calendar_event | Get a specific event |

Output

All commands output JSON. Use --compact or -c for single-line output:

google messages list                # Pretty-printed JSON
google -c calendar today            # Compact JSON

Errors are also returned as JSON:

{"error": {"name": "auth_error", "detail": "Not authenticated", "statusCode": 401}, "hint": "Run: google auth login"}

Scopes

Required Google API scopes:

| Scope | Purpose | |-------|---------| | gmail.readonly | Read messages, labels, threads | | gmail.compose | Create and modify drafts | | calendar.readonly | Read calendar events |

Note: The gmail.send scope is intentionally not requested. This CLI cannot send emails.

License

MIT