gws

# gws

CLI for Google Workspace APIs. Binary: `gws`. Config: `~/.config/gws/`.

On Hermes, prefer the bundled native `google-workspace` skill. This shared skill exists so the same workflow remains available to agents that do not ship a first-party equivalent.

## Auth

```
gws auth setup              # one-time OAuth client setup if client_secret.json is missing
gws auth login              # OAuth browser flow
gws auth status             # check current auth
```

Env: `GOOGLE_WORKSPACE_CLI_TOKEN`, `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE`

## Drive

```
gws drive files list --params '{"q": "name contains \"report\"", "pageSize": 10}'
gws drive files get --params '{"fileId": "ID"}'
gws drive files export --params '{"fileId": "ID", "mimeType": "text/plain"}' > out.txt
gws drive files create --params '{"name": "new.txt", "mimeType": "text/plain"}' --upload file.txt
```

## Docs

```
gws docs documents get --params '{"documentId": "ID"}'
```

## Google Doc To Markdown With Comments

When the user asks to download or fetch a specific Google Doc with comments in Markdown, use the skill-local helper instead of hand-assembling the pipeline (`$SKILL_DIR` = this skill's own directory):

```
go -C "$SKILL_DIR"/tools/google_doc_markdown run . \
  --doc 'https://docs.google.com/document/d/FILE_ID/edit' \
  --output /absolute/path/doc-with-comments.md
```

Behavior:
- Accepts either a full Google Doc URL or a raw Doc ID.
- Checks `gws auth status` first and fails with an explicit setup/login instruction if auth is missing or the token lacks Drive access.
- Exports the Google Doc as HTML through `gws drive files export`.
- Removes Google comment reference markup and omits embedded base64 images that would otherwise pollute the Markdown.
- Converts the cleaned HTML to Markdown with `pandoc`.
- Fetches threaded comments through `gws drive comments list`.
- Appends a clean `## Comments` section with author, timestamps, quoted text, comment body, and replies.

Agent workflow for this task:
- Run `gws auth status` first.
- If auth is missing or invalid, stop and tell the user to run `gws auth setup` and `gws auth login`.
- Run the helper with the doc URL and an explicit output path in the current working directory unless the user asked for a different location.
- Report the saved Markdown path back to the user.

Use this helper for prompts like:
- `use gws to download this doc with comments https://docs.google.com/document/d/.../edit`
- `fetch this Google Doc with comments as markdown`

## Gmail

```
gws gmail users messages list --params '{"userId": "me", "q": "newer_than:7d", "maxResults": 10}'
gws gmail users messages get --params '{"userId": "me", "id": "MSG_ID"}'
gws gmail users messages send --params '{"userId": "me"}' --body '{"raw": "BASE64_RFC2822"}'
```

## Sheets

```
gws sheets spreadsheets get --params '{"spreadsheetId": "ID"}'
gws sheets spreadsheets.values get --params '{"spreadsheetId": "ID", "range": "Sheet1!A1:D10"}'
gws sheets spreadsheets.values update --params '{"spreadsheetId": "ID", "range": "Sheet1!A1", "valueInputOption": "USER_ENTERED"}' --body '{"values": [["a","b"]]}'
```

## Calendar

```
gws calendar events list --params '{"calendarId": "primary", "timeMin": "2026-01-01T00:00:00Z", "maxResults": 10}'
```

## Tips

- Use `gws schema <service.resource.method>` to discover params for any endpoint.
- Add `--resolve-refs` to schema for full type details.
- Confirm before sending emails or creating events.