@iamrommel/google-cli

A single binary, google-cli, for working with Google Workspace from the terminal — Gmail, Calendar, Tasks, Docs, Sheets, Drive, and Maps.

Designed for per-project configuration so the same install works across many projects with different OAuth credentials. All commands return JSON, so it's easy to script or call from agents.

Install

npm install -g @iamrommel/google-cli

Requires Node.js ≥ 20.

Quick start

# 1. Create a Google Cloud project + OAuth client (one-time, see below)
# 2. Drop client_secret.json into one of the supported locations
# 3. Authorize
google-cli auth setup

# 4. Use it
google-cli gmail send --to "[email protected]" --subject "Hi" --body "Hello"
google-cli calendar list
google-cli drive search "invoice 2026"

Google Cloud setup (one-time)

1. Go to https://console.cloud.google.com/ and create a project (or use an existing one)
2. APIs & Services → Library → enable each of:
   • Gmail API
   • Google Calendar API
   • Google Tasks API
   • Google Docs API
   • Google Drive API
   • Google Sheets API
   • For Maps support also enable: Places API, Directions API, Geocoding API
3. APIs & Services → Credentials → Create Credentials → OAuth client ID
   • Application type: Desktop app
   • Download the JSON
4. Place the downloaded file as client_secret.json somewhere google-cli can find it (see Configuration)
5. Run google-cli auth setup and complete the browser flow — tokens are written next to client_secret.json

Configuration

google-cli resolves credentials in this order (first match wins). Run google-cli auth where to see what got picked up.

| # | Source | How to use | |---|---|---| | 1 | ./.google-cli/ in cwd (walks upward, like git) | mkdir .google-cli && cp ~/Downloads/client_secret.json .google-cli/ — highest priority so project-local always wins | | 2 | Env vars | GOOGLE_CLIENT_SECRET_PATH=/path/to/client_secret.json GOOGLE_TOKENS_PATH=/path/to/tokens.json google-cli ... — or set GOOGLE_CLI_CREDENTIALS_DIR=/path/to/dir to point at a directory containing both | | 3 | $XDG_CONFIG_HOME/google-cli/ (default ~/.config/google-cli/) | mkdir -p ~/.config/google-cli && cp ~/Downloads/client_secret.json ~/.config/google-cli/ | | 4 | Default for first-time write | If nothing above exists, auth setup creates ./.google-cli/ in the current working directory |

Per-project OAuth clients are easy: drop a different .google-cli/ in each project root and that project's CLI runs use it.

Env vars reference

| Variable | Purpose | |---|---| | GOOGLE_CLI_CREDENTIALS_DIR | Override the entire credentials directory | | GOOGLE_CLIENT_SECRET_PATH | Override the client_secret.json path | | GOOGLE_TOKENS_PATH | Override the tokens.json path | | GOOGLE_CLI_TIMEZONE | Default IANA timezone for calendar events (default UTC) | | GOOGLE_MAPS_API_KEY | Required for google-cli maps subcommands |

Command reference

All commands return JSON to stdout. Errors return JSON with an error field and exit non-zero.

Auth

google-cli auth setup           # Interactive OAuth (opens listener, prints URL, waits)
google-cli auth url             # Print the auth URL only (non-blocking)
google-cli auth listen          # Wait for callback on localhost:3456
google-cli auth status          # Show authentication state
google-cli auth where           # Show resolved credentials directory
google-cli auth revoke          # Revoke + delete tokens

Gmail

google-cli gmail send --to "[email protected]" --subject "Hi" --body "Hello"
google-cli gmail send --to "[email protected]" --cc "[email protected]" --subject "Hi" --body "<p>Hello</p>" --html
google-cli gmail draft --to "[email protected]" --subject "Hi" --body "Draft"
google-cli gmail search "is:unread newer_than:7d"
google-cli gmail read <messageId>
google-cli gmail attachments <messageId>
google-cli gmail download-attachment <messageId> --attachment-id <id> --output ./file.pdf
google-cli gmail mark-read <messageId>
google-cli gmail archive <messageId>

Calendar

google-cli calendar list
google-cli calendar list --from 2026-04-23T00:00:00Z --to 2026-04-30T23:59:59Z --max 50
google-cli calendar create --title "Meeting" --start 2026-04-25T10:00:00 --end 2026-04-25T11:00:00 --timezone Asia/Manila
google-cli calendar update <eventId> --title "New title"
google-cli calendar delete <eventId>

Tasks

google-cli tasks lists
google-cli tasks list
google-cli tasks list --show-completed
google-cli tasks create --title "Buy milk" --due 2026-04-25
google-cli tasks update <taskId> --notes "..."
google-cli tasks complete <taskId>
google-cli tasks delete <taskId>

Docs

google-cli docs create --title "Notes" --content "Initial body"
google-cli docs read <docId>
google-cli docs update <docId> --content "Replacement"
google-cli docs update <docId> --content "Appended" --append
google-cli docs list --query "weekly"

Sheets

google-cli sheets create --title "Budget" --sheets "Income,Expenses"
google-cli sheets read <id> --range "Sheet1!A1:D10"
google-cli sheets update <id> --range "Sheet1!A1:B2" --values '[["Name","Age"],["Rommel",30]]'
google-cli sheets append <id> --range "Sheet1!A:B" --values '[["Mandy",1]]'
google-cli sheets add-chart <id> --title "Sales" --type line --data-range "Sheet1!A1:D10"
google-cli sheets clear <id> --range "Sheet1!A1:Z100"
google-cli sheets merge-cells <id> --range "Sheet1!A1:E1"
google-cli sheets format-cells <id> --range "Sheet1!A1:E1" --bold --bg-color "#6AA84F"
google-cli sheets list

Drive

google-cli drive list
google-cli drive search "invoice 2026"
google-cli drive get <fileId>
google-cli drive upload ./report.pdf --parent-id <folderId>
google-cli drive download <fileId> --output ./local.pdf
google-cli drive mkdir "Reports"
google-cli drive share <fileId> --email "[email protected]" --role writer --notify
google-cli drive trash <fileId>
google-cli drive delete <fileId>

Maps (uses an API key, not OAuth)

export GOOGLE_MAPS_API_KEY=...
google-cli maps search "coffee near Makati"
google-cli maps directions --from "BGC" --to "Makati Med" --mode driving
google-cli maps geocode "BGC, Taguig"

Use as a Claude Code skill

A ready-to-use SKILL.md template is shipped at skill-template/SKILL.md. Drop it into your Claude Code project so the agent knows how to call google-cli:

# From your project root
mkdir -p .claude/skills/google
curl -fsSL https://raw.githubusercontent.com/iamrommel/google-cli/main/skill-template/SKILL.md \
  -o .claude/skills/google/SKILL.md

Or, if you have the package installed globally, copy from node_modules:

cp "$(npm root -g)/@iamrommel/google-cli/skill-template/SKILL.md" .claude/skills/google/SKILL.md

The template covers every subcommand with examples and includes the auth recovery flow, so Claude Code (or any agent) can pick up Google Workspace operations with no extra prompting. Edit it freely to fit your project's conventions.

Programmatic use

Everything is also exposed as a library:

import { GoogleAuth, GmailService } from '@iamrommel/google-cli'

const auth = new GoogleAuth()
const client = await auth.getClient()
const gmail = new GmailService(client)
await gmail.send({ to: '[email protected]', subject: 'Hi', body: 'Hello' })

Scopes requested

Authorization grants these scopes:

• gmail.modify — read, send, modify, trash (no delete)
• calendar
• tasks
• documents
• spreadsheets
• drive — full read/write
• contacts

License

MIT — see LICENSE.