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
1gws 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

Detailed Usage

list — List chat spaces

bash
1gws 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
1gws 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

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

members — List space members

bash
1gws 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

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

Flags:

• --space string — Space ID or name (required)
• --text string — Message text (required)

get — Get a single message

bash
1gws chat get <message-name>

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

update — Update a message

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

Flags:

• --text string — New message text (required)

delete — Delete a message

bash
1gws chat delete <message-name> [flags]

Flags:

• --force — Force delete even if message has replies

reactions — List reactions on a message

bash
1gws 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

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

Flags:

• --emoji string — Emoji unicode character (required)

unreact — Remove a reaction

bash
1gws chat unreact <reaction-name>

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

get-space — Get space details

bash
1gws chat get-space <space>

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

create-space — Create a space

bash
1gws 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

bash
1gws chat delete-space <space>

update-space — Update a space

bash
1gws 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.

bash
1gws 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

bash
1gws chat find-dm --user users/123

Flags:

• --user string — User resource name or email (required, e.g. users/123 or users/user@example.com)

setup-space — Create space with members

bash
1# Named space with members
2gws chat setup-space --display-name "Project Team" --members "users/111,users/222"
3
4# Direct message (no display-name needed)
5gws chat setup-space --type DIRECT_MESSAGE --members "users/111"
6
7# Group chat (no display-name needed)
8gws 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

bash
1gws chat get-member <member-name>

add-member — Add a member to a space

bash
1gws 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

bash
1gws chat remove-member <member-name>

update-member — Update member role

bash
1gws 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

bash
1gws 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

bash
1gws chat mark-read <space> [flags]

Flags:

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

thread-read-state — Get thread read state

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

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

attachment — Get attachment metadata

bash
1gws chat attachment <attachment-name>

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

upload — Upload a file

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

Flags:

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

download — Download media

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

Flags:

• --output string — Output file path (required)

events — List space events

bash
1gws 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

bash
1gws chat event <event-name>

build-cache — Build space-members cache

bash
1gws chat build-cache                    # Cache GROUP_CHAT spaces (default)
2gws chat build-cache --type all         # Cache all space types
3gws 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

bash
1gws chat find-group --members "alice@example.com,bob@example.com"
2gws 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

Output Modes

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

Common Mistakes

Recipe: Find a Group Chat by Member Names

Preferred method — use the member cache:

bash
1# 1. Build the cache (one-time, or periodically)
2gws chat build-cache
3
4# 2. Search by email
5gws chat find-group --members "alice@example.com,bob@example.com"
6
7# 3. Get recent messages from the matched space
8gws chat messages spaces/AAAApznBCFA --after "2026-02-20T00:00:00Z" --order-by "createTime DESC" --max 25

Alternative — manual search (no cache needed):

bash
1# 1. List all spaces, filter to group chats
2gws chat list --format json | jq '.spaces | map(select(.type == "GROUP_CHAT")) | .[:10]'
3
4# 2. Check members of candidate spaces
5gws 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

bash
1# 1. Resolve email to user resource name
2gws contacts resolve --email "user@example.com"
3
4# 2. Check if DM already exists
5gws chat find-dm --user users/123456
6
7# 3. If not found, create the DM
8gws chat setup-space --type DIRECT_MESSAGE --members "users/123456"
9
10# 4. Send a message
11gws 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