gws-chat

Stars7

Forks2

UpdatedJuly 9, 2026 at 05:07

Google Chat CLI operations via gws. Use when users need to list/create/manage chat spaces, read/send messages, manage members, track read state, handle attachments, or monitor space events. Triggers: google chat, gchat, chat spaces, chat messages.

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

omriariav

omriariav/workspace-cli

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

File Explorer

2 files

SKILL.md

readonly

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:

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:

Enable the Chat API in your Google Cloud project
Configure the OAuth consent screen for Chat scopes
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 user@example.com`
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 "user1@example.com,user2@example.com"`
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"`
Quote a message	`gws chat send --space <space-id> --text "Reply" --quote <message-id>`
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

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

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

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:

{
  "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:

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

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 ~/.config/gws/user-cache.json. The cache grows over time, avoiding repeat API calls.

Flags:

--max int — Maximum number of members to return (default 100)
--filter string — Filter members (e.g. member.type = "HUMAN")
--show-groups — Include Google Group memberships
--show-invited — Include invited memberships

send — Send a message

gws chat send --space <space-id> --text <message>

Flags:

--space string — Space ID or name (required)
--text string — Message text (required)
--quote string — Message resource name or ID to quote; the CLI fetches the quoted message and sends its current create/update timestamp.
--quote-type string — Quote type: reply or forward (default API behavior is reply).
--notify string — Notification behavior: none, force, or silent (default none). force and silent are rejected until Chat app authentication is supported.

get — Get a single message

gws chat get <message-name>

Retrieves a single message by its resource name (e.g. spaces/AAAA/messages/msg1).

Flags:

--resolve-senders — Same additive sender attribution as on chat messages.

update — Update a message

gws chat update <message-name> --text "New text"

Flags:

--text string — New message text (required)

delete — Delete a message

gws chat delete <message-name> [flags]

Flags:

--force — Force delete even if message has replies

reactions — List reactions on a message

gws chat reactions <message-name> [flags]

Flags:

--filter string — Filter reactions (e.g. emoji.unicode = "😀")
--page-size int — Number of reactions per page (default 25)

react — Add a reaction

gws chat react <message-name> --emoji "👍"

Flags:

--emoji string — Emoji unicode character (required)

unreact — Remove a reaction

gws chat unreact <reaction-name>

Removes a reaction by its resource name (e.g. spaces/AAAA/messages/msg1/reactions/rxn1).

get-space — Get space details

gws chat get-space <space>

Retrieves details about a Chat space including name, type, description.

create-space — Create a space

gws chat create-space --display-name "Team Chat" [flags]

Flags:

--display-name string — Space display name (required)
--type string — Space type: SPACE or GROUP_CHAT (default SPACE)
--description string — Space description

delete-space — Delete a space

gws chat delete-space <space>

update-space — Update a space

gws chat update-space <space> [flags]

Flags:

--display-name string — New display name
--description string — New description

search-spaces — Search for spaces (admin only)

Requires Workspace admin privileges and chat.admin.spaces scope. Not available with regular user OAuth.

gws chat search-spaces --query "Engineering" [flags]

Flags:

--query string — Search query (required)
--page-size int — Results per page (default 100)

find-dm — Find direct message space

gws chat find-dm --email user@example.com
gws chat find-dm --user users/123

Flags:

--user string — User resource name (e.g. users/123)
--email string — User email address (e.g. user@example.com)

setup-space — Create space with members

# Named space with members
gws chat setup-space --display-name "Project Team" --members "users/111,users/222"

# Direct message (no display-name needed)
gws chat setup-space --type DIRECT_MESSAGE --members "users/111"

# Group chat (no display-name needed)
gws chat setup-space --type GROUP_CHAT --members "users/111,users/222"

Flags:

--display-name string — Space display name (required for SPACE type, forbidden for DM/GROUP_CHAT)
--type string — Space type: SPACE, GROUP_CHAT, or DIRECT_MESSAGE (default SPACE)
--members string — Comma-separated user resource names (required for DM/GROUP_CHAT)

get-member — Get member details

gws chat get-member <member-name>

add-member — Add a member to a space

gws chat add-member <space> --user users/123 [flags]

Flags:

--user string — User resource name (required)
--role string — Member role: ROLE_MEMBER or ROLE_MANAGER (default ROLE_MEMBER)

remove-member — Remove a member

gws chat remove-member <member-name>

update-member — Update member role

gws chat update-member <member-name> --role ROLE_MANAGER

Flags:

--role string — New role: ROLE_MEMBER or ROLE_MANAGER (required)

read-state — Get space read state

gws chat read-state <space>

Returns when you last read the space. Space ID is auto-expanded to the full read state resource name.

mark-read — Mark space as read

gws chat mark-read <space> [flags]

Flags:

--time string — Read time in RFC-3339 format (defaults to now)

thread-read-state — Get thread read state

gws chat thread-read-state <thread-name>

Full resource name required (e.g. users/me/spaces/AAAA/threads/thread1/threadReadState).

unread — List unread messages

gws chat unread <space-id> [flags]

Lists messages received after the last read time. Combines read-state lookup and message filtering.

Flags:

--max int — Maximum number of unread messages (default: 25)
--mark-read — Mark space as read after listing
--resolve-senders — Same additive sender attribution as on chat messages.

attachment — Get attachment metadata

gws chat attachment <attachment-name>

Returns metadata: name, content_name, content_type, source, download_uri, thumbnail_uri.

upload — Upload a file

gws chat upload <space> --file ./report.pdf

Flags:

--file string — Path to file to upload (required)

download — Download media

gws chat download <resource-name> --output ./file.pdf

Flags:

--output string — Output file path (required)

events — List space events

gws chat events <space> --filter 'event_types:"google.workspace.chat.message.v1.created"' [flags]

Flags:

--filter string — Event type filter (required — API requires it)
--page-size int — Events per page (default 100)

event — Get event details

gws chat event <event-name>

build-cache — Build space-members cache

gws chat build-cache                    # Cache GROUP_CHAT spaces (default)
gws chat build-cache --type all         # Cache all space types
gws chat build-cache --type SPACE       # Cache only SPACE type

Iterates spaces, fetches members, resolves emails via People API, and stores a local cache at ~/.config/gws/space-members-cache.json. Progress is shown on stderr.

Flags:

--type string — Space type to cache: GROUP_CHAT (default), SPACE, DIRECT_MESSAGE, or all

find-group — Find group chats by members

gws chat find-group --members "alice@example.com,bob@example.com"
gws chat find-group --members "alice@example.com" --refresh

Searches the local space-members cache for spaces where ALL specified emails are members. Requires build-cache to be run first (or use --refresh).

Flags:

--members string — Comma-separated email addresses to search for (required)
--refresh — Rebuild cache before searching

find-space — Find spaces by display name

gws chat find-space --name "sales-skills" --refresh
gws chat find-space --name "team" --type SPACE

Searches the local space cache for spaces whose display_name contains the given query (case-insensitive substring match). DMs without a display name are skipped.

Cache scope matters. Default gws chat build-cache only caches GROUP_CHAT. To find SPACE-type rooms (most named spaces) or all types, either:

prebuild with gws chat build-cache --type SPACE (or --type all), or
pass --refresh so this command rebuilds the cache before searching.

Flags:

--name string — Display name substring to search for (case-insensitive, required)
--type string — Filter by space type: SPACE, GROUP_CHAT, or DIRECT_MESSAGE
--refresh — Rebuild cache before searching (scoped to --type if set, otherwise all types)

Output Modes

gws chat list --format json    # Structured JSON (default)
gws chat list --format yaml    # YAML format
gws chat list --format text    # Human-readable text

Common Mistakes

Mistake	Correct Usage
`--limit N` on messages	Use `--max N` — `--limit` does not exist
`find-dm --user email@example.com`	Use `users/email@example.com` format — the `--user` flag requires a resource name prefix
`setup-space --display-name "X" --type DIRECT_MESSAGE`	Omit `--display-name` for DM/GROUP_CHAT — API rejects it
`find-group` without cache	Run `gws chat build-cache` first, or use `--refresh`

Recipe: Find a Group Chat by Member Names

Preferred method — use the member cache:

# 1. Build the cache (one-time, or periodically)
gws chat build-cache

# 2. Search by email
gws chat find-group --members "alice@example.com,bob@example.com"

# 3. Get recent messages from the matched space
gws chat messages spaces/AAAApznBCFA --after "2026-02-20T00:00:00Z" --order-by "createTime DESC" --max 25

Alternative — manual search (no cache needed):

# 1. List all spaces, filter to group chats
gws chat list --format json | jq '.spaces | map(select(.type == "GROUP_CHAT")) | .[:10]'

# 2. Check members of candidate spaces
gws chat members spaces/AAAApznBCFA --format json

Key insight: DMs and group chats often have empty display_name — you must check members to identify participants.

Recipe: Create a DM via Contacts

# 1. Resolve email to user resource name
gws contacts resolve --email "user@example.com"

# 2. Check if DM already exists
gws chat find-dm --user users/123456

# 3. If not found, create the DM
gws chat setup-space --type DIRECT_MESSAGE --members "users/123456"

# 4. Send a message
gws chat send --space spaces/DMXYZ --text "Hello!"

Tips for AI Agents

Always use --format json (the default) for programmatic parsing
Use gws chat list first to get space IDs
Space IDs are in the format spaces/AAAA1234
Message names are in the format spaces/AAAA/messages/msg1
members auto-resolves display names via People API — first call may be slower, subsequent calls use cache
Use --order-by "createTime DESC" with messages to get newest first
Use --filter 'createTime > "YYYY-MM-DDT00:00:00Z"' to scope messages to a date range — more reliable than relying on default ordering
read-state auto-expands bare space IDs (e.g. AAAA → users/me/spaces/AAAA/spaceReadState)
events requires a --filter with event types — see API docs
Chat API requires additional GCP setup beyond standard OAuth — see the gws-auth skill

name	gws-chat
version	2.2.0
description	Google Chat CLI operations via gws. Use when users need to list/create/manage chat spaces, read/send messages, manage members, track read state, handle attachments, or monitor space events. Triggers: google chat, gchat, chat spaces, chat messages.
metadata	{"short-description":"Google Chat CLI operations","compatibility":"claude-code, codex-cli"}

gws-chat

More from this repository

More from this repository

Google Chat (gws chat)

Dependency Check

Authentication

Quick Command Reference

Detailed Usage

list — List chat spaces

messages — List messages in a space

recent — Recap recent messages across active spaces

members — List space members

send — Send a message

get — Get a single message

update — Update a message

delete — Delete a message

reactions — List reactions on a message

react — Add a reaction

unreact — Remove a reaction

get-space — Get space details

create-space — Create a space

delete-space — Delete a space

update-space — Update a space

search-spaces — Search for spaces (admin only)

find-dm — Find direct message space

setup-space — Create space with members

get-member — Get member details

add-member — Add a member to a space

remove-member — Remove a member

update-member — Update member role

read-state — Get space read state

mark-read — Mark space as read

thread-read-state — Get thread read state

unread — List unread messages

attachment — Get attachment metadata

upload — Upload a file

download — Download media

events — List space events

event — Get event details

build-cache — Build space-members cache

find-group — Find group chats by members

find-space — Find spaces by display name

Output Modes

Common Mistakes

Recipe: Find a Group Chat by Member Names

Recipe: Create a DM via Contacts

Tips for AI Agents

Google Chat (gws chat)

Dependency Check

Authentication

Quick Command Reference

Detailed Usage

list — List chat spaces

messages — List messages in a space

recent — Recap recent messages across active spaces

members — List space members

send — Send a message

get — Get a single message

update — Update a message

delete — Delete a message

reactions — List reactions on a message

react — Add a reaction

unreact — Remove a reaction

get-space — Get space details

create-space — Create a space

delete-space — Delete a space

update-space — Update a space

search-spaces — Search for spaces (admin only)

find-dm — Find direct message space

setup-space — Create space with members

get-member — Get member details

add-member — Add a member to a space

remove-member — Remove a member

update-member — Update member role

read-state — Get space read state

mark-read — Mark space as read

thread-read-state — Get thread read state

unread — List unread messages

attachment — Get attachment metadata

upload — Upload a file