gws-chat

What this skill does

# Google Chat (gws chat)

`gws chat` provides CLI access to Google Chat with structured JSON output.

> **Disclaimer:** `gws` is not the official Google CLI. This is an independent, open-source project not endorsed by or affiliated with Google.

## Dependency Check

**Before executing any `gws` command**, verify the CLI is installed:
```bash
gws version
```

If not found, install: `go install github.com/omriariav/workspace-cli/cmd/gws@latest`

## Authentication

Requires OAuth2 credentials. Run `gws auth status` to check.
If not authenticated: `gws auth login` (opens browser for OAuth consent).
For initial setup, see the `gws-auth` skill.

**Note:** Google Chat API requires additional setup:
1. Enable the Chat API in your Google Cloud project
2. Configure the OAuth consent screen for Chat scopes
3. For some operations, you may need a service account with domain-wide delegation

## Quick Command Reference

| Task | Command |
|------|---------|
| **Spaces** | |
| List chat spaces | `gws chat list` |
| List spaces (filtered) | `gws chat list --filter 'spaceType = "SPACE"'` |
| Get space details | `gws chat get-space <space-id>` |
| Create a space | `gws chat create-space --display-name "Team" --type SPACE` |
| Delete a space | `gws chat delete-space <space-id>` |
| Update a space | `gws chat update-space <space-id> --display-name "New Name"` |
| Search spaces (admin only) | `gws chat search-spaces --query "Engineering"` |
| Find DM with user | `gws chat find-dm --email [email protected]` |
| Create space + members | `gws chat setup-space --display-name "Team" --members "users/1,users/2"` |
| Create DM | `gws chat setup-space --type DIRECT_MESSAGE --members "users/123"` |
| Create group chat | `gws chat setup-space --type GROUP_CHAT --members "users/1,users/2"` |
| Build member cache | `gws chat build-cache` |
| Find group by members | `gws chat find-group --members "[email protected],[email protected]"` |
| Find space by name | `gws chat find-space --name "sales-skills"` |
| **Messages** | |
| Read messages | `gws chat messages <space-id>` |
| Read recent messages | `gws chat messages <space-id> --order-by "createTime DESC" --max 10` |
| Messages after a date | `gws chat messages <space-id> --after "2026-02-17T00:00:00Z"` |
| Messages in a range | `gws chat messages <space-id> --after "2026-02-17T00:00:00Z" --before "2026-02-20T00:00:00Z"` |
| Recap recent messages | `gws chat recent --since 2h` |
| Recap last 7 days | `gws chat recent --since 7d --max 1000` |
| Send a message | `gws chat send --space <space-id> --text "Hello"` |
| Get a single message | `gws chat get <message-name>` |
| Update a message | `gws chat update <message-name> --text "New text"` |
| Delete a message | `gws chat delete <message-name>` |
| **Members** | |
| List space members | `gws chat members <space-id>` |
| Get member details | `gws chat get-member <member-name>` |
| Add a member | `gws chat add-member <space-id> --user users/123` |
| Remove a member | `gws chat remove-member <member-name>` |
| Update member role | `gws chat update-member <member-name> --role ROLE_MANAGER` |
| **Reactions** | |
| List reactions | `gws chat reactions <message-name>` |
| Add a reaction | `gws chat react <message-name> --emoji "👍"` |
| Remove a reaction | `gws chat unreact <reaction-name>` |
| **Read State** | |
| Get read state | `gws chat read-state <space-id>` |
| Mark space as read | `gws chat mark-read <space-id>` |
| Get thread read state | `gws chat thread-read-state <thread-name>` |
| List unread messages | `gws chat unread <space-id>` |
| **Attachments & Media** | |
| Get attachment info | `gws chat attachment <attachment-name>` |
| Upload a file | `gws chat upload <space-id> --file ./report.pdf` |
| Download media | `gws chat download <resource-name> --output ./file.pdf` |
| **Events** | |
| List space events | `gws chat events <space-id> --filter 'event_types:"google.workspace.chat.message.v1.created"'` |
| Get event details | `gws chat event <event-name>` |

## Detailed Usage

### list — List chat spaces

```bash
gws chat list [flags]
```

Lists all Chat spaces (rooms, DMs, group chats) you have access to. Supports filtering and pagination.

**Flags:**
- `--filter string` — Filter spaces (e.g. `spaceType = "SPACE"`)
- `--page-size int` — Number of spaces per page (default 100)

### messages — List messages in a space

```bash
gws chat messages <space-id> [flags]
```

**Flags:**
- `--max int` — Maximum number of messages to return (default 25)
- `--after string` — Show messages after this time (RFC3339, e.g. `2026-02-17T00:00:00Z`)
- `--before string` — Show messages before this time (RFC3339, e.g. `2026-02-20T00:00:00Z`)
- `--filter string` — Filter messages (e.g. `createTime > "2024-01-01T00:00:00Z"`)
- `--order-by string` — Order messages (e.g. `createTime DESC`)
- `--show-deleted` — Include deleted messages in results
- `--resolve-senders` — Make extra API calls to fill missing `sender_display_name` (via space membership listing) and add a `self` boolean (via People API `people/me`). One extra Chat call per space plus one People call per invocation.

`--after` and `--before` are convenience shortcuts for `--filter`. They combine with `--filter` using AND.

### recent — Recap recent messages across active spaces

```bash
gws chat recent --since <window> [flags]
```

Recaps Chat messages across every space active within `--since`, without iterating message history for inactive spaces. Uses `spaces.list` `lastActiveTime` as the cheap prefilter, then queries `spaces.messages.list` per active space with `createTime > since` and `orderBy=createTime DESC`. Results are flattened and sorted globally by newest first. Includes both sent and received messages by default.

**Flags:**
- `--since string` — Time window: a Go duration (`2h`, `12h`, `7d`) or RFC3339 timestamp (`2026-04-30T09:00:00Z`). Default `2h`.
- `--max int` — Total message cap (default 500, `0` = all)
- `--max-per-space int` — Per-space cap (default 100, `0` = all)
- `--max-spaces int` — Active-space cap after sorting by `lastActiveTime` DESC (default `0` = all)
- `--resolve-senders` — Fill `sender_display_name` (one extra membership-list call per active space) and add `self` via People API
- `--exclude-self` — Omit messages sent by the authenticated user (best-effort self detection via People API)

**Output:**
```json
{
  "since": "2026-04-30T09:00:00Z",
  "spaces_scanned": 123,
  "active_spaces": 8,
  "count": 42,
  "messages": [
    {
      "space": "spaces/AAAA",
      "space_display_name": "Team Chat",
      "space_type": "SPACE",
      "space_last_active_time": "2026-04-30T10:58:00Z",
      "name": "spaces/AAAA/messages/msg1",
      "text": "...",
      "create_time": "2026-04-30T10:57:00Z",
      "sender": "Alice",
      "sender_resource": "users/123"
    }
  ]
}
```

**Examples:**
```bash
gws chat recent --since 2h
gws chat recent --since 12h --resolve-senders --exclude-self
gws chat recent --since 7d --max 1000 --max-per-space 200
gws chat recent --since 2026-04-30T09:00:00Z
```

Sender attribution fields:
- `sender` — existing display-name-or-resource string. Always present when the message has a sender.
- `sender_type`, `sender_resource`, `sender_display_name` — additive fields populated from the Chat message payload itself. They appear in default output whenever the API returned them, with no extra calls.
- `self` — only populated when `--resolve-senders` is set and the People API self lookup succeeds. Omitted otherwise rather than guessed.
- `--resolve-senders` only adds work for the cases the payload alone can't satisfy: filling `sender_display_name` when the API didn't include one, and adding `self`. Failures degrade gracefully — messages stay usable.

### members — List space members

```bash
gws chat members <space-id> [flags]
```

Lists all members of a Chat space with display names, emails, roles, and user types.

Display names and emails are auto-resolved via the People API and cached locally at `~/.co