gw

gw is a native Google Workspace CLI with direct Google API access. It is built for direct execution: less ceremony, more signal.

What it does

• Browser-based OAuth login (localhost callback)
• Calendar read access (event listing)
• Gmail read access (search + metadata fetch)
• Drive read access (search + recent + file metadata)
• Google Chat read access (spaces + messages)
• Time utilities for reliable local/UTC context
• Compatibility aliases for Workspace-style command names

Quick start

1. Create a Google Cloud Desktop OAuth client.
2. Download the OAuth client JSON.
3. Save it to ~/.config/gworkspace/credentials.json (or pass --credentials).

gw auth login
gw auth status
gw time now

auth login opens your browser, waits for OAuth callback on localhost, then stores token at ~/.config/gworkspace/token.json.

Install and run

Run from source

bun install
bun run build
node dist/index.js --help

Install globally (optional)

bun install -g .
gw --help

Help

gw --help
gw -h
gw help
gw help auth
gw auth --help

Common workflows

Morning context pull

gw time now
gw calendar list --from 2026-02-18T00:00:00Z --to 2026-02-18T23:59:59Z
gw gmail search --query "newer_than:1d" --max 20

Project document scan

gw drive search --query "name contains 'spec' and trashed = false"
gw drive get --id <fileId>

Message triage

gw gmail search --query "is:unread newer_than:7d" --max 25
gw gmail get --id <messageId>

Command surface

Auth

• gw auth login [--credentials path/to/credentials.json] [--no-open]
• gw auth status
• gw auth logout

Calendar

• gw calendar list --from <ISO> --to <ISO> [--calendarId primary] [--max 20]
• gw calendar list today [--calendarId primary] [--max 20]

Gmail

• gw gmail search --query "<gmail query>" [--max 20] [--pageToken <token>]
• gw gmail list today [--max 20]
• gw gmail get --id <messageId>

Drive

• gw drive search --query "<drive query>" [--max 20]
• gw drive recent [--max 20]
• gw drive get --id <fileId>

Time

• gw time now
• gw time date
• gw time zone

Chat

• gw chat spaces [--max 20] [--filter "spaceType = SPACE"] [--pageToken <token>]
• gw chat messages --space spaces/<spaceId> [--max 20] [--orderBy "createTime desc"] [--pageToken <token>]
• gw chat list today --space spaces/<spaceId> [--max 20]

Workspace-style aliases (compat)

gw calendar_getEvents --timeMin 2026-02-18T00:00:00Z --timeMax 2026-02-19T00:00:00Z
gw gmail_search --query "newer_than:7d" --max 20
gw drive_search --query "trashed = false" --max 20

Security notes

• OAuth tokens are stored locally, not committed by default.
• Uses Desktop OAuth credentials JSON for browser login.
• Scopes are read-only:
  • calendar.readonly
  • gmail.readonly
  • drive.readonly
  • chat.spaces.readonly
  • chat.messages.readonly
• If you rotate credentials, run gw auth logout then gw auth login.

Troubleshooting

• Credentials file not found
  • Create/download Desktop OAuth credentials and pass --credentials /path/to/credentials.json, or place it at ~/.config/gworkspace/credentials.json.
• Browser did not open
  • Run gw auth login --no-open and open the URL manually.
• Login timeout
  • Re-run login and complete consent in the browser within the timeout window.
• No token found
  • Run gw auth login first.

Docs

• docs/auth.md - OAuth browser flow, token storage, and troubleshooting.
• docs/commands.md - full command reference and examples.

Repo layout

src/
  index.ts            # tiny entrypoint
  cli.ts              # command routing
  usage.ts            # help output
  config.ts           # paths + scopes
  auth/
    index.ts          # auth commands + authorize()
    oauth.ts          # browser OAuth flow
    token.ts          # token read/write/delete
  commands/
    calendar.ts
    gmail.ts
    drive.ts
    chat.ts
    time.ts
  lib/
    args.ts           # argv parsing helpers
    io.ts             # JSON output + fail handling
    types.ts          # shared types

Development

bun run check
bun run build
node dist/index.js --help