google-workspace-cli

Files (1)

• SKILL.md

SKILL.md (first lines)

## Prerequisites

1. **gcloud CLI** (required for automated setup):

```bash
which gcloud || brew install google-cloud-sdk
```

2. **gws CLI**:

```bash
which gws || brew install googleworkspace-cli

# Or: npm install -g @googleworkspace/cli
```

## Setup

### Automated (requires gcloud CLI installed first)

```bash
gws auth setup
```

Creates a GCP project, enables APIs, configures OAuth, and logs you in.

### Manual

1. Create a project at [console.cloud.google.com](https://console.cloud.google.com)
2. Configure **OAuth consent screen** → External → Testing mode
3. **Add yourself as a test user** (required)
4. Create **OAuth credentials** → type **Desktop app** (not Web app)
5. Download client JSON to `~/.config/gws/client_secret.json`
6. Enable the APIs you need (Gmail, Drive, Calendar, etc.)
7. Login with only the scopes you need:

```bash
gws auth login -s gmail,drive,calendar,sheets
```

### Check auth status

```bash
gws auth status
```

## Common Gotchas

- **Subcommands are space-separated**, not dot-separated: `gws gmail users messages list` (NOT `users.messages`)
- OAuth client must be **Desktop app** type, not Web — otherwise `redirect_uri_mismatch`
- Must add yourself as **test user** in consent screen — otherwise "Access blocked"
- Testing mode apps limited to ~25 OAuth scopes — use `-s` to select only what you need
- If API not enabled, you get 403 with a direct link to enable it

## Usage

```bash
# Core syntax (space-separated subcommands)
gws <service> <resource> [sub-resource] <method> [flags]

# List Drive files
gws drive files list --params '{"pageSize": 5}'

# Gmail inbox
gws gmail users messages list --params '{"userId": "me", "maxResults": 10}'

# Get a specific email
gws gmail users messages get --params '{"userId": "me", "id": "MSG_ID", "format": "metadata", "metadataHeaders": ["Subject","From","Date"]}'

# Calendar agenda (helper command)
gws calendar +agenda

# Create calendar event
gws calendar +insert --summary "Meeting" --start 2026-04-05T10:00:00Z --end 2026-04-05T11:00:00Z --attendee user@example.com

# Send email
gws gmail +send --to user@example.com --subject "Hello" --body "Hi there"
gws gmail +send --to user@example.com --subject "Report" --body "<h1>Hi</h1>" --html --attach ./report.pdf
gws gmail +send --to user@example.com --subject "Draft" --body "Review this" --draft

# Upload to Drive
gws drive +upload ./file.pdf
gws drive +upload ./file.pdf --parent FOLDER_ID --name "Renamed.pdf"

# Read spreadsheet
gws sheets +read --spreadsheet SPREADSHEET_ID --range "Sheet1!A1:D10"

# Inspect any method's schema before calling it
gws schema drive.files.list

# Preview request without executing
gws drive files list --dry-run
```

## Key Flags

| Flag | Purpose |
|------|---------|
| `--params '<JSON>'` | URL/query parameters |
| `--json '<JSON>'` | Request body (POST/PATCH/PUT) |
| `--page-all` | Auto-paginate (NDJSON output) |
| `--page-limit <N>` | Max pages (default 10) |
| `--upload <PATH>` | File upload |
| `--output <PATH>` | Download binary files |
| `--dry-run` | Preview without executing |
| `--format <FMT>` | Output format: json (default), table, yaml, csv |

## Helper Commands

Prefixed with `+`, these are convenience wrappers. Run `gws <service> +cmd --help` for full options.

- **gmail:** `+send`, `+reply`, `+reply-all`, `+forward`, `+triage`, `+watch`
- **sheets:** `+append`, `+read`
- **docs:** `+write`
- **chat:** `+send`
- **drive:** `+upload`
- **calendar:** `+insert`, `+agenda`
- **workflow:** `+standup-report`, `+meeting-prep`, `+weekly-digest`

From DevChiniwala/HeyClara, MIT.

More from DevChiniwala/HeyClara