---
id: swarmclawai/swarmclaw/google-workspace
version: "266f5942"
license: MIT
install: manual
updated: 2026-06-30
---

# google-workspace — Google Workspace CLI (`gws`) brings Google Workspace API automation to the command line, handling Drive files, Docs, Sheets, Gmail messages, Calendar events, and Chat spaces with structured JSON responses. Use it to read, list, and mutate Workspace resources while confirming IDs and respecting API limits.

Publisher: swarmclawai · Stars: 628 · Updated: 2026-06-30

Install (manual): `git clone https://github.com/swarmclawai/swarmclaw`

## SKILL.md

# Google Workspace CLI

Use `gws` when the task is about Google Workspace resources or Google Workspace API automation.

Prefer `gws` over generic HTTP calls when possible because it already knows the Workspace API surface and returns structured JSON by default.

## Rules

1. Start with read/list/get commands before mutating Workspace state.
2. Confirm IDs first: document IDs, spreadsheet IDs, file IDs, message IDs, calendar IDs, space IDs.
3. Do not run interactive auth flows from an agent tool call. If auth is missing, report that `gws` needs to be configured in plugin settings or via a manual terminal login.
4. Keep commands machine-readable. Prefer JSON output and parse it instead of scraping human text.
5. For large list operations, limit the scope first, then page or filter.

## Common Commands

Check installation and health:

```bash
gws doctor
```

Inspect help for a resource or method:

```bash
gws help
gws drive help
gws drive files help
```

Google Docs:

```bash
gws docs get --document-id <DOC_ID>
```

Google Drive:

```bash
gws drive files list --params '{"pageSize":10}'
gws drive files get --file-id <FILE_ID>
```

Google Sheets:

```bash
gws sheets spreadsheets get --spreadsheet-id <SPREADSHEET_ID>
```

Gmail:

```bash
gws gmail users messages list --user-id me --params '{"maxResults":10}'
gws gmail users messages get --user-id me --message-id <MESSAGE_ID>
```

Google Calendar:

```bash
gws calendar events list --calendar-id primary --params '{"maxResults":10,"singleEvents":true}'
```

Google Chat:

```bash
gws chat spaces messages list --parent spaces/<SPACE_ID>
```

## Tool Usage In SwarmClaw

When using the `google_workspace` tool:

- Put the `gws` command after the binary into `args`, for example:
  `{"args":["drive","files","list"],"params":{"pageSize":5}}`
- Use `params` for `--params`
- Use `jsonInput` for `--json`
- Use `pageAll: true` when you intentionally want all pages
- Use `dryRun: true` before risky mutations if you are unsure

## Error Handling

- If `gws` is missing: tell the user to install Google Workspace CLI.
- If auth is missing or expired: tell the user to configure the plugin settings or authenticate `gws` manually.
- If a command fails because an ID is missing: switch to a list/search command first and find the right ID.


[View on SkillFed](https://skillfed.io/swarmclawai/swarmclaw/google-workspace) · [View on GitHub](https://github.com/swarmclawai/swarmclaw)