Unofficial Google Workspace CLI — manage Gmail, Calendar, Drive, Docs, Sheets, Slides, Tasks, Chat, Forms, Contacts, and Search from the terminal. Not affiliated with Google.

GitHub stars
7

Install

/plugin install gws@workspace-cli

Run it inside Claude Code after adding the marketplace with /plugin marketplace add omriariav/workspace-cli.

Contents

Discovered from source

Skills 16

Google Workspace Auth (gws auth)

gws auth manages OAuth2 authentication for all Google Workspace services.

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

Quick Command Reference

TaskCommand
Check auth statusgws auth status
Login (all scopes)gws auth login
Login (specific services)gws auth login --services gmail,calendar,chat
Login with credentialsgws auth login --client-id <id> --client-secret <secret>
Logout (revokes token)gws auth logout

Service-Account Modes (v1.43.0+)

Besides the default interactive OAuth flow, gws supports two explicit service-account modes via auth_mode (GWS_AUTH_MODE or config file). Modes are mutually exclusive and validated fail-closed with actionable errors; key material is never persisted, printed, or echoed.

ModeRequired settingsBehavior
oauth (default)noneInteractive OAuth2 + PKCE via gws auth login
service-account-dwdservice_account_key_file (GWS_SERVICE_ACCOUNT_KEY_FILE) + impersonate_user (GWS_IMPERSONATE_USER)Domain-wide delegation: the service account acts as the named Workspace user across all services
service-account-appservice_account_key_fileAdmin-approved Google Chat app credentials; limited to gws events subscriptions on individual Chat spaces — every other service command is rejected
# Domain-wide delegation (requires DWD enabled for the service account
# and the scopes authorized in the Admin console)
export GWS_AUTH_MODE=service-account-dwd
export GWS_SERVICE_ACCOUNT_KEY_FILE=~/keys/sa.json
export GWS_IMPERSONATE_USER=user@yourdomain.com
gws gmail list   # runs as the impersonated user, no login needed

# Chat app auth (events subscriptions only)
export GWS_AUTH_MODE=service-account-app
export GWS_SERVICE_ACCOUNT_KEY_FILE=~/keys/chat-app-sa.json
gws events subscriptions create --target //chat.googleapis.com/spaces/AAA ...

Notes:

  • gws auth login fails fast in service-account modes (no login needed); gws auth status reports the configured mode instead of token state.
  • Incomplete or mixed configuration is rejected: DWD without impersonate_user, app mode with impersonate_user, or OAuth mode with leftover service-account settings all produce clear errors.

First-Time Setup

If you haven't set up Google Cloud credentials yet, see the detailed setup guide: Setup Guide

Quick summary:

  1. Create a Google Cloud project
  2. Enable the required Workspace APIs
  3. Create OAuth 2.0 credentials (Desktop app type)
  4. Set credentials via environment variables or config file
  5. Run gws auth login

Detailed Usage

status — Check authentication status

gws auth status

Shows whether you're authenticated, the current user email, and token expiry info.

login — Authenticate with Google

gws auth login [flags]

Flags:

  • --client-id string — OAuth client ID (overrides env/config)
  • --client-secret string — OAuth client secret (overrides env/config)
  • --services string — Comma-separated services to authorize (e.g. gmail,calendar,chat). Omit for all scopes.

Opens a browser for Google OAuth consent. The token is stored at ~/.config/gws/token.json.

Available services: gmail, calendar, drive, docs, sheets, slides, tasks, chat, forms, contacts

Credential sources (in priority order):

  1. Command-line flags (--client-id, --client-secret)
  2. Environment variables (GWS_CLIENT_ID, GWS_CLIENT_SECRET)
  3. Config file (~/.config/gws/config.yaml)

logout — Remove stored credentials

gws auth logout

Revokes the token server-side with Google, then deletes the local token at ~/.config/gws/token.json.

Configuration

Environment Variables

export GWS_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GWS_CLIENT_SECRET="your-client-secret"

Config File (~/.config/gws/config.yaml)

client_id: "your-client-id.apps.googleusercontent.com"
client_secret: "your-client-secret"
services:
  - gmail
  - calendar
  - chat

Token Management

  • Token stored at: ~/.config/gws/token.json (atomic writes, file-locked)
  • Granted services tracked in: ~/.config/gws/granted_services.json
  • Tokens auto-refresh when expired; refresh tokens preserved across re-auth
  • Scoped login: use --services to request only needed scopes (smaller consent screen)
  • Default services can be set in config.yaml: services: [gmail, calendar, chat]
  • To add more scopes, re-run gws auth login --services gmail,calendar,chat,drive
  • Logout revokes the token server-side before deleting locally

Tips for AI Agents

  • Always check gws auth status before running any gws command to verify authentication
  • If auth fails, guide users to the setup guide at references/setup-guide.md
  • Credentials should NEVER be committed to version control or output in logs
  • The OAuth flow opens a browser — this requires a desktop environment or manual URL handling
  • Token refresh is automatic; if a command fails with auth errors, try gws auth logout then gws auth login

Google Calendar (gws calendar)

gws calendar provides CLI access to Google Calendar 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.

Quick Command Reference

Events

TaskCommand
List calendarsgws calendar list
View upcoming eventsgws calendar events
View next 14 daysgws calendar events --days 14
3-day window (yesterday–tomorrow)gws calendar events --from "2026-03-24" --days 3
Search events by textgws calendar events --query "standup"
View pending invitesgws calendar events --days 30 --pending
Filter by event typegws calendar events --event-types focusTime,outOfOffice
Get event by IDgws calendar get --id <event-id>
Create an eventgws calendar create --title "Meeting" --start "2024-02-01 14:00" --end "2024-02-01 15:00"
Quick add from textgws calendar quick-add --text "Lunch with John tomorrow at noon"
Update an eventgws calendar update <event-id> --title "New Title"
Delete an eventgws calendar delete <event-id>
RSVP to an eventgws calendar rsvp <event-id> --response accepted
List recurring instancesgws calendar instances --id <event-id>
Move event to calendargws calendar move --id <event-id> --destination <cal-id>

Calendar Management

TaskCommand
Get calendar metadatagws calendar get-calendar --id <cal-id>
Create secondary calendargws calendar create-calendar --summary "Projects"
Update calendargws calendar update-calendar --id <cal-id> --summary "New Name"
Delete secondary calendargws calendar delete-calendar --id <cal-id>
Clear all eventsgws calendar clear

Subscriptions

TaskCommand
Subscribe to calendargws calendar subscribe --id <cal-id>
Unsubscribegws calendar unsubscribe --id <cal-id>
Get subscription infogws calendar calendar-info --id <cal-id>
Update subscriptiongws calendar update-subscription --id <cal-id> --color-id 7

Access Control (ACL)

TaskCommand
List ACL rulesgws calendar acl
Share with usergws calendar share --email user@example.com --role reader
Remove accessgws calendar unshare --rule-id "user:user@example.com"
Update accessgws calendar update-acl --rule-id "user:user@example.com" --role writer

Other

TaskCommand
Query free/busygws calendar freebusy --from "2024-03-01 09:00" --to "2024-03-01 17:00"
List colorsgws calendar colors
List settingsgws calendar settings

Detailed Usage

list -- List calendars

gws calendar list

Lists all calendars you have access to, including shared calendars and subscriptions.

events -- List events

gws calendar events [flags]

Lists upcoming events from a calendar.

Flags:

  • --calendar-id string -- Calendar ID (default: "primary")
  • --days int -- Number of days to look ahead (default 7)
  • --from string -- Start date (YYYY-MM-DD or RFC3339); defaults to now. Enables fetching past events.
  • --max int -- Maximum number of events (default 50)
  • --pending -- Only show events with pending RSVP (needsAction). Tip: increase --max when using --pending over long date ranges, since --max limits the API fetch before client-side filtering.
  • --query string -- Free-text search across summary, description, location, and attendees
  • --event-types strings -- Filter by event type: default, birthday, focusTime, fromGmail, outOfOffice, workingLocation
  • --show-deleted -- Include cancelled/deleted events in results
  • --timezone string -- Timezone for response times (e.g. America/New_York)
  • --updated-min string -- Only events modified after this time (RFC3339)

Output includes (fields omitted when empty):

CategoryFields
Coreid, summary, status
Timestart, end, all_day
Detailsdescription, location, hangout_link, html_link, created, updated, color_id, visibility, transparency, event_type
Peopleorganizer (email), creator (email), response_status (your RSVP)
Attendeesattendees[] -- { email, response_status, optional, organizer, self }
Conferenceconference -- { conference_id, solution, entry_points[]: { type, uri } }
Attachmentsattachments[] -- { file_url, title, mime_type, file_id }
Recurrencerecurrence[] -- RRULE strings
Remindersreminders -- { use_default, overrides[]: { method, minutes } }

get -- Get event by ID

gws calendar get --id <event-id> [--calendar-id <cal-id>]

Returns full event details using mapEventToOutput format (same fields as events).

create -- Create an event

gws calendar create --title <title> --start <time> --end <time> [flags]

Flags:

  • --title string -- Event title (required)
  • --start string -- Start time in RFC3339 or YYYY-MM-DD HH:MM format (required)
  • --end string -- End time in RFC3339 or YYYY-MM-DD HH:MM format (required)
  • --calendar-id string -- Calendar ID (default: "primary")
  • --description string -- Event description
  • --location string -- Event location
  • --attendees strings -- Attendee email addresses
  • --add-self bool (default true) -- Add the authenticated user as an accepted attendee. Pass --add-self=false to opt out.

quick-add -- Quick add from text

gws calendar quick-add --text "Lunch with John tomorrow at noon" [--calendar-id <cal-id>]

Uses Google's natural language processing to create an event from a text string.

update -- Update an event

gws calendar update <event-id> [flags]

Updates an existing calendar event. Uses PATCH (only changed fields are sent).

Flags:

  • --title string -- New event title
  • --start string -- New start time
  • --end string -- New end time
  • --description string -- New event description
  • --location string -- New event location
  • --add-attendees strings -- Attendee emails to add
  • --calendar-id string -- Calendar ID (default: "primary")

delete -- Delete an event

gws calendar delete <event-id> [--calendar-id <cal-id>]

rsvp -- Respond to an event invitation

gws calendar rsvp <event-id> --response <status> [--message <text>] [--calendar-id <cal-id>]

Valid responses: accepted, declined, tentative. If --message is provided, notifies all attendees.

instances -- List recurring event instances

gws calendar instances --id <event-id> [--max 50] [--from <time>] [--to <time>] [--calendar-id <cal-id>]

Lists all instances of a recurring event within an optional time range.

move -- Move event to another calendar

gws calendar move --id <event-id> --destination <cal-id> [--calendar-id <cal-id>]

get-calendar -- Get calendar metadata

gws calendar get-calendar --id <cal-id>

Returns: id, summary, description, timezone, location, etag.

create-calendar -- Create a secondary calendar

gws calendar create-calendar --summary <name> [--description <text>] [--timezone <tz>]

update-calendar -- Update a calendar

gws calendar update-calendar --id <cal-id> [--summary <name>] [--description <text>] [--timezone <tz>]

delete-calendar -- Delete a secondary calendar

gws calendar delete-calendar --id <cal-id>

clear -- Clear all events from a calendar

gws calendar clear [--calendar-id <cal-id>]

subscribe -- Subscribe to a public calendar

gws calendar subscribe --id <cal-id>

unsubscribe -- Unsubscribe from a calendar

gws calendar unsubscribe --id <cal-id>

calendar-info -- Get subscription info

gws calendar calendar-info --id <cal-id>

Returns: id, summary, primary, description, timezone, color_id, background_color, foreground_color, summary_override, hidden, selected, access_role.

update-subscription -- Update subscription settings

gws calendar update-subscription --id <cal-id> [--color-id <id>] [--hidden] [--summary-override <name>]

acl -- List access control rules

gws calendar acl [--calendar-id <cal-id>]

Returns array of rules with: id, role, scope_type, scope_value.

share -- Share calendar with a user

gws calendar share --email <email> --role <role> [--calendar-id <cal-id>]

Valid roles: reader, writer, owner, freeBusyReader.

unshare -- Remove calendar access

gws calendar unshare --rule-id <rule-id> [--calendar-id <cal-id>]

update-acl -- Update access control rule

gws calendar update-acl --rule-id <rule-id> --role <role> [--calendar-id <cal-id>]

freebusy -- Query free/busy information

gws calendar freebusy --from <time> --to <time> [--calendars "primary,user@example.com"]

Returns busy periods for each requested calendar.

colors -- List available colors

gws calendar colors

Returns calendar_colors and event_colors maps with background/foreground hex values.

settings -- List user calendar settings

gws calendar settings

Returns all user calendar settings as key-value pairs.

Output Modes

gws calendar events --format json    # Structured JSON (default)
gws calendar events --format yaml    # YAML format
gws calendar events --format text    # Human-readable text

Tips for AI Agents

  • Always use --format json (the default) for programmatic parsing
  • Use gws calendar events to get event IDs, then use those IDs for update/delete/rsvp/get/move
  • Time format accepts both RFC3339 (2024-02-01T14:00:00Z) and human-friendly (2024-02-01 14:00)
  • The update command uses PATCH (not PUT), so only changed fields are sent
  • For non-primary calendars, get the calendar ID from gws calendar list first
  • Use quick-add for natural language event creation (e.g. "Meeting with Bob next Tuesday 2pm")
  • Use freebusy to check availability before creating events
  • ACL roles: freeBusyReader < reader < writer < owner
  • Default event window is 7 days; increase with --days for broader views

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:

  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 — configure it with auth_mode: service-account-dwd (see the gws-auth skill). Note: auth_mode: service-account-app (admin-approved Chat app credentials) is restricted to gws events subscriptions on individual Chat spaces; it does NOT enable normal Chat operations such as send, notify, or space management.

Quick Command Reference

TaskCommand
Spaces
List chat spacesgws chat list
List spaces (filtered)gws chat list --filter 'spaceType = "SPACE"'
Get space detailsgws chat get-space <space-id>
Create a spacegws chat create-space --display-name "Team" --type SPACE
Delete a spacegws chat delete-space <space-id>
Update a spacegws chat update-space <space-id> --display-name "New Name"
Search spaces (admin only)gws chat search-spaces --query "Engineering"
Find DM with usergws chat find-dm --email user@example.com
Create space + membersgws chat setup-space --display-name "Team" --members "users/1,users/2"
Create DMgws chat setup-space --type DIRECT_MESSAGE --members "users/123"
Create group chatgws chat setup-space --type GROUP_CHAT --members "users/1,users/2"
Build member cachegws chat build-cache
Find group by membersgws chat find-group --members "user1@example.com,user2@example.com"
Find space by namegws chat find-space --name "sales-skills"
Messages
Read messagesgws chat messages <space-id>
Read recent messagesgws chat messages <space-id> --order-by "createTime DESC" --max 10
Messages after a dategws chat messages <space-id> --after "2026-02-17T00:00:00Z"
Messages in a rangegws chat messages <space-id> --after "2026-02-17T00:00:00Z" --before "2026-02-20T00:00:00Z"
Recap recent messagesgws chat recent --since 2h
Recap last 7 daysgws chat recent --since 7d --max 1000
Send a messagegws chat send --space <space-id> --text "Hello"
Quote a messagegws chat send --space <space-id> --text "Reply" --quote <message-id>
Get a single messagegws chat get <message-name>
Update a messagegws chat update <message-name> --text "New text"
Delete a messagegws chat delete <message-name>
Members
List space membersgws chat members <space-id>
Get member detailsgws chat get-member <member-name>
Add a membergws chat add-member <space-id> --user users/123
Remove a membergws chat remove-member <member-name>
Update member rolegws chat update-member <member-name> --role ROLE_MANAGER
Reactions
List reactionsgws chat reactions <message-name>
Add a reactiongws chat react <message-name> --emoji "👍"
Remove a reactiongws chat unreact <reaction-name>
Read State
Get read stategws chat read-state <space-id>
Mark space as readgws chat mark-read <space-id>
Get thread read stategws chat thread-read-state <thread-name>
List unread messagesgws chat unread <space-id>
Attachments & Media
Get attachment infogws chat attachment <attachment-name>
Upload a filegws chat upload <space-id> --file ./report.pdf
Download mediagws chat download <resource-name> --output ./file.pdf
Events
List space eventsgws chat events <space-id> --filter 'event_types:"google.workspace.chat.message.v1.created"'
Get event detailsgws 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 require Chat app authentication for message sends, which gws does not support: the service-account-app auth mode only covers gws events subscriptions, so these values are rejected.

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]

This polls historical space events on demand. For push delivery of new events to a Pub/Sub topic (Workspace Events API subscriptions on spaces or users, including read-state), use the gws-events skill (gws events subscriptions ...).

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

MistakeCorrect Usage
--limit N on messagesUse --max N — --limit does not exist
find-dm --user email@example.comUse users/email@example.com format — the --user flag requires a resource name prefix
setup-space --display-name "X" --type DIRECT_MESSAGEOmit --display-name for DM/GROUP_CHAT — API rejects it
find-group without cacheRun 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
  • For continuous push notifications of Chat events (messages, memberships, reactions, read-state) use Workspace Events subscriptions — see the gws-events skill

Google Contacts (gws contacts)

gws contacts provides CLI access to Google Contacts via the People API 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

Minimum version required: v1.14.0 (Contacts support added in this release)

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.

Quick Command Reference

TaskCommand
List contactsgws contacts list
List more contactsgws contacts list --max 100
Search by namegws contacts search "John Doe"
Search by emailgws contacts search "john@example.com"
Get contact detailsgws contacts get <resource-name>
Create a contactgws contacts create --name "Jane Smith" --email "jane@example.com"
Update a contactgws contacts update <resource-name> --name "New Name"
Delete a contactgws contacts delete <resource-name>
Batch create contactsgws contacts batch-create --file contacts.json
Batch update contactsgws contacts batch-update --file updates.json
Batch delete contactsgws contacts batch-delete --resources people/c1 --resources people/c2
List directory peoplegws contacts directory
Search directorygws contacts directory-search --query "John"
Update contact photogws contacts photo <resource-name> --file photo.jpg
Delete contact photogws contacts delete-photo <resource-name>
Resolve multiple contactsgws contacts resolve --ids people/c1 --ids people/c2

Detailed Usage

list — List contacts

gws contacts list [flags]

Lists contacts from your Google account.

Flags:

  • --max int — Maximum number of contacts to return (default 50)

Output includes:

  • resource_name — Resource identifier (e.g., people/c1234567890)
  • name — Contact's display name
  • emails — Array of email addresses
  • phones — Array of phone numbers
  • organization — Organization info (name and title)

Examples:

gws contacts list
gws contacts list --max 100
gws contacts list --format json | jq '.contacts[] | select(.name | contains("Smith"))'

search — Search contacts

gws contacts search <query>

Searches contacts by name, email, or phone number.

Arguments:

  • query — Search string (required)

Search behavior:

  • Searches across names, email addresses, and phone numbers
  • Case-insensitive matching
  • Returns contacts that match any field

Examples:

gws contacts search "John"
gws contacts search "john@example.com"
gws contacts search "555-1234"
gws contacts search "Company Inc"

get — Get contact details

gws contacts get <resource-name>

Gets detailed information about a specific contact by resource name.

Arguments:

  • resource-name — Resource identifier (required, e.g., people/c1234567890)

Output includes:

  • resource_name — Resource identifier
  • name — Contact's display name
  • emails — Array of email addresses
  • phones — Array of phone numbers
  • organization — Organization info (name and title)

Examples:

gws contacts get people/c1234567890

Tip: Get the resource_name from list or search output:

gws contacts search "Jane" --format json | jq -r '.contacts[0].resource_name' | xargs gws contacts get

create — Create a new contact

gws contacts create --name <name> [flags]

Creates a new contact with a name, email, and/or phone number.

Flags:

  • --name string — Contact name (required)
  • --email string — Contact email address (optional)
  • --phone string — Contact phone number (optional)

Output includes:

  • status — Always "created"
  • resource_name — New contact's resource identifier
  • All contact fields

Examples:

gws contacts create --name "Jane Smith"
gws contacts create --name "John Doe" --email "john@example.com"
gws contacts create --name "Bob Wilson" --email "bob@example.com" --phone "555-1234"

delete — Delete a contact

gws contacts delete <resource-name>

Deletes a contact by resource name.

Arguments:

  • resource-name — Resource identifier (required, e.g., people/c1234567890)

Output includes:

  • status — Always "deleted"
  • resource_name — Deleted contact's resource identifier

Examples:

gws contacts delete people/c1234567890

Warning: This operation is permanent and cannot be undone. Consider confirming before deletion:

gws contacts get people/c1234567890  # Review first
gws contacts delete people/c1234567890  # Then delete

update — Update a contact

gws contacts update <resource-name> [flags]

Updates an existing contact by resource name. Specify fields to update via flags.

Arguments:

  • resource-name — Resource identifier (required, e.g., people/c1234567890)

Flags:

  • --name string — Updated contact name
  • --email string — Updated email address
  • --phone string — Updated phone number
  • --organization string — Updated organization name
  • --title string — Updated job title
  • --etag string — Etag for concurrency control (from get command)

Examples:

gws contacts update people/c1234567890 --name "Jane Doe"
gws contacts update people/c1234567890 --email "new@example.com" --phone "555-9999"
gws contacts update people/c1234567890 --organization "Acme Inc" --title "Manager"

batch-create — Batch create contacts

gws contacts batch-create --file <path>

Creates multiple contacts from a JSON file. The file should contain an array of contact objects.

Flags:

  • --file string — Path to JSON file with contacts array (required)

File format:

[
  {"names": [{"unstructuredName": "John Doe"}], "emailAddresses": [{"value": "john@example.com"}]},
  {"names": [{"unstructuredName": "Jane Smith"}], "phoneNumbers": [{"value": "555-1234"}]}
]

Examples:

gws contacts batch-create --file contacts.json

batch-update — Batch update contacts

gws contacts batch-update --file <path>

Updates multiple contacts from a JSON file. The file should contain a map of resource names to contact objects.

Flags:

  • --file string — Path to JSON file with contacts map (required)

File format:

{
  "contacts": {
    "people/c123": {"etag": "...", "names": [{"unstructuredName": "Updated Name"}]},
    "people/c456": {"etag": "...", "emailAddresses": [{"value": "new@example.com"}]}
  },
  "update_mask": "names,emailAddresses"
}

Examples:

gws contacts batch-update --file updates.json

batch-delete — Batch delete contacts

gws contacts batch-delete --resources <resource-name> [--resources <resource-name> ...]

Deletes multiple contacts by resource names.

Flags:

  • --resources string — Resource names to delete (repeatable)

Examples:

gws contacts batch-delete --resources people/c1 --resources people/c2

directory — List directory people

gws contacts directory [flags]

Lists people in the organization's directory. Requires directory.readonly scope.

Flags:

  • --max int — Maximum number of directory people to return (default 50)

Examples:

gws contacts directory
gws contacts directory --max 100

directory-search — Search directory people

gws contacts directory-search --query <query> [flags]

Searches people in the organization's directory by query.

Flags:

  • --query string — Search query (required)
  • --max int — Maximum number of results to return (default 50)

Examples:

gws contacts directory-search --query "John"
gws contacts directory-search --query "engineering" --max 100

photo — Update contact photo

gws contacts photo <resource-name> --file <path>

Updates a contact's photo from an image file (JPEG or PNG).

Arguments:

  • resource-name — Resource identifier (required)

Flags:

  • --file string — Path to image file, JPEG or PNG (required)

Examples:

gws contacts photo people/c1234567890 --file photo.jpg
gws contacts photo people/c1234567890 --file avatar.png

delete-photo — Delete contact photo

gws contacts delete-photo <resource-name>

Deletes a contact's photo by resource name.

Arguments:

  • resource-name — Resource identifier (required)

Examples:

gws contacts delete-photo people/c1234567890

resolve — Resolve multiple contacts

gws contacts resolve --ids <resource-name> [--ids <resource-name> ...]

Gets multiple contacts by their resource names in a single batch request.

Flags:

  • --ids string — Resource names to resolve (repeatable)

Examples:

gws contacts resolve --ids people/c1 --ids people/c2

Output Modes

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

Tips for AI Agents

  • Always use --format json (the default) for programmatic parsing
  • Use gws contacts list or search to get resource names, then use those with get or delete
  • Resource names have the format people/c<numeric-id> (e.g., people/c1234567890)
  • The list command paginates automatically up to the --max limit (default 50)
  • Search is more efficient than listing all contacts and filtering client-side
  • When creating contacts, --name is required, but --email and --phone are optional
  • Organization info can be set via update command (--organization, --title flags)
  • Use --quiet on any command to suppress JSON output (useful for scripted actions)
  • For bulk operations, use batch-create, batch-update, batch-delete for better efficiency
  • Use resolve to fetch multiple contacts in one request instead of multiple get calls
  • Directory commands (directory, directory-search) require Google Workspace and directory.readonly scope

Google Docs (gws docs)

gws docs provides CLI access to Google Docs 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.

Quick Command Reference

TaskCommand
Read a documentgws docs read <doc-id>
Read with formattinggws docs read <doc-id> --include-formatting
Get document infogws docs info <doc-id>
Create a documentgws docs create --title "My Doc"
Create with markdowngws docs create --title "My Doc" --text "# Heading\n\n**Bold**"
Create with plain textgws docs create --title "My Doc" --text "Plain" --content-format plaintext
Append textgws docs append <doc-id> --text "New paragraph"
Insert text at positiongws docs insert <doc-id> --text "Hello" --at 1
Find and replacegws docs replace <doc-id> --find "old" --replace "new"
Replace all contentgws docs replace-content <doc-id> --text "# New content"
Replace from filegws docs replace-content <doc-id> --file ./content.md
Delete contentgws docs delete <doc-id> --from 5 --to 10
Add a tablegws docs add-table <doc-id> --rows 3 --cols 4
Format textgws docs format <doc-id> --from 1 --to 10 --bold
Set paragraph stylegws docs set-paragraph-style <doc-id> --from 1 --to 100 --alignment CENTER
Set heading stylegws docs set-paragraph-style <doc-id> --from 1 --to 100 --style HEADING_1
Add a listgws docs add-list <doc-id> --at 1 --type bullet --items "A;B;C"
Remove listgws docs remove-list <doc-id> --from 1 --to 50
Trash documentgws docs trash <doc-id>
Permanently deletegws docs trash <doc-id> --permanent
Add a tabgws docs add-tab <doc-id> --title "Tab 2"
Delete a tabgws docs delete-tab <doc-id> --tab-id <id>
Rename a tabgws docs rename-tab <doc-id> --tab-id <id> --title "New Name"
Read specific tabgws docs read <doc-id> --tab "Tab 2"
Add an imagegws docs add-image <doc-id> --uri <url>
Insert table rowgws docs insert-table-row <doc-id> --table-start 5 --row 0 --col 0
Delete table rowgws docs delete-table-row <doc-id> --table-start 5 --row 0 --col 0
Insert table columngws docs insert-table-col <doc-id> --table-start 5 --row 0 --col 0
Delete table columngws docs delete-table-col <doc-id> --table-start 5 --row 0 --col 0
Merge table cellsgws docs merge-cells <doc-id> --table-start 5 --row 0 --col 0 --row-span 2 --col-span 2
Unmerge table cellsgws docs unmerge-cells <doc-id> --table-start 5 --row 0 --col 0 --row-span 2 --col-span 2
Pin header rowsgws docs pin-rows <doc-id> --table-start 5 --count 1
Insert page breakgws docs page-break <doc-id> --at 10
Insert section breakgws docs section-break <doc-id> --at 10
Add headergws docs add-header <doc-id>
Delete headergws docs delete-header <doc-id> <header-id>
Add footergws docs add-footer <doc-id>
Delete footergws docs delete-footer <doc-id> <footer-id>
Add named rangegws docs add-named-range <doc-id> --name "range1" --from 1 --to 10
Delete named rangegws docs delete-named-range <doc-id> --name "range1"
Add footnotegws docs add-footnote <doc-id> --at 5
Delete objectgws docs delete-object <doc-id> <object-id>
Replace imagegws docs replace-image <doc-id> --object-id <id> --uri <url>
Replace named rangegws docs replace-named-range <doc-id> --name "range1" --text "new"
Update doc marginsgws docs update-style <doc-id> --margin-top 72
Update section stylegws docs update-section-style <doc-id> --from 1 --to 100 --column-count 2
Update cell stylegws docs update-table-cell-style <doc-id> --table-start 5 --row 0 --col 0 --bg-color "#FF0000"
Update column widthgws docs update-table-col-properties <doc-id> --table-start 5 --col-index 0 --width 200
Update row heightgws docs update-table-row-style <doc-id> --table-start 5 --row 0 --min-height 50

Detailed Usage

read — Read document content

gws docs read <document-id> [flags]

Flags:

  • --include-formatting — Include formatting information and element positions

Use --include-formatting to see position indices needed for insert, delete, and add-table.

info — Get document info

gws docs info <document-id>

Gets metadata about a Google Doc (title, ID, revision info).

create — Create a new document

gws docs create --title <title> [flags]

Flags:

  • --title string — Document title (required)
  • --text string — Initial text content
  • --content-format string — Content format: markdown (default), plaintext, or richformat

Examples:

gws docs create --title "Meeting Notes"
gws docs create --title "Report" --text "# Q4 Summary\n\n**Revenue** grew 15%"
gws docs create --title "Plain" --text "No formatting" --content-format plaintext

append — Append text

gws docs append <document-id> --text <text> [flags]

Flags:

  • --text string — Text to append (required)
  • --newline — Add newline before appending (default: true)
  • --content-format string — Content format: markdown (default), plaintext, or richformat

insert — Insert text at position

gws docs insert <document-id> --text <text> [flags]

Flags:

  • --text string — Text to insert (required)
  • --at int — Position to insert at (1-based index, default: 1)
  • --content-format string — Content format: markdown (default), plaintext, or richformat

Position 1 is the start of the document content. Use gws docs read <id> --include-formatting to see element positions.

replace — Find and replace text

gws docs replace <document-id> --find <text> --replace <text> [flags]

Flags:

  • --find string — Text to find (required)
  • --replace string — Replacement text (required)
  • --match-case — Case-sensitive matching (default: true)

replace-content — Replace all document content

gws docs replace-content <document-id> --text "# New content"
gws docs replace-content <document-id> --file ./content.md

Flags:

  • --text string — Replacement text
  • --file string — Read content from file (alternative to --text)
  • --content-format string — Content format: markdown (default), plaintext, or richformat

Replaces the entire document body while preserving the doc ID, permissions, comments, and revision history. Provide exactly one of --text or --file.

delete — Delete content

gws docs delete <document-id> --from <pos> --to <pos>

Flags:

  • --from int — Start position (1-based index, required)
  • --to int — End position (1-based index, required)

Use gws docs read <id> --include-formatting to see position indices.

add-table — Add a table

gws docs add-table <document-id> [flags]

Flags:

  • --rows int — Number of rows (default: 3)
  • --cols int — Number of columns (default: 3)
  • --at int — Position to insert at (1-based index, default: 1)

format — Format text style

gws docs format <document-id> [flags]

Flags:

  • --from int — Start position (1-based index, required)
  • --to int — End position (1-based index, required)
  • --bold — Make text bold
  • --italic — Make text italic
  • --font-size int — Font size in points
  • --color string — Text color (hex, e.g., "#FF0000")
  • --font-family string — Font family (e.g., "Arial", "David Libre")

set-paragraph-style — Set paragraph style

gws docs set-paragraph-style <document-id> [flags]

Flags:

  • --from int — Start position (1-based index, required)
  • --to int — End position (1-based index, required)
  • --alignment string — Paragraph alignment: START, CENTER, END, JUSTIFIED
  • --line-spacing float — Line spacing multiplier (e.g., 1.15, 1.5, 2.0)
  • --style string — Named style: NORMAL_TEXT, TITLE, SUBTITLE, HEADING_1..HEADING_6
  • --direction string — Text direction: LEFT_TO_RIGHT or RIGHT_TO_LEFT

add-list — Add a bullet or numbered list

gws docs add-list <document-id> [flags]

Flags:

  • --at int — Position to insert at (1-based index, default: 1)
  • --type string — List type: bullet or numbered (default: bullet)
  • --items string — List items separated by semicolons (required)

remove-list — Remove list formatting

gws docs remove-list <document-id> [flags]

Flags:

  • --from int — Start position (1-based index, required)
  • --to int — End position (1-based index, required)

trash — Trash or permanently delete a document

gws docs trash <document-id> [flags]

Flags:

  • --permanent — Permanently delete instead of trashing (cannot be undone)

Content Formats

The --content-format flag controls how --text input is handled for create, append, and insert.

FormatDescription
markdown (default)Text is inserted as-is with markdown syntax preserved. Select the text in Google Docs and use "Paste from Markdown" to apply formatting.
plaintextText is inserted as-is with no markdown syntax expected.
richformat--text is parsed as a JSON array of Google Docs API Request objects, passed directly to BatchUpdate.

Markdown example:

gws docs create --title "Report" --text "# Summary\n\n- Item **one**\n- Item *two*"

Richformat example:

gws docs create --title "Styled" --text '[{"insertText":{"location":{"index":1},"text":"Hello World"}},{"updateTextStyle":{"range":{"startIndex":1,"endIndex":6},"textStyle":{"bold":true},"fields":"bold"}}]' --content-format richformat

Output Modes

gws docs read <doc-id> --format json    # Structured JSON (default)
gws docs read <doc-id> --format yaml    # YAML format
gws docs read <doc-id> --format text    # Human-readable text

Tips for AI Agents

  • Always use --format json (the default) for programmatic parsing
  • To get position indices for insert/delete/add-table, first run gws docs read <id> --include-formatting
  • Positions are 1-based (1 = start of document content)
  • append is the simplest way to add content — it adds to the end with an automatic newline
  • replace replaces ALL occurrences in the document, not just the first one
  • Document IDs can be extracted from Google Docs URLs: docs.google.com/document/d/<ID>/edit
  • For comments on a doc, use gws drive comments <doc-id>
  • Use --quiet on write operations to suppress JSON output in scripts

Google Drive (gws drive)

gws drive provides CLI access to Google Drive 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.

Quick Command Reference

Files & Folders

TaskCommand
List filesgws drive list
List files in foldergws drive list --folder <folder-id>
Search filesgws drive search "quarterly report"
Get file infogws drive info <file-id>
Download a filegws drive download <file-id>
Upload a filegws drive upload report.pdf
Create a foldergws drive create-folder --name "Project Files"
Move a filegws drive move <file-id> --to <folder-id>
Delete a filegws drive delete <file-id>
Copy a filegws drive copy <file-id>
Convert Office filegws drive convert <file-id>
Export filegws drive export --file-id <id> --mime-type application/pdf --output report.pdf
Update metadatagws drive update --file-id <id> --name "New Name"
Empty trashgws drive empty-trash
Drive infogws drive about
Recent changesgws drive changes

Permissions

TaskCommand
List permissionsgws drive permissions --file-id <id>
Share with usergws drive share --file-id <id> --type user --role writer --email user@example.com
Share with anyonegws drive share --file-id <id> --type anyone --role reader
Get permissiongws drive permission --file-id <id> --permission-id <perm-id>
Update permissiongws drive update-permission --file-id <id> --permission-id <perm-id> --role reader
Remove permissiongws drive unshare --file-id <id> --permission-id <perm-id>

Comments & Replies

TaskCommand
List commentsgws drive comments <file-id>
Get commentgws drive comment --file-id <id> --comment-id <cid>
Add commentgws drive add-comment --file-id <id> --content "Great work!"
Delete commentgws drive delete-comment --file-id <id> --comment-id <cid>
Resolve commentgws drive resolve-comment --file-id <id> --comment-id <cid>
Unresolve commentgws drive unresolve-comment --file-id <id> --comment-id <cid>
List repliesgws drive replies --file-id <id> --comment-id <cid>
Reply to commentgws drive reply --file-id <id> --comment-id <cid> --content "Thanks!"
Get replygws drive get-reply --file-id <id> --comment-id <cid> --reply-id <rid>
Delete replygws drive delete-reply --file-id <id> --comment-id <cid> --reply-id <rid>

Approvals

TaskCommand
List approvalsgws drive approvals <file-id>
Get approvalgws drive approval <file-id> <approval-id>
Start approvalgws drive start-approval --file-id <id> --reviewers reviewer@example.com
Approvegws drive approve --file-id <id> --approval-id <approval-id>
Declinegws drive decline --file-id <id> --approval-id <approval-id>
Reassign reviewersgws drive reassign-approval --file-id <id> --approval-id <approval-id> --add-reviewer reviewer@example.com
Cancel approvalgws drive cancel-approval --file-id <id> --approval-id <approval-id>
Comment on approvalgws drive comment-approval --file-id <id> --approval-id <approval-id> --message "Looks good"

Revisions

TaskCommand
List revisionsgws drive revisions --file-id <id>
Get revisiongws drive revision --file-id <id> --revision-id <rid>
Delete revisiongws drive delete-revision --file-id <id> --revision-id <rid>

Shared Drives

TaskCommand
List shared drivesgws drive shared-drives
Get shared drivegws drive shared-drive --id <drive-id>
Create shared drivegws drive create-drive --name "Engineering"
Update shared drivegws drive update-drive --id <drive-id> --name "New Name"
Delete shared drivegws drive delete-drive --id <drive-id>

Detailed Usage

list — List files

gws drive list [flags]

Flags:

  • --folder string — Folder ID to list (default: "root")
  • --max int — Maximum number of files (default 50)
  • --order string — Sort order (default: "modifiedTime desc")

Examples:

gws drive list
gws drive list --folder 1abc123xyz --max 20
gws drive list --order "name"

search — Search for files

gws drive search <query> [flags]

Flags:

  • --max int — Maximum number of results (default 50)
  • --raw — Treat query as raw V3 query syntax

Examples:

gws drive search "quarterly report"
gws drive search "budget 2024" --max 10
gws drive search "mimeType='application/pdf' and trashed=false" --raw

info — Get file info

gws drive info <file-id>

Gets detailed information about a file including name, type, size, owners, and permissions.

download — Download a file

gws drive download <file-id> [flags]

Flags:

  • --output string — Output file path (default: original filename)

Examples:

gws drive download 1abc123xyz
gws drive download 1abc123xyz --output ./local-copy.pdf

upload — Upload a file

gws drive upload <local-file> [flags]

Flags:

  • --folder string — Parent folder ID (default: root)
  • --name string — File name in Drive (default: local filename)
  • --mime-type string — MIME type (auto-detected if not specified)

create-folder — Create a new folder

gws drive create-folder --name <name> [flags]

Flags:

  • --name string — Folder name (required)
  • --parent string — Parent folder ID (default: root)

move — Move a file

gws drive move <file-id> --to <folder-id>

delete — Delete a file

gws drive delete <file-id> [flags]

By default, moves to trash. Use --permanent to permanently delete.

copy — Copy a file

gws drive copy <file-id> [flags]

Flags:

  • --name string — Name for the copy
  • --folder string — Destination folder ID

convert — Convert Office file to Google format

gws drive convert <file-id> [flags]

Converts DOCX/XLSX/PPTX to native Google Docs/Sheets/Slides. Creates a new file (does not modify the original). Target format is auto-detected from source MIME type.

Flags:

  • --name string — Name for the converted file (default: original name)
  • --folder string — Destination folder ID
  • --to string — Target format: docs, sheets, slides (auto-detected if omitted)

export — Export a Google Workspace file

gws drive export --file-id <id> --mime-type <mime> --output <path>

Exports Docs, Sheets, Slides to formats like PDF, CSV, DOCX, etc.

Flags:

  • --file-id string — File ID (required)
  • --mime-type string — Export MIME type (required, e.g. application/pdf, text/csv)
  • --output string — Output file path (required)

update — Update file metadata

gws drive update --file-id <id> [flags]

Flags:

  • --file-id string — File ID (required)
  • --name string — New file name
  • --description string — New description
  • --starred — Star or unstar the file
  • --trashed — Trash or untrash the file

empty-trash — Empty trash

gws drive empty-trash

Permanently deletes all files in the trash. Cannot be undone.

about — Drive storage and user info

gws drive about

Returns user info and storage quota (limit, usage, usage in Drive, usage in trash).

changes — List recent file changes

gws drive changes [flags]

Polling pattern: the first call (without --page-token) fetches the current start token and typically returns zero results. Save the returned new_start_page_token and pass it in subsequent calls to detect new changes.

Flags:

  • --max int — Maximum number of changes (default 100)
  • --page-token string — Page token from a previous call (auto-fetches start token if empty)

permissions — List permissions

gws drive permissions --file-id <id>

share — Share a file

gws drive share --file-id <id> --type <type> --role <role> [flags]

Flags:

  • --file-id string — File ID (required)
  • --type string — Permission type: user, group, domain, anyone (required)
  • --role string — Role: reader, commenter, writer, organizer, owner (required)
  • --email string — Email address (for user/group type)
  • --domain string — Domain (for domain type)
  • --send-notification — Send notification email (default: true)

unshare — Remove a permission

gws drive unshare --file-id <id> --permission-id <perm-id>

permission — Get permission details

gws drive permission --file-id <id> --permission-id <perm-id>

update-permission — Update a permission

gws drive update-permission --file-id <id> --permission-id <perm-id> --role <role>

comments — List comments

gws drive comments <file-id> [flags]

Flags:

  • --max int — Maximum number of comments (default 100)
  • --include-resolved — Include resolved comments
  • --include-deleted — Include deleted comments

comment — Get a single comment

gws drive comment --file-id <id> --comment-id <cid>

add-comment — Add a comment

gws drive add-comment --file-id <id> --content "comment text"
gws drive add-comment --file-id <id> --content "Fix this" --quoted-text "the text to anchor to"

Flags:

  • --file-id string — File ID (required)
  • --content string — Comment content (required)
  • --quoted-text string — Anchor comment to this quoted text in the document

delete-comment — Delete a comment

gws drive delete-comment --file-id <id> --comment-id <cid>

resolve-comment — Resolve a comment

Posts a reply with action=resolve (the documented Drive API path for state transitions). The original comment content is never modified. Pass an optional --content to attach a closing note.

gws drive resolve-comment --file-id <id> --comment-id <cid>
gws drive resolve-comment --file-id <id> --comment-id <cid> --content "fixed in #1234"

unresolve-comment — Reopen a resolved comment

Posts a reply with action=reopen. The original comment content is never modified. Pass an optional --content to attach a reopening note.

gws drive unresolve-comment --file-id <id> --comment-id <cid>
gws drive unresolve-comment --file-id <id> --comment-id <cid> --content "still broken on safari"

replies — List replies

gws drive replies --file-id <id> --comment-id <cid>

reply — Create a reply

gws drive reply --file-id <id> --comment-id <cid> --content "reply text"

get-reply — Get a reply

gws drive get-reply --file-id <id> --comment-id <cid> --reply-id <rid>

delete-reply — Delete a reply

gws drive delete-reply --file-id <id> --comment-id <cid> --reply-id <rid>

approvals — List file approvals

gws drive approvals <file-id> [flags]

Flags:

  • --max int — Maximum number of approvals (default 100)

approval — Get an approval

gws drive approval <file-id> <approval-id>

start-approval — Start an approval workflow

gws drive start-approval --file-id <id> --reviewers reviewer@example.com [flags]

Flags:

  • --file-id string — File ID (required)
  • --reviewers string — Comma-separated reviewer email addresses (required)
  • --due-time string — Approval due time (RFC3339)
  • --message string — Message to send to reviewers
  • --lock-file — Lock the file while approval is in progress

approve — Approve a file approval

gws drive approve --file-id <id> --approval-id <approval-id> [--message "Approved"]

decline — Decline a file approval

gws drive decline --file-id <id> --approval-id <approval-id> [--message "Needs changes"]

reassign-approval — Reassign approval reviewers

gws drive reassign-approval --file-id <id> --approval-id <approval-id> --add-reviewer new@example.com
gws drive reassign-approval --file-id <id> --approval-id <approval-id> --replace-reviewer old@example.com=new@example.com

Flags:

  • --add-reviewer string — Comma-separated reviewer emails to add
  • --replace-reviewer string — Comma-separated replacements in old@example.com=new@example.com form
  • --message string — Message to send to reviewers

cancel-approval — Cancel an approval

gws drive cancel-approval --file-id <id> --approval-id <approval-id> [--message "Cancelling"]

comment-approval — Comment on an approval

gws drive comment-approval --file-id <id> --approval-id <approval-id> --message "Please review"

revisions — List revisions

gws drive revisions --file-id <id>

revision — Get revision details

gws drive revision --file-id <id> --revision-id <rid>

delete-revision — Delete a revision

gws drive delete-revision --file-id <id> --revision-id <rid>

shared-drives — List shared drives

gws drive shared-drives [flags]

Flags:

  • --max int — Maximum number of drives (default 100)
  • --query string — Search query

shared-drive — Get shared drive info

gws drive shared-drive --id <drive-id>

create-drive — Create a shared drive

gws drive create-drive --name "Drive Name"

update-drive — Update a shared drive

gws drive update-drive --id <drive-id> --name "New Name"

delete-drive — Delete a shared drive

gws drive delete-drive --id <drive-id>

Output Modes

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

Change Notifications

To receive push notifications when Drive files change (baseline file and permission events on a file or shared drive, delivered to an existing Pub/Sub topic), use the Workspace Events API via the gws-events skill (gws events subscriptions create --target //drive.googleapis.com/files/FILE ...). For on-demand history, gws drive changes and gws drive activity remain the polling options.

Tips for AI Agents

  • Always use --format json (the default) for programmatic parsing
  • Use gws drive search to find files by name, then gws drive info <id> for details
  • File IDs from Google Docs/Sheets/Slides URLs can be extracted from the URL path
  • Delete moves to trash by default — use --permanent only when explicitly requested
  • When uploading, MIME type is auto-detected from the file extension
  • The comments command works on any Drive file type (Docs, Sheets, Slides, etc.)
  • Resolved comments are excluded by default; use --include-resolved to see them
  • Use gws drive about to check storage quota before large uploads
  • Use gws drive changes to monitor recent file activity
  • For sharing, use --type anyone --role reader for public access
  • For Workspace file exports, common MIME types: application/pdf, text/csv, application/vnd.openxmlformats-officedocument.wordprocessingml.document

Google Workspace Events (gws events)

gws events manages Workspace Events API subscriptions (lifecycle) and decodes Pub/Sub CloudEvent notifications.

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

Quick Command Reference

TaskCommand
List subscriptionsgws events subscriptions list --event-type <type> [--target <resource>]
Get a subscriptiongws events subscriptions get <id>
Create a subscriptiongws events subscriptions create --target <resource> --event-types <types> --topic projects/P/topics/T
Update event types / TTLgws events subscriptions update <id> --event-types <types> --ttl 86400s
Renew (extend expiration)gws events subscriptions renew <id> (--ttl 0s = maximum)
Deletegws events subscriptions delete <id>
Reactivate a suspended subscriptiongws events subscriptions reactivate <id>
Decode a Pub/Sub notification`...

Output Modes

All commands support --format json (default), --format yaml, and --format text, plus --quiet to suppress output.

Supported targets (GA only)

TargetFormatNotes
Chat space//chat.googleapis.com/spaces/SPACEuser auth, or admin-approved app auth
All the user's Chat spaces//chat.googleapis.com/spaces/-user auth only
User (Chat or Meet user events)//cloudidentity.googleapis.com/users/USERuser auth only; Chat membership + read-state, or Meet events
Drive file//drive.googleapis.com/files/FILEfile + permission events
Shared drive//drive.googleapis.com/drives/DRIVEfile + permission events
Meet space//meet.googleapis.com/spaces/SPACEMeet events

Customer-wide Chat targets (//admin.googleapis.com/customers/...) are Developer Preview and rejected.

Supported event types (GA only)

  • Chat: google.workspace.chat.{message,reaction,membership,space}.v1.* (created/updated/deleted as applicable) plus google.workspace.chat.spaceReadState.v1.updated and google.workspace.chat.threadReadState.v1.updated (user targets, user auth).
  • Drive (baseline): google.workspace.drive.file.v3.{added,moved,contentChanged,deleted,renamed,trashed,untrashed} and google.workspace.drive.permission.v3.{created,edited,deleted}.
  • Meet: google.workspace.meet.{conference,participant,recording,transcript,smartNote}.v2.*.

Excluded (Developer Preview or unsupported): Drive comment/reply/approval/ access-proposal events, Chat availability events, customer-wide Chat events, and every chat.app.all.* scope. Chat batch* events are output-only — they arrive automatically once the base event is subscribed and can be decoded, but cannot be requested at creation.

Pub/Sub topic constraint

The notification topic must already exist in the same Cloud project as the subscription and is immutable: gws validates the projects/PROJECT/topics/TOPIC format and never creates, replaces, or modifies topics. Grant the Workspace Events service publish access to the topic in Cloud Console.

Auth modes and scopes

Credentials are minted with the least-privilege documented scopes for the subscription's event classes (e.g. chat.messages.readonly for message events, drive.metadata for Drive events, meetings.space.readonly — or meetings.space.created with --meet-created-scope — for Meet).

  • OAuth (default): run gws auth login (the events service grants the subscription scopes).
  • service-account-dwd: acts as the impersonated Workspace user; same targets as OAuth.
  • service-account-app: admin-approved Chat app; individual Chat space subscriptions only. Read-state and non-Chat targets are rejected (their app-wide variants are Preview). Read/delete lifecycle ops use chat.bot; mutations mint only the granular chat.app.*.readonly scope(s) matching the subscription's event classes (derived from the existing subscription via a chat.bot Get when not passed explicitly).

See the auth skill for configuring the modes.

Renewal and payloads

Subscriptions expire. --include-resource-data payloads have shorter maximum expirations — renew explicitly:

gws events subscriptions renew SUBSCRIPTION_ID          # maximum allowed
gws events subscriptions renew SUBSCRIPTION_ID --ttl 86400s

Decoding notifications

gcloud pubsub subscriptions pull my-sub --format=json | jq '.[0].message' | gws events decode

Output fields: event_type (ce-type), subscription (ce-source — the Workspace Events subscription), target (ce-subject — the changed resource), attributes, message_id, publish_time, and the base64-decoded data payload.

Tips for AI Agents

  • The list command requires an event-type filter — a target alone is rejected locally before the API is called.
  • Always pass the topic as projects/PROJECT/topics/TOPIC and confirm it already exists; gws will not create it.
  • Prefer the default least-privilege scopes; only pass --meet-created-scope when the subscription covers Meet spaces the authenticated user created.
  • Renew before expiry: subscriptions with --include-resource-data expire sooner. renew with the default --ttl 0s requests the maximum.
  • In service-account-app mode, stick to individual Chat space targets; read-state and non-Chat targets need user credentials (OAuth or DWD).
  • Pipe raw Pub/Sub JSON straight into gws events decode — it accepts both push envelopes and bare messages and base64-decodes the payload for you.

Google Forms (gws forms)

gws forms provides CLI access to Google Forms 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.

Quick Command Reference

TaskCommand
Get form infogws forms info <form-id>
Get form details (alias)gws forms get <form-id>
Get all form responsesgws forms responses <form-id>
Get a single responsegws forms response <form-id> --response-id <id>
Create a new formgws forms create --title "My Form"
Update a formgws forms update <form-id> --title "New Title"

Detailed Usage

info — Get form info

gws forms info <form-id>

Gets metadata about a Google Form including title, description, and question structure.

get — Get form details

gws forms get <form-id>

Alias for info. Gets metadata about a Google Form including title, description, and question structure.

responses — Get all form responses

gws forms responses <form-id>

Gets all responses submitted to a form, with question titles mapped to answers.

response — Get a single form response

gws forms response <form-id> --response-id <response-id>

Gets a specific response by ID from a form.

Flags:

  • --response-id string — Response ID to retrieve (required)

create — Create a new form

gws forms create --title "Feedback Survey"
gws forms create --title "Team Poll" --description "Weekly team feedback"

Creates a new blank Google Form with a title and optional description.

Flags:

  • --title string — Form title (required)
  • --description string — Form description (optional)

update — Update a form

gws forms update <form-id> --title "New Title"
gws forms update <form-id> --description "Updated description"
gws forms update <form-id> --file batch-update.json

Updates a Google Form. For simple changes use --title or --description flags. For advanced updates (adding questions, etc.), provide a JSON file with a batchUpdate request body.

Flags:

  • --title string — New form title
  • --description string — New form description
  • --file string — Path to JSON file with batchUpdate request body

Output Modes

gws forms info <form-id> --format json    # Structured JSON (default)
gws forms info <form-id> --format yaml    # YAML format
gws forms info <form-id> --format text    # Human-readable text

Tips for AI Agents

  • Always use --format json (the default) for programmatic parsing
  • Form IDs can be extracted from Google Forms URLs: docs.google.com/forms/d/<ID>/edit
  • Use info to understand the form structure before fetching responses
  • Use create to make a new blank form, then update --file to add questions via batchUpdate
  • The get command is an alias for info — both return the same output
  • Use --quiet on any command to suppress JSON output (useful for scripted actions)

Google Gmail (gws gmail)

gws gmail provides CLI access to Gmail 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.

Quick Command Reference

TaskCommand
List recent emailsgws gmail list
List with labelsgws gmail list --include-labels
List all matchesgws gmail list --query "label:work" --all
List unread emailsgws gmail list --query "is:unread"
Search emailsgws gmail list --query "from:user@example.com"
Read a messagegws gmail read <message-id>
Extract HTML linksgws gmail links <message-id>
Read full threadgws gmail thread <thread-id>
Send an emailgws gmail send --to user@example.com --subject "Hi" --body "Hello"
List all labelsgws gmail labels
Get label detailsgws gmail label-info --id Label_1
Create a labelgws gmail create-label --name "MyLabel"
Update a labelgws gmail update-label --id Label_1 --name "NewName"
Delete a labelgws gmail delete-label --id Label_1
Add labelsgws gmail label <message-id> --add "STARRED"
Remove labelsgws gmail label <message-id> --remove "UNREAD"
Batch modify labelsgws gmail batch-modify --ids "msg1,msg2" --add-labels "STARRED"
Archive a messagegws gmail archive <message-id>
Archive a threadgws gmail archive-thread <thread-id>
Trash a messagegws gmail trash <message-id>
Untrash a messagegws gmail untrash <message-id>
Delete a messagegws gmail delete <message-id>
Batch deletegws gmail batch-delete --ids "msg1,msg2"
Trash a threadgws gmail trash-thread <thread-id>
Untrash a threadgws gmail untrash-thread <thread-id>
Delete a threadgws gmail delete-thread <thread-id>
Reply to a messagegws gmail reply <message-id> --body "Thanks!"
Reply to allgws gmail reply <message-id> --body "Got it" --all
Forward a messagegws gmail forward <message-id> --to "user@example.com"
Extract event IDgws gmail event-id <message-id>
List draftsgws gmail drafts
Get a draftgws gmail draft --id <draft-id>
Create a draftgws gmail create-draft --to user@example.com --subject "Hi" --body "Hello"
Update a draftgws gmail update-draft --id <draft-id> --body "Updated body"
Send a draftgws gmail send-draft --id <draft-id>
Delete a draftgws gmail delete-draft --id <draft-id>
Download attachmentgws gmail attachment --message-id <msg-id> --id <att-id> --output file.pdf

Detailed Usage

list — List recent messages/threads

gws gmail list [flags]

Lists recent email threads from your inbox. Each result includes:

  • thread_id — Thread ID (use with gws gmail thread)
  • message_id — Latest message ID (use with read, label, archive, trash)
  • message_count — Number of messages in the thread

Flags:

  • --max int — Maximum number of results (default 10, use --all for unlimited)
  • --all — Fetch all matching results (may take time for large result sets)
  • --query string — Gmail search query (e.g., is:unread, from:someone@example.com)
  • --include-labels — Include Gmail label IDs in the output for each thread

Examples:

gws gmail list --max 5
gws gmail list --query "is:unread"
gws gmail list --query "from:boss@company.com subject:urgent"
gws gmail list --query "after:2024/01/01 has:attachment"
gws gmail list --include-labels
gws gmail list --query "label:work" --all

thread — Read a full thread

gws gmail thread <thread-id>

Reads and displays all messages in a Gmail thread (conversation). Use the thread_id from gws gmail list output. Returns all messages with headers, body, labels, and attachments (when present) — each entry exposes filename, mime_type, size, attachment_id, and part_id.

read — Read a message

gws gmail read <message-id>

Reads and displays the content of a specific email message. Use the message_id from gws gmail list output. When the message has attachments, the response includes an attachments array. Each entry has filename, mime_type, size, attachment_id, and part_id; pass attachment_id to gws gmail attachment --id <id> to download.

ATT_ID=$(gws gmail read <msg-id> --format json | jq -r '.attachments[0].attachment_id')
gws gmail attachment --message-id <msg-id> --id "$ATT_ID" --output file.pdf

send — Send an email

gws gmail send --to <email> --subject <subject> --body <body> [flags]

Flags:

  • --to string — Recipient email address (required)
  • --subject string — Email subject (required)
  • --body string — Email body (required)
  • --cc string — CC recipients (comma-separated)
  • --bcc string — BCC recipients (comma-separated)
  • --attachment string — File path to attach (repeatable)

Examples:

gws gmail send --to user@example.com --subject "Meeting" --body "Let's meet at 3pm"
gws gmail send --to user@example.com --cc team@example.com --subject "Update" --body "Status update"
gws gmail send --to user@example.com --subject "Report" --body "See attached" --attachment /tmp/report.pdf
gws gmail send --to user@example.com --subject "Files" --body "Multiple" --attachment /tmp/a.pdf --attachment /tmp/b.png

labels — List all labels

gws gmail labels

Lists all Gmail labels in the account, including system labels (INBOX, SENT, etc.) and user-created labels.

label — Add or remove labels

gws gmail label <message-id> [flags]

Flags:

  • --add string — Label names to add (comma-separated)
  • --remove string — Label names to remove (comma-separated)

Use gws gmail labels to see available label names.

Examples:

gws gmail label 18abc123 --add "STARRED"
gws gmail label 18abc123 --add "ActionNeeded,IMPORTANT" --remove "INBOX"
gws gmail label 18abc123 --remove "UNREAD"

archive — Archive a message

gws gmail archive <message-id>

Archives a Gmail message by removing the INBOX label. The message remains accessible via search and labels.

archive-thread — Archive all messages in a thread

gws gmail archive-thread <thread-id>

Archives all messages in a Gmail thread by removing the INBOX label and marking all messages as read. Use the thread_id from gws gmail list output. More efficient than archiving individual messages for multi-message threads.

trash — Trash a message

gws gmail trash <message-id>

Moves a Gmail message to the trash. Messages in trash are permanently deleted after 30 days.

reply — Reply to a message

gws gmail reply <message-id> --body <body> [flags]

Replies to an existing email message within its thread. Automatically sets threading headers (In-Reply-To, References), thread ID, and Re: subject prefix.

Flags:

  • --body string — Reply body (required)
  • --cc string — CC recipients (comma-separated)
  • --bcc string — BCC recipients (comma-separated)
  • --all — Reply to all recipients

Examples:

gws gmail reply 18abc123 --body "Thanks, got it!"
gws gmail reply 18abc123 --body "Adding someone" --cc extra@example.com
gws gmail reply 18abc123 --body "Sounds good" --all

forward — Forward a message

gws gmail forward <message-id> --to <recipients> [flags]

Forwards an existing email message to new recipients. Preserves the original message content and attachments. Adds a "Fwd:" prefix to the subject.

Flags:

  • --to string — Recipient email addresses (comma-separated, required)
  • --body string — Optional note above the forwarded content
  • --cc string — CC recipients (comma-separated)
  • --bcc string — BCC recipients (comma-separated)

Examples:

gws gmail forward 18abc123 --to "user@example.com"
gws gmail forward 18abc123 --to "user1@example.com,user2@example.com" --body "FYI"
gws gmail forward 18abc123 --to "user@example.com" --cc "manager@example.com"

event-id — Extract calendar event ID from an invite email

gws gmail event-id <message-id>

Extracts the Google Calendar event ID from a calendar invite email by parsing the eid parameter from Google Calendar URLs in the email body and base64 decoding it.

Examples:

gws gmail event-id 19c041be3fcd1b79
gws gmail event-id 19c041be3fcd1b79 | jq -r '.event_id' | xargs -I{} gws calendar rsvp {} --response accepted

Output Modes

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

untrash — Remove a message from trash

gws gmail untrash <message-id>

Removes a Gmail message from the trash, restoring it to its previous location.

delete — Permanently delete a message

gws gmail delete <message-id>

Permanently deletes a Gmail message. This action cannot be undone.

batch-modify — Modify labels on multiple messages

gws gmail batch-modify --ids <comma-separated-ids> [flags]

Flags:

  • --ids string — Comma-separated message IDs (required)
  • --add-labels string — Label names to add (comma-separated)
  • --remove-labels string — Label names to remove (comma-separated)

Examples:

gws gmail batch-modify --ids "msg1,msg2,msg3" --add-labels "STARRED"
gws gmail batch-modify --ids "msg1,msg2" --remove-labels "INBOX,UNREAD"
gws gmail batch-modify --ids "msg1,msg2" --add-labels "ActionNeeded" --remove-labels "INBOX"

batch-delete — Permanently delete multiple messages

gws gmail batch-delete --ids <comma-separated-ids>

Flags:

  • --ids string — Comma-separated message IDs (required)

trash-thread — Move a thread to trash

gws gmail trash-thread <thread-id>

Moves all messages in a Gmail thread to the trash.

untrash-thread — Remove a thread from trash

gws gmail untrash-thread <thread-id>

Removes all messages in a Gmail thread from the trash.

delete-thread — Permanently delete a thread

gws gmail delete-thread <thread-id>

Permanently deletes all messages in a Gmail thread. This action cannot be undone.

label-info — Get label details

gws gmail label-info --id <label-id>

Flags:

  • --id string — Label ID (required)

Returns detailed information including message/thread counts and visibility settings.

create-label — Create a new label

gws gmail create-label --name <label-name> [flags]

Flags:

  • --name string — Label name (required)
  • --visibility string — Message visibility: labelShow, labelShowIfUnread, labelHide
  • --list-visibility string — Label list visibility: labelShow, labelHide

Examples:

gws gmail create-label --name "ProjectX"
gws gmail create-label --name "Archive/2024" --visibility labelHide

update-label — Update a label

gws gmail update-label --id <label-id> [flags]

Flags:

  • --id string — Label ID (required)
  • --name string — New label name
  • --visibility string — Message visibility: labelShow, labelShowIfUnread, labelHide
  • --list-visibility string — Label list visibility: labelShow, labelHide

delete-label — Delete a label

gws gmail delete-label --id <label-id>

Flags:

  • --id string — Label ID (required)

Permanently deletes a Gmail label. Messages with this label are not deleted.

drafts — List drafts

gws gmail drafts [flags]

Flags:

  • --max int — Maximum number of results (default 10)
  • --query string — Gmail search query

draft — Get a draft by ID

gws gmail draft --id <draft-id>

Flags:

  • --id string — Draft ID (required)

Returns full draft content including headers and body.

create-draft — Create a draft

gws gmail create-draft --to <email> [flags]

Flags:

  • --to string — Recipient email address (required)
  • --subject string — Email subject
  • --body string — Email body
  • --cc string — CC recipients (comma-separated)
  • --bcc string — BCC recipients (comma-separated)
  • --thread-id string — Thread ID for reply draft
  • --attachment string — File path to attach (repeatable)

Examples:

gws gmail create-draft --to user@example.com --subject "Draft" --body "Work in progress"
gws gmail create-draft --to user@example.com --subject "Re: Topic" --thread-id thread123
gws gmail create-draft --to user@example.com --subject "Draft" --body "See attached" --attachment /tmp/file.pdf

update-draft — Update a draft

gws gmail update-draft --id <draft-id> [flags]

Flags:

  • --id string — Draft ID (required)
  • --to string — Recipient email address
  • --subject string — Email subject
  • --body string — Email body
  • --cc string — CC recipients (comma-separated)
  • --bcc string — BCC recipients (comma-separated)

send-draft — Send an existing draft

gws gmail send-draft --id <draft-id>

Flags:

  • --id string — Draft ID (required)

delete-draft — Delete a draft

gws gmail delete-draft --id <draft-id>

Flags:

  • --id string — Draft ID (required)

attachment — Download an attachment

gws gmail attachment --message-id <msg-id> --id <attachment-id> --output <file-path>

Flags:

  • --message-id string — Message ID (required)
  • --id string — Attachment ID (required)
  • --output string — Output file path (required)

Discover the --id value from the attachments array on gws gmail read or gws gmail thread output. Each entry includes filename, mime_type, size, attachment_id, and part_id.

Examples:

gws gmail attachment --message-id 18abc123 --id ANGjdJ9x --output report.pdf

# End-to-end: discover the attachment ID and download it.
ATT_ID=$(gws gmail read 18abc123 --format json | jq -r '.attachments[0].attachment_id')
gws gmail attachment --message-id 18abc123 --id "$ATT_ID" --output report.pdf

links — Extract HTML anchor links from a message

gws gmail links <message-id>

Fetches the full message and extracts <a href> anchors from text/html MIME parts. Useful when a message's plain text body contains visible labels like "Notes by Gemini" or "Open meeting notes" but the underlying URL is only present in the HTML part.

Returns message_id and a links array in document order. Each entry has:

  • text — Visible anchor text
  • href — Full URL
  • mime_part — Always "text/html"
  • google_docs_id — (Google Docs only) document ID parsed from the URL path
  • query — (Google Docs only) raw query string, e.g. usp=sharing
  • fragment — (Google Docs only) URL fragment including #, e.g. #heading=h.abc
  • tab_id — (Google Docs only) tab ID from the tab query parameter, e.g. t.0

All non-empty href anchors are returned, including mailto: links. Google Docs metadata fields are only present when applicable.

Examples:

gws gmail links 18abc123 --format json

# Gemini Notes flow: find the Google Doc URL in a Gemini Notes email.
DOC_URL=$(gws gmail links 18abc123 --format json | jq -r '.links[] | select(.text == "Notes by Gemini") | .href')
DOC_ID=$(gws gmail links 18abc123 --format json | jq -r '.links[] | select(.google_docs_id) | .google_docs_id' | head -1)
gws docs read "$DOC_ID"

Tips for AI Agents

  • Always use --format json (the default) for programmatic parsing
  • Use gws gmail list to get IDs: message_id for read/label/archive/trash, thread_id for thread
  • Use gws gmail thread <thread-id> to view full conversations with all messages
  • Gmail search query syntax supports operators like is:, from:, to:, subject:, after:, before:, has:, label:
  • When managing labels, run gws gmail labels first to see available label names and IDs
  • Archive is a shortcut for gws gmail label <id> --remove "INBOX"
  • Use gws gmail archive-thread <thread-id> to archive all messages in a conversation at once (archives + marks read)
  • To mark as read: gws gmail label <id> --remove "UNREAD"
  • To star a message: gws gmail label <id> --add "STARRED"
  • Use --include-labels with list to see which Gmail labels are applied to each thread
  • Use --all with list to fetch every matching result (bypasses the default 10 limit)
  • Use --quiet on any command to suppress JSON output (useful for scripted archive/label actions)

Google Groups (gws groups)

gws groups provides CLI access to Google Groups via the Admin Directory API 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

Minimum version required: v1.18.0 (Groups support added in this release)

Prerequisites

  • Admin SDK API must be enabled in the Google Cloud project
  • Google Workspace admin privileges are required (not available for personal Gmail accounts)

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.

Quick Command Reference

TaskCommand
List groupsgws groups list
List groups in a domaingws groups list --domain example.com
List groups for a usergws groups list --user-email user@example.com
List more groupsgws groups list --max 200
List group membersgws groups members group@example.com
List group ownersgws groups members group@example.com --role OWNER

Detailed Usage

list -- List groups

gws groups list [flags]

Lists Google Groups in your domain. By default, lists all groups for the customer account.

Flags:

  • --max int -- Maximum number of groups to return (default 50)
  • --domain string -- Filter by domain
  • --user-email string -- Filter groups for a specific user

Note: --domain and --user-email are mutually exclusive. Providing both will return an error.

Output includes:

  • id -- Group ID
  • email -- Group email address
  • name -- Group display name
  • description -- Group description (if set)
  • member_count -- Number of direct members (if available)

Examples:

gws groups list
gws groups list --max 200
gws groups list --domain example.com
gws groups list --user-email alice@example.com
gws groups list --format json | jq '.groups[] | {name, email}'

members -- List group members

gws groups members <group-email> [flags]

Lists members of a Google Group by group email address.

Arguments:

  • group-email -- Group email address (required)

Flags:

  • --max int -- Maximum number of members to return (default 50)
  • --role string -- Filter by role: OWNER, MANAGER, or MEMBER

Output includes:

  • id -- Member ID
  • email -- Member email address
  • role -- Member role (OWNER, MANAGER, or MEMBER)
  • type -- Member type (e.g., USER, GROUP)
  • status -- Member status (if available)

Examples:

gws groups members engineering@example.com
gws groups members engineering@example.com --max 200
gws groups members engineering@example.com --role OWNER
gws groups members engineering@example.com --role MANAGER
gws groups members engineering@example.com --format json | jq '.members[] | select(.role == "OWNER")'

Output Modes

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

Tips for AI Agents

  • Always use --format json (the default) for programmatic parsing
  • The list command returns groups for the entire customer account by default; use --domain or --user-email to narrow results
  • --domain and --user-email cannot be used together -- pick one filter
  • Use --role on the members command to quickly find group owners or managers
  • The members command requires the exact group email address as a positional argument
  • Use --quiet on any command to suppress JSON output (useful for scripted actions)
  • This command requires Admin SDK API enabled and Workspace admin privileges -- it will not work with personal Gmail accounts
  • For bulk membership analysis, pipe output through jq to filter and aggregate results

GWS Setup

Use this workflow to inspect and configure gws and its optional context hooks. Installation is inert: no Workspace API calls or context injection occur until the user explicitly approves an --apply command.

gws is not the official Google CLI and is not endorsed by or affiliated with Google.

Safety contract

  • Begin with inspection and a preview. Do not authenticate, open a browser, or write configuration until the user approves the exact planned action.
  • Never print or copy OAuth tokens, client secrets, cached Workspace content, or existing credential files.
  • Time-only mode needs no Google authentication. Ask about authentication only if the user elects Workspace context.
  • Workspace hooks are read-only and event-driven. Never send, modify, delete, or mark data as read.
  • Do not edit, disable, or replace personal hooks. If status detects a duplicate time injector, explain it and offer a separately approved migration plan.

Inspect first

Run only read-only checks:

command -v gws
gws version
gws hooks status

If the user is considering Workspace context, also run gws auth status. Report paths, enabled providers, timezone, auth readiness, source gaps, and duplicate time injectors without including credentials or cached context.

Output formats

Use --format json for structured automation, --format yaml for readable structured output, or --format text for a concise terminal view. Hook status and health output never includes cached Workspace content in any format.

Scope and providers

Configuration precedence is: built-in defaults, user config ~/.config/gws/hooks.json, workspace config .gws/hooks.json, then GWS_HOOKS_ENABLED and GWS_HOOKS_TIMEZONE environment overrides. The user config exclusively owns the global hook gate and both provider enablement settings. Workspace config contains only allowlisted, consent-free preferences such as timezone, Workspace refresh TTL, and source settings; it cannot activate a provider, private reads, credentials, tokens, or cached content.

Ask the user to choose one or both providers:

  • time: computes current local time for every supported event; no Google auth required.
  • workspace: reads only configured Calendar, Gmail, sent-mail, Tasks, and explicit Chat sources, refreshing only on an event after its TTL expires.

Preview, then apply

Preview every mutation without --apply:

gws hooks enable --time --scope user
gws hooks enable --workspace --scope user
gws hooks enable --time --workspace --scope user
gws hooks configure --scope user --enabled=true --time=true --workspace=false
gws hooks configure --scope workspace --calendar=false --gmail=false --sent-mail=false --tasks=true --chat=false
gws hooks configure --scope workspace --timezone America/New_York --refresh-minutes 5 --calendar-lookahead-days 7 --gmail-limit 8 --sent-lookback-days 7 --sent-limit 5 --task-discovery-limit 3 --task-limit 10
gws hooks configure --scope workspace --task-list TASK_LIST_ID --chat-space spaces/SPACE_ID --chat-limit 5

Review the exact path and requested keys. Existing configuration values are deliberately not echoed; use gws hooks status to inspect the safe effective provider state and auth requirement.

Only after the user explicitly approves the exact preview, repeat that command with --apply:

gws hooks enable --time --workspace --scope user --apply
gws hooks configure --scope workspace --timezone America/New_York --refresh-minutes 5 --apply

Writes are atomic, merge-only, and mode-restricted. They never write secret material. Do not use workspace scope for hooks enable, hooks disable, or hooks configure --enabled/--time/--workspace: those consent controls are user-scope only.

Host hook approval

Applying GWS configuration makes the providers eligible, but it does not by itself activate a lifecycle hook in the host. The host must also review and approve the packaged hook entrypoints.

  • In Codex, open /hooks, inspect the gws SessionStart and UserPromptSubmit entries, and explicitly approve them when the user approves that separate host action.
  • Do not claim hooks are active until that host review/approval is complete. Without it, the GWS configuration remains inert.

Hook command reference

See the focused hook command reference for the user-facing command surface and safety constraints.

Verify, reconfigure, and disable

Run a safe health check after an approved change:

gws hooks status
gws hooks test --event UserPromptSubmit

The test reports provider state, resolved timezone, auth/source diagnostics, source availability, and refresh metadata without printing cached Workspace or message content. It does not mutate Workspace state. For reconfiguration, preview gws hooks configure and get new approval before --apply. To stop all hook fetches immediately while retaining normal gws commands and authentication:

gws hooks disable --scope user
gws hooks disable --scope user --apply

Tips for AI Agents

  • Treat an inspect or preview as read-only evidence, never as approval to apply it.
  • Time-only mode must not prompt for OAuth credentials or invoke Workspace commands.
  • When a duplicate personal time injector is detected, report it without changing the personal hook.

Google Keep (gws keep)

gws keep provides CLI access to Google Keep via the Keep API 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

Minimum version required: v1.18.0 (Keep support added in this release)

Prerequisites

  • Keep API must be enabled in the Google Cloud project
  • Google Workspace Enterprise plan is required (the Keep API is not available for personal Gmail or standard Workspace accounts)

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.

Quick Command Reference

TaskCommand
List notesgws keep list
List more notesgws keep list --max 50
Get a specific notegws keep get <note-id>
Create a notegws keep create --title "Title" --text "Content"

Detailed Usage

list -- List notes

gws keep list [flags]

Lists notes from Google Keep.

Flags:

  • --max int -- Maximum number of notes to return (default 20)

Output includes:

  • name -- Note resource name (e.g., notes/abc123)
  • title -- Note title
  • text -- Note text content (if available)
  • create_time -- Creation timestamp (if available)
  • update_time -- Last update timestamp (if available)
  • trashed -- Whether the note is trashed (only present if true)

Examples:

gws keep list
gws keep list --max 50
gws keep list --format json | jq '.notes[] | {name, title}'

get -- Get a note

gws keep get <note-id>

Gets a specific note from Google Keep by its ID.

Arguments:

  • note-id -- Note identifier (required, e.g., notes/abc123 or just abc123)

Output includes:

  • name -- Note resource name
  • title -- Note title
  • text -- Note text content (if available)
  • create_time -- Creation timestamp (if available)
  • update_time -- Last update timestamp (if available)
  • trashed -- Whether the note is trashed (only present if true)

Examples:

gws keep get notes/abc123
gws keep get abc123

Tip: The notes/ prefix is optional -- the CLI automatically prepends it if missing:

gws keep list --format json | jq -r '.notes[0].name' | xargs gws keep get

create -- Create a note

gws keep create --title <title> --text <text>

Creates a new note in Google Keep.

Flags:

  • --title string -- Note title (required)
  • --text string -- Note text content (required)

Output includes:

  • name -- New note's resource name
  • title -- Note title
  • text -- Note text content
  • create_time -- Creation timestamp
  • update_time -- Last update timestamp

Examples:

gws keep create --title "Shopping List" --text "Milk, eggs, bread"
gws keep create --title "Meeting Notes" --text "Discuss Q1 goals"
gws keep create --title "Reminder" --text "Call dentist at 3pm"

Output Modes

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

Tips for AI Agents

  • Always use --format json (the default) for programmatic parsing
  • Use gws keep list to discover note IDs, then use get for full details
  • Note IDs follow the format notes/<alphanumeric-id> (e.g., notes/abc123)
  • The get command accepts both notes/abc123 and abc123 -- the notes/ prefix is added automatically if missing
  • Both --title and --text are required when creating a note
  • The list command default is 20 notes; increase with --max if you need more
  • Use --quiet on any command to suppress JSON output (useful for scripted actions)
  • This command requires the Keep API enabled and a Google Workspace Enterprise plan -- it will not work with personal Gmail or standard Workspace accounts
  • The Keep API is read/create only via this CLI -- note updates and deletions are not currently supported

Google Search (gws search)

gws search provides CLI access to Google Programmable Search Engine (Custom Search) 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 separate API credentials beyond standard OAuth:

  1. Create a Programmable Search Engine at https://programmablesearchengine.google.com/
  2. Get an API key from Google Cloud Console
  3. Set GWS_SEARCH_ENGINE_ID and GWS_SEARCH_API_KEY environment variables, or add search_engine_id and search_api_key to your config file

Quick Command Reference

TaskCommand
Web searchgws search "query"
Limit resultsgws search "query" --max 5
Search a sitegws search "query" --site example.com
Image searchgws search "query" --type image
Paginate resultsgws search "query" --start 11
Override API keygws search "query" --api-key <key> --engine-id <id>

Detailed Usage

search — Web search

gws search <query> [flags]

Flags:

  • --max int — Maximum number of results, 1-10 (default 10)
  • --site string — Restrict search to a specific site
  • --type string — Search type: image or empty for web
  • --start int — Start index for results pagination (default 1)
  • --api-key string — API Key (overrides config)
  • --engine-id string — Search Engine ID (overrides config)

Examples:

gws search "golang best practices"
gws search "kubernetes deployment" --max 5
gws search "release notes" --site github.com
gws search "logo" --type image
gws search "query" --start 11    # Page 2 of results

Output Modes

gws search "query" --format json    # Structured JSON (default)
gws search "query" --format yaml    # YAML format
gws search "query" --format text    # Human-readable text

Tips for AI Agents

  • Always use --format json (the default) for programmatic parsing
  • This command uses Google's Custom Search API, not standard Google search — it requires a separate API key and search engine ID
  • Max 10 results per request; use --start to paginate
  • The --site flag is useful for searching within a specific domain
  • Image search (--type image) returns image URLs and metadata

Google Sheets (gws sheets)

gws sheets provides CLI access to Google Sheets with structured JSON output. This skill has 38 commands covering full spreadsheet management including batch operations, named ranges, filters, charts, and conditional formatting.

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.

Quick Command Reference

Reading Data

TaskCommand
Get spreadsheet infogws sheets info <id>
List sheetsgws sheets list <id>
Read a rangegws sheets read <id> "Sheet1!A1:D10"
Read entire sheetgws sheets read <id> "Sheet1"

Writing Data

TaskCommand
Create spreadsheetgws sheets create --title "My Sheet"
Write to cellsgws sheets write <id> "Sheet1!A1" --values "a,b,c"
Write multiple rowsgws sheets write <id> "A1" --values "a,b,c;d,e,f"
Write JSON datagws sheets write <id> "A1" --values-json '[["a","b"],["c","d"]]'
Append rowsgws sheets append <id> "Sheet1" --values "x,y,z"
Clear cellsgws sheets clear <id> "Sheet1!A1:D10"

Batch & Cross-Spreadsheet Operations

TaskCommand
Read multiple rangesgws sheets batch-read <id> --ranges "A1:B5" --ranges "Sheet2!A1:C10"
Write multiple rangesgws sheets batch-write <id> --ranges "A1:B2" --values '[[1,2],[3,4]]'
Copy sheet to anothergws sheets copy-to <id> --sheet-id 0 --destination <dest-id>

Sheet Management

TaskCommand
Add a sheetgws sheets add-sheet <id> --name "New Sheet"
Delete a sheetgws sheets delete-sheet <id> --name "Old Sheet"
Rename a sheetgws sheets rename-sheet <id> --sheet "Old" --name "New"
Duplicate a sheetgws sheets duplicate-sheet <id> --sheet "Template"

Row/Column Operations

TaskCommand
Insert rowsgws sheets insert-rows <id> --sheet "Sheet1" --at 5 --count 3
Delete rowsgws sheets delete-rows <id> --sheet "Sheet1" --from 5 --to 8
Insert columnsgws sheets insert-cols <id> --sheet "Sheet1" --at 2 --count 1
Delete columnsgws sheets delete-cols <id> --sheet "Sheet1" --from 2 --to 4

Named Ranges

TaskCommand
Add a named rangegws sheets add-named-range <id> "Sheet1!A1:D10" --name "MyRange"
List named rangesgws sheets list-named-ranges <id>
Delete a named rangegws sheets delete-named-range <id> --named-range-id "nr-123"

Filters

TaskCommand
Add a basic filtergws sheets add-filter <id> "Sheet1!A1:D10"
Clear a basic filtergws sheets clear-filter <id> --sheet "Sheet1"
Add a filter viewgws sheets add-filter-view <id> "Sheet1!A1:D10" --name "My View"

Cell Operations

TaskCommand
Merge cellsgws sheets merge <id> "Sheet1!A1:D4"
Unmerge cellsgws sheets unmerge <id> "Sheet1!A1:D4"
Sort a rangegws sheets sort <id> "A1:D10" --by B --desc
Find and replacegws sheets find-replace <id> --find "old" --replace "new"
Format cellsgws sheets format <id> "A1:D10" --bold --bg-color "#FFFF00"
Set column widthgws sheets set-column-width <id> --sheet "Sheet1" --col A --width 200
Set row heightgws sheets set-row-height <id> --sheet "Sheet1" --row 1 --height 50
Freeze panesgws sheets freeze <id> --sheet "Sheet1" --rows 1 --cols 1

Charts

TaskCommand
Add a chartgws sheets add-chart <id> --type BAR --data "Sheet1!A1:B10"
List chartsgws sheets list-charts <id>
Delete a chartgws sheets delete-chart <id> --chart-id 12345

Conditional Formatting

TaskCommand
Add a rulegws sheets add-conditional-format <id> "A1:D10" --rule ">" --value "100" --bg-color "#FFFF00"
List rulesgws sheets list-conditional-formats <id> --sheet "Sheet1"
Delete a rulegws sheets delete-conditional-format <id> --sheet "Sheet1" --index 0

Detailed Usage

info — Get spreadsheet info

gws sheets info <spreadsheet-id>

list — List sheets

gws sheets list <spreadsheet-id>

read — Read cell values

gws sheets read <spreadsheet-id> <range> [flags]

Flags:

  • --headers — Treat first row as headers for JSON output (default: true)
  • --output-format string — Output format: json or csv (default: "json")

Range format:

  • Sheet1!A1:D10 — Specific range in Sheet1
  • Sheet1!A:D — Columns A through D
  • Sheet1 — All data in Sheet1
  • A1:D10 — Range in first sheet

create — Create a spreadsheet

gws sheets create --title <title> [flags]

Flags:

  • --title string — Spreadsheet title (required)
  • --sheet-names strings — Sheet names (comma-separated, default: Sheet1)

write — Write values to cells

gws sheets write <spreadsheet-id> <range> [flags]

Flags:

  • --values string — Values (comma-separated, semicolon for rows)
  • --values-json string — Values as JSON array

Examples:

gws sheets write <id> "Sheet1!A1" --values "Hello"
gws sheets write <id> "A1:C1" --values "Name,Age,City"
gws sheets write <id> "A1:C2" --values "Name,Age,City;Alice,30,NYC"
gws sheets write <id> "A1" --values-json '[["Name","Age"],["Alice",30]]'

append — Append rows

gws sheets append <spreadsheet-id> <range> [flags]

Appends rows after the last row with data. The range identifies the table to append to.

Flags:

  • --values string — Values (comma-separated, semicolon for rows)
  • --values-json string — Values as JSON array

add-sheet / delete-sheet / rename-sheet / duplicate-sheet

gws sheets add-sheet <id> --name "New Sheet" [--rows 1000] [--cols 26]
gws sheets delete-sheet <id> --name "Sheet Name"     # or --sheet-id 123
gws sheets rename-sheet <id> --sheet "Current" --name "New Name"
gws sheets duplicate-sheet <id> --sheet "Template" [--new-name "Copy"]

insert-rows / delete-rows / insert-cols / delete-cols

gws sheets insert-rows <id> --sheet "Sheet1" --at 5 --count 3
gws sheets delete-rows <id> --sheet "Sheet1" --from 5 --to 8
gws sheets insert-cols <id> --sheet "Sheet1" --at 2 --count 1
gws sheets delete-cols <id> --sheet "Sheet1" --from 2 --to 4

Row/column indices are 0-based. For delete, --from is inclusive and --to is exclusive.

merge / unmerge

gws sheets merge <id> "Sheet1!A1:D4"
gws sheets unmerge <id> "Sheet1!A1:D4"

Unbounded ranges (A:A, 1:1) are not supported for merge/unmerge.

sort — Sort a range

gws sheets sort <id> <range> [flags]

Flags:

  • --by string — Column to sort by (e.g., "A", "B", "C") (default: "A")
  • --desc — Sort in descending order
  • --has-header — First row is a header (excluded from sort)

find-replace — Find and replace

gws sheets find-replace <id> --find <text> --replace <text> [flags]

Flags:

  • --find string — Text to find (required)
  • --replace string — Replacement text (required)
  • --sheet string — Limit to specific sheet (optional)
  • --match-case — Case-sensitive matching
  • --entire-cell — Match entire cell contents only

format — Format cells

gws sheets format <id> <range> [flags]

Flags:

  • --bold — Make text bold
  • --italic — Make text italic
  • --bg-color string — Background color (hex, e.g., "#FFFF00")
  • --color string — Text color (hex, e.g., "#FF0000")
  • --font-size int — Font size in points

set-column-width — Set column width

gws sheets set-column-width <id> --sheet <name> --col <letter> --width <pixels>

Flags:

  • --sheet string — Sheet name (required)
  • --col string — Column letter, e.g., A, B, AA (required)
  • --width int — Column width in pixels (default: 100)

set-row-height — Set row height

gws sheets set-row-height <id> --sheet <name> --row <number> --height <pixels>

Flags:

  • --sheet string — Sheet name (required)
  • --row int — Row number, 1-based (required)
  • --height int — Row height in pixels (default: 21)

freeze — Freeze rows and columns

gws sheets freeze <id> --sheet <name> --rows <n> --cols <n>

Flags:

  • --sheet string — Sheet name (required)
  • --rows int — Number of rows to freeze
  • --cols int — Number of columns to freeze

copy-to — Copy a sheet to another spreadsheet

gws sheets copy-to <spreadsheet-id> --sheet-id <id> --destination <dest-spreadsheet-id>

Flags:

  • --sheet-id int — Source sheet ID to copy (required)
  • --destination string — Destination spreadsheet ID (required)

batch-read — Read multiple ranges

gws sheets batch-read <spreadsheet-id> --ranges "A1:B5" --ranges "Sheet2!A1:C10" [flags]

Flags:

  • --ranges strings — Ranges to read (can be repeated, required)
  • --value-render string — Value render option: FORMATTED_VALUE, UNFORMATTED_VALUE, FORMULA (default: "FORMATTED_VALUE")

batch-write — Write to multiple ranges

gws sheets batch-write <spreadsheet-id> --ranges "A1:B2" --values '[[1,2],[3,4]]' [flags]

Flags:

  • --ranges strings — Target ranges (can be repeated, pairs with --values, required)
  • --values strings — JSON arrays of values (can be repeated, pairs with --ranges, required)
  • --value-input string — Value input option: RAW, USER_ENTERED (default: "USER_ENTERED")

The nth --ranges pairs with the nth --values.

add-named-range — Add a named range

gws sheets add-named-range <spreadsheet-id> <range> --name <name>

Flags:

  • --name string — Name for the named range (required)

list-named-ranges — List named ranges

gws sheets list-named-ranges <spreadsheet-id>

delete-named-range — Delete a named range

gws sheets delete-named-range <spreadsheet-id> --named-range-id <id>

Flags:

  • --named-range-id string — ID of the named range to delete (required)

Use list-named-ranges to find the IDs.

add-filter — Add a basic filter

gws sheets add-filter <spreadsheet-id> <range>

Sets a basic filter on the specified range. Only one basic filter per sheet.

clear-filter — Clear a basic filter

gws sheets clear-filter <spreadsheet-id> --sheet <name>

Flags:

  • --sheet string — Sheet name (required)

add-filter-view — Add a filter view

gws sheets add-filter-view <spreadsheet-id> <range> --name <title>

Flags:

  • --name string — Title for the filter view (required)

Filter views are saved views that don't affect other users.

add-chart — Add a chart

gws sheets add-chart <spreadsheet-id> [flags]

Flags:

  • --type string — Chart type: BAR, LINE, AREA, COLUMN, SCATTER, PIE, COMBO (required)
  • --data string — Data range, e.g., "Sheet1!A1:B10" (required)
  • --title string — Chart title
  • --sheet string — Sheet to place chart on (defaults to new sheet)

list-charts — List charts

gws sheets list-charts <spreadsheet-id>

delete-chart — Delete a chart

gws sheets delete-chart <spreadsheet-id> --chart-id <id>

Flags:

  • --chart-id int — Chart ID to delete (required). Get IDs from list-charts.

add-conditional-format — Add a conditional formatting rule

gws sheets add-conditional-format <spreadsheet-id> <range> [flags]

Flags:

  • --rule string — Condition type (required): >, <, =, !=, contains, not-contains, blank, not-blank, formula
  • --value string — Comparison value (required for most rules)
  • --bg-color string — Background color (hex, e.g., "#FFFF00")
  • --color string — Text color (hex, e.g., "#FF0000")
  • --bold — Make matching text bold
  • --italic — Make matching text italic

list-conditional-formats — List conditional formatting rules

gws sheets list-conditional-formats <spreadsheet-id> --sheet <name>

Flags:

  • --sheet string — Sheet name (required)

delete-conditional-format — Delete a conditional formatting rule

gws sheets delete-conditional-format <spreadsheet-id> --sheet <name> --index <n>

Flags:

  • --sheet string — Sheet name (required)
  • --index int — 0-based index of the rule to delete (required). Get indices from list-conditional-formats.

Output Modes

gws sheets read <id> "A1:D10" --format json    # Structured JSON (default)
gws sheets read <id> "A1:D10" --format yaml    # YAML format
gws sheets read <id> "A1:D10" --format text    # Human-readable text

Tips for AI Agents

  • Always use --format json (the default) for programmatic parsing
  • Always specify the sheet name in ranges for multi-sheet spreadsheets (e.g., Sheet1!A1:D10)
  • Use gws sheets list <id> to discover sheet names before operating on them
  • Row/column indices for insert/delete operations are 0-based
  • For delete operations, --from is inclusive and --to is exclusive
  • Use --values-json for data that might contain commas or semicolons
  • append finds the last row with data and adds below it — great for log-style data
  • read --headers (default true) uses the first row as JSON keys — disable with --headers=false for raw arrays
  • Spreadsheet IDs can be extracted from URLs: docs.google.com/spreadsheets/d/<ID>/edit
  • Unbounded ranges (A:A, 1:1) are not supported for merge/unmerge/sort
  • Use --quiet on write/append/clear operations to suppress JSON output in scripts

Google Slides (gws slides)

gws slides provides CLI access to Google Slides 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.

Quick Command Reference

TaskCommand
Get presentation infogws slides info <id>
List all slidesgws slides list <id>
Read slide contentgws slides read <id>
Read specific slidegws slides read <id> 3
Read with speaker notesgws slides read <id> --notes
Create presentationgws slides create --title "My Deck"
Add a slidegws slides add-slide <id> --title "Slide Title" --body "Content"
Add blank slidegws slides add-slide <id> --layout BLANK
Delete a slidegws slides delete-slide <id> --slide-number 3
Duplicate a slidegws slides duplicate-slide <id> --slide-number 2
Add a shapegws slides add-shape <id> --slide-number 1 --type RECTANGLE
Add an imagegws slides add-image <id> --slide-number 1 --url "https://..."
Add text to shapegws slides add-text <id> --object-id <obj-id> --text "Hello"
Add text to table cellgws slides add-text <id> --table-id <tbl-id> --row 0 --col 0 --text "Cell"
Add speaker notesgws slides add-text <id> --notes --slide-number 1 --text "Notes here"
Clear speaker notesgws slides delete-text <id> --notes --slide-number 1
Find and replacegws slides replace-text <id> --find "old" --replace "new"
Delete any elementgws slides delete-object <id> --object-id <obj-id>
Clear text from shapegws slides delete-text <id> --object-id <obj-id>
Style textgws slides update-text-style <id> --object-id <obj-id> --bold --color "#FF0000"
Move/resize elementgws slides update-transform <id> --object-id <obj-id> --x 200 --y 100
Create a tablegws slides create-table <id> --slide-number 1 --rows 3 --cols 4
Insert table rowsgws slides insert-table-rows <id> --table-id <tbl-id> --at 1 --count 2
Delete table rowgws slides delete-table-row <id> --table-id <tbl-id> --row 2
Style table cellgws slides update-table-cell <id> --table-id <tbl-id> --row 0 --col 0 --background-color "#FFFF00"
Style table bordergws slides update-table-border <id> --table-id <tbl-id> --row 0 --col 0 --color "#000000"
Paragraph stylegws slides update-paragraph-style <id> --object-id <obj-id> --alignment CENTER
Shape propertiesgws slides update-shape <id> --object-id <obj-id> --background-color "#0000FF"
Reorder slidesgws slides reorder-slides <id> --slide-ids "slide1,slide2" --to 0
Set slide background colorgws slides update-slide-background <id> --slide-number 1 --color "#005843"
Set slide background imagegws slides update-slide-background <id> --slide-number 1 --image-url "https://..."
List available layoutsgws slides list-layouts <id>
Add slide with custom layoutgws slides add-slide <id> --layout-id <layout-id>
Add a linegws slides add-line <id> --slide-number 1 --start-x 50 --start-y 50 --end-x 300 --end-y 200
Group elementsgws slides group <id> --object-ids "obj1,obj2,obj3"
Ungroup elementsgws slides ungroup <id> --group-id <group-id>
Get slide thumbnailgws slides thumbnail <id> --slide <slide-id-or-number>

Detailed Usage

info — Get presentation info

gws slides info <presentation-id> [--notes]

Flags:

  • --notes — Include speaker notes in output

list — List all slides

gws slides list <presentation-id> [--notes]

Lists all slides with their content and object IDs.

Flags:

  • --notes — Include speaker notes in output

read — Read slide content

gws slides read <presentation-id> [slide-number] [--notes]

Reads text content. Omit slide number to read all slides. Slide numbers are 1-indexed.

Flags:

  • --notes — Include speaker notes in output

create — Create a presentation

gws slides create --title <title>

add-slide — Add a slide

gws slides add-slide <presentation-id> [flags]

Flags:

  • --title string — Slide title
  • --body string — Slide body text
  • --layout string — Layout type (default: "TITLE_AND_BODY")
  • --layout-id string — Custom layout ID from presentation's masters (overrides --layout)

Available predefined layouts: TITLE_AND_BODY, TITLE_ONLY, BLANK, SECTION_HEADER, TITLE, ONE_COLUMN_TEXT, MAIN_POINT, BIG_NUMBER

For custom layouts, use gws slides list-layouts <id> to discover layout IDs.

delete-slide — Delete a slide

gws slides delete-slide <presentation-id> [flags]

Flags:

  • --slide-number int — Slide number (1-indexed)
  • --slide-id string — Slide object ID (alternative)

duplicate-slide — Duplicate a slide

gws slides duplicate-slide <presentation-id> [flags]

Flags:

  • --slide-number int — Slide number (1-indexed)
  • --slide-id string — Slide object ID (alternative)

add-shape — Add a shape

gws slides add-shape <presentation-id> [flags]

Flags:

  • --slide-number int — Slide number (1-indexed)
  • --slide-id string — Slide object ID
  • --type string — Shape type (default: "RECTANGLE")
  • --x float — X position in points (default: 100)
  • --y float — Y position in points (default: 100)
  • --width float — Width in points (default: 200)
  • --height float — Height in points (default: 100)

Shape types: RECTANGLE, ELLIPSE, TEXT_BOX, ROUND_RECTANGLE, TRIANGLE, ARROW, etc.

add-image — Add an image

gws slides add-image <presentation-id> --url <image-url> [flags]

Flags:

  • --url string — Image URL (required, must be publicly accessible)
  • --slide-number int — Slide number (1-indexed)
  • --slide-id string — Slide object ID
  • --x float — X position in points (default: 100)
  • --y float — Y position in points (default: 100)
  • --width float — Width in points (default: 400)
  • --height float — Height in points (default: auto-calculated from image aspect ratio)

add-text — Add text to shape, table cell, or speaker notes

# For shapes/text boxes:
gws slides add-text <presentation-id> --object-id <id> --text <text> [flags]

# For table cells:
gws slides add-text <presentation-id> --table-id <id> --row <n> --col <n> --text <text> [flags]

# For speaker notes:
gws slides add-text <presentation-id> --notes --slide-number <n> --text <text> [flags]

Flags:

  • --object-id string — Shape/text box ID (mutually exclusive with --table-id and --notes)
  • --table-id string — Table object ID (requires --row and --col)
  • --row int — Row index, 0-based (required with --table-id)
  • --col int — Column index, 0-based (required with --table-id)
  • --notes — Target speaker notes shape (mutually exclusive with --object-id and --table-id)
  • --slide-id string — Slide object ID (required with --notes)
  • --slide-number int — Slide number, 1-indexed (required with --notes)
  • --text string — Text to insert (required)
  • --at int — Position to insert at (0 = beginning)

Get object IDs from gws slides list <id> output. For tables, find elements with "type": "TABLE" and use their objectId as the --table-id value.

replace-text — Find and replace text

gws slides replace-text <presentation-id> --find <text> --replace <text> [flags]

Flags:

  • --find string — Text to find (required)
  • --replace string — Replacement text (required)
  • --match-case — Case-sensitive matching (default: true)

Replaces across ALL slides in the presentation.

delete-object — Delete any page element

gws slides delete-object <presentation-id> --object-id <id>

Deletes shapes, images, tables, or any page element by object ID.

delete-text — Clear text from shape or speaker notes

gws slides delete-text <presentation-id> --object-id <id> [flags]
gws slides delete-text <presentation-id> --notes --slide-number <n> [flags]

Flags:

  • --object-id string — Shape containing text (required unless --notes)
  • --notes — Target speaker notes shape (alternative to --object-id)
  • --slide-id string — Slide object ID (required with --notes)
  • --slide-number int — Slide number, 1-indexed (required with --notes)
  • --from int — Start index (default: 0)
  • --to int — End index (if omitted, deletes to end)

update-text-style — Style text formatting

gws slides update-text-style <presentation-id> --object-id <id> [flags]

Flags:

  • --object-id string — Shape containing text (required)
  • --from int / --to int — Text range (optional)
  • --bold / --italic / --underline — Boolean styles
  • --font-size float — Size in points
  • --font-family string — Font name
  • --color string — Hex color #RRGGBB

update-transform — Move, scale, or rotate elements

gws slides update-transform <presentation-id> --object-id <id> [flags]

Flags:

  • --object-id string — Element to transform (required)
  • --x / --y float — Position in points
  • --scale-x / --scale-y float — Scale factors
  • --rotate float — Rotation in degrees

create-table — Add a table

gws slides create-table <presentation-id> --rows <n> --cols <n> [flags]

Flags:

  • --slide-number int or --slide-id string — Target slide
  • --rows int — Number of rows (required)
  • --cols int — Number of columns (required)
  • --x / --y / --width / --height float — Position and size

insert-table-rows — Insert rows into table

gws slides insert-table-rows <presentation-id> --table-id <id> --at <row> [flags]

Flags:

  • --table-id string — Table object ID (required)
  • --at int — Row index to insert at (required)
  • --count int — Number of rows (default: 1)
  • --below — Insert below the index (default: true)

delete-table-row — Remove row from table

gws slides delete-table-row <presentation-id> --table-id <id> --row <index>

update-table-cell — Style table cell

gws slides update-table-cell <presentation-id> --table-id <id> --row <r> --col <c> [flags]

Flags:

  • --table-id string — Table object ID (required)
  • --row int / --col int — Cell location (required)
  • --background-color string — Hex color #RRGGBB

update-table-border — Style table borders

gws slides update-table-border <presentation-id> --table-id <id> --row <r> --col <c> [flags]

Flags:

  • --table-id string — Table object ID (required)
  • --row int / --col int — Cell location (required)
  • --border string — top, bottom, left, right, or all
  • --color string — Hex color #RRGGBB
  • --width float — Border width in points
  • --style string — solid, dashed, or dotted

update-paragraph-style — Paragraph formatting

gws slides update-paragraph-style <presentation-id> --object-id <id> [flags]

Flags:

  • --object-id string — Shape containing text (required)
  • --from int / --to int — Text range (optional)
  • --alignment string — START, CENTER, END, JUSTIFIED
  • --line-spacing float — Line spacing percentage (100 = single)
  • --space-above / --space-below float — Paragraph spacing in points

update-shape — Shape properties

gws slides update-shape <presentation-id> --object-id <id> [flags]

Flags:

  • --object-id string — Shape to update (required)
  • --background-color string — Fill color #RRGGBB
  • --outline-color string — Outline color #RRGGBB
  • --outline-width float — Outline width in points

reorder-slides — Change slide order

gws slides reorder-slides <presentation-id> --slide-ids <ids> --to <position>

Flags:

  • --slide-ids string — Comma-separated slide IDs to move (required)
  • --to int — Target position, 0-indexed (required)

update-slide-background — Set slide background

gws slides update-slide-background <presentation-id> [flags]

Sets the background of a slide to a solid color or an image URL.

Flags:

  • --slide-number int — Slide number (1-indexed)
  • --slide-id string — Slide object ID
  • --color string — Background color as hex #RRGGBB
  • --image-url string — Background image URL

One of --color or --image-url is required (mutually exclusive).

list-layouts — List available slide layouts

gws slides list-layouts <presentation-id>

Lists all available slide layouts from the presentation's masters. Use the returned layout IDs with add-slide --layout-id.

add-slide with custom layout

The add-slide command also supports --layout-id for custom master layouts:

gws slides add-slide <presentation-id> --layout-id <layout-object-id>

Use list-layouts to discover available layout IDs.

add-line — Add a line or connector

gws slides add-line <presentation-id> [flags]

Flags:

  • --slide-number int — Slide number (1-indexed)
  • --slide-id string — Slide object ID
  • --type string — Line category: STRAIGHT, BENT, or CURVED (default: "STRAIGHT")
  • --start-x float — Start X position in points
  • --start-y float — Start Y position in points
  • --end-x float — End X position in points (default: 200)
  • --end-y float — End Y position in points (default: 200)
  • --color string — Line color as hex #RRGGBB
  • --weight float — Line thickness in points (default: 1)

Supported line values: STRAIGHT, BENT, and CURVED. Values are trimmed and normalized to uppercase. Any other value is rejected rather than falling back to STRAIGHT.

group — Group elements together

gws slides group <presentation-id> --object-ids <ids>

Flags:

  • --object-ids string — Comma-separated element IDs to group (required, minimum 2; whitespace is trimmed and blank entries are rejected)

ungroup — Ungroup elements

gws slides ungroup <presentation-id> --group-id <id>

Flags:

  • --group-id string — Object ID of the group to ungroup (required; must not be blank or whitespace only)

thumbnail — Get slide page thumbnail

gws slides thumbnail <presentation-id> --slide <slide-id-or-number> [flags]

Gets a thumbnail image URL for a specific slide page.

Flags:

  • --slide string — Slide object ID or 1-based slide number (required)
  • --size string — Thumbnail size: SMALL, MEDIUM, LARGE (default: "MEDIUM")
  • --download string — Download thumbnail to file path instead of returning URL

Output Modes

gws slides list <id> --format json    # Structured JSON (default)
gws slides list <id> --format yaml    # YAML format
gws slides list <id> --format text    # Human-readable text

Tips for AI Agents

General

  • Always use --format json (the default) for programmatic parsing
  • Use gws slides list <id> to get slide object IDs and element object IDs before using update commands
  • Slide numbers are 1-indexed (first slide is 1, not 0)
  • Positions and sizes are in points (PT): standard slide is 720x405 points
  • Presentation IDs can be extracted from URLs: docs.google.com/presentation/d/<ID>/edit
  • For comments on a presentation, use gws drive comments <presentation-id>
  • Use --quiet on update operations to suppress JSON output in scripts

Styling

  • Colors are always hex format with # prefix: --background-color "#005843", --color "#FFFFFF"
  • To style text: first add-text, then update-text-style for font/color, then update-paragraph-style for alignment
  • update-shape sets fill and outline colors on shapes, not text
  • update-text-style sets font properties (bold, italic, size, color) on text within shapes

Gotchas & Workarounds

  • add-slide --layout may fail on presentations with custom slide masters; use list-layouts to get layout IDs and add-slide --layout-id instead
  • replace-text operates across ALL slides in the presentation — cannot target specific slides
  • Image URLs must be publicly accessible — Google Slides fetches them server-side
  • add-text inserts into shapes/text boxes or table cells; use add-shape --type TEXT_BOX to create a text container first
  • When creating a styled slide from scratch, work in this order: (1) add shape, (2) style shape with update-shape, (3) add text, (4) style text with update-text-style, (5) align with update-paragraph-style

Common Workflows

Create a Colored Title Slide

# 1. Add a full-slide rectangle as background
gws slides add-shape "<PRES_ID>" --slide-number 1 --type RECTANGLE \
  --x 0 --y 0 --width 720 --height 405

# 2. Get the shape ID from the output, then set fill color
gws slides update-shape "<PRES_ID>" --object-id "<SHAPE_ID>" \
  --background-color "#005843"

# 3. Add title text to the shape
gws slides add-text "<PRES_ID>" --object-id "<SHAPE_ID>" \
  --text "Thank You"

# 4. Style text: white, large, bold
gws slides update-text-style "<PRES_ID>" --object-id "<SHAPE_ID>" \
  --color "#FFFFFF" --font-size 48 --bold

# 5. Center the text
gws slides update-paragraph-style "<PRES_ID>" --object-id "<SHAPE_ID>" \
  --alignment CENTER

Populate a Table with Data

# 1. List slide to find table ID
gws slides list "<PRES_ID>" | jq '.slides[0].elements[] | select(.type=="TABLE")'

# 2. Add text to cells (0-indexed rows and columns)
gws slides add-text "<PRES_ID>" --table-id "<TABLE_ID>" --row 0 --col 0 --text "Header 1"
gws slides add-text "<PRES_ID>" --table-id "<TABLE_ID>" --row 0 --col 1 --text "Header 2"
gws slides add-text "<PRES_ID>" --table-id "<TABLE_ID>" --row 1 --col 0 --text "Data A"
gws slides add-text "<PRES_ID>" --table-id "<TABLE_ID>" --row 1 --col 1 --text "Data B"

# 3. Style header row with background color
gws slides update-table-cell "<PRES_ID>" --table-id "<TABLE_ID>" \
  --row 0 --col 0 --background-color "#005843"
gws slides update-table-cell "<PRES_ID>" --table-id "<TABLE_ID>" \
  --row 0 --col 1 --background-color "#005843"

Template Variable Replacement

# Replace placeholders across all slides
gws slides replace-text "<PRES_ID>" --find "{{COMPANY_NAME}}" --replace "Acme Corp"
gws slides replace-text "<PRES_ID>" --find "{{DATE}}" --replace "February 2026"
gws slides replace-text "<PRES_ID>" --find "{{PRESENTER}}" --replace "Jane Smith"

Move Slide to End

# Get slide ID from list (use .id field)
SLIDE_ID=$(gws slides list "<PRES_ID>" | jq -r '.slides[2].id')

# Move to high position (API adjusts to valid range)
gws slides reorder-slides "<PRES_ID>" --slide-ids "$SLIDE_ID" --to 99

Learnings

See LEARNINGS.md for session-specific learnings and gotchas discovered during real usage.

Note: LEARNINGS.md is a template. Keep sensitive/proprietary learnings local - don't commit them to the repo.

Google Tasks (gws tasks)

gws tasks provides CLI access to Google Tasks 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.

Quick Command Reference

TaskCommand
List task listsgws tasks lists
Get task list detailsgws tasks list-info <tasklist-id>
Create a task listgws tasks create-list --title "My List"
Update a task listgws tasks update-list <tasklist-id> --title "New Name"
Delete a task listgws tasks delete-list <tasklist-id>
List tasksgws tasks list <tasklist-id>
List with completedgws tasks list <tasklist-id> --show-completed
Get a taskgws tasks get <tasklist-id> <task-id>
Create a taskgws tasks create --title "Buy groceries"
Create with due dategws tasks create --title "Report" --due "2024-02-01"
Update a taskgws tasks update <tasklist-id> <task-id> --title "New title"
Delete a taskgws tasks delete <tasklist-id> <task-id>
Complete a taskgws tasks complete <tasklist-id> <task-id>
Reopen a taskgws tasks reopen <tasklist-id> <task-id>
Move a taskgws tasks move <tasklist-id> <task-id> --previous <sibling-id>
Clear completedgws tasks clear <tasklist-id>

Detailed Usage

lists — List task lists

gws tasks lists

Lists all your task lists. The default list is @default.

list-info — Get task list details

gws tasks list-info <tasklist-id>

Gets details for a specific task list including id, title, updated time, and self link.

Examples:

gws tasks list-info @default
gws tasks list-info MTIzNDU2

create-list — Create a task list

gws tasks create-list --title <title>

Flags:

  • --title string — Task list title (required)

Examples:

gws tasks create-list --title "Work Tasks"
gws tasks create-list --title "Shopping"

update-list — Update a task list

gws tasks update-list <tasklist-id> --title <title>

Flags:

  • --title string — New task list title (required)

Examples:

gws tasks update-list MTIzNDU2 --title "Renamed List"

delete-list — Delete a task list

gws tasks delete-list <tasklist-id>

Deletes a task list and all its tasks.

Examples:

gws tasks delete-list MTIzNDU2

list — List tasks in a task list

gws tasks list <tasklist-id> [flags]

Flags:

  • --max int — Maximum number of tasks (default 100)
  • --show-completed — Include completed tasks

Examples:

gws tasks list @default
gws tasks list @default --show-completed
gws tasks list @default --max 10

create — Create a task

gws tasks create --title <title> [flags]

Flags:

  • --title string — Task title (required)
  • --tasklist string — Task list ID (default: "@default")
  • --notes string — Task notes/description
  • --due string — Due date in RFC3339 or YYYY-MM-DD format

Examples:

gws tasks create --title "Buy groceries"
gws tasks create --title "Finish report" --due "2024-02-01" --notes "Include Q4 data"
gws tasks create --title "Team task" --tasklist MTIzNDU2

update — Update a task

gws tasks update <tasklist-id> <task-id> [flags]

Updates an existing task's title, notes, or due date while preserving its current completion status. At least one of --title, --notes, or --due is required.

Flags:

  • --title string — New task title
  • --notes string — New task notes/description
  • --due string — New due date in RFC3339 or YYYY-MM-DD format

Examples:

gws tasks update @default dGFzay0x --title "Updated title"
gws tasks update @default dGFzay0x --notes "Added notes" --due "2024-03-01"

get — Get a task

gws tasks get <tasklist-id> <task-id>

Gets full details for a specific task including title, notes, status, due date, parent, and completion time.

Examples:

gws tasks get @default dGFzay0xMjM0

delete — Delete a task

gws tasks delete <tasklist-id> <task-id>

Deletes a specific task.

Examples:

gws tasks delete @default dGFzay0xMjM0

complete — Mark a task as completed

gws tasks complete <tasklist-id> <task-id>

Marks a specific task as completed.

Examples:

gws tasks complete @default dGFzay0xMjM0

reopen — Reopen a completed task

gws tasks reopen <tasklist-id> <task-id>

Sets a task's status to needsAction while preserving its other fields.

Examples:

gws tasks reopen @default dGFzay0xMjM0

move — Move a task

gws tasks move <tasklist-id> <task-id> [flags]

Moves a task to a different position, parent, or task list.

Flags:

  • --parent string — Parent task ID (makes this a subtask)
  • --previous string — Previous sibling task ID (positions after this task)
  • --destination-list string — Destination task list ID (moves to another list)

Examples:

gws tasks move @default task-1 --previous task-2
gws tasks move @default task-1 --parent parent-task
gws tasks move @default task-1 --destination-list other-list-id

clear — Clear completed tasks

gws tasks clear <tasklist-id>

Clears all completed tasks from a task list. Completed tasks are marked as hidden and no longer returned by default.

Examples:

gws tasks clear @default

Output Modes

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

Tips for AI Agents

  • Always use --format json (the default) for programmatic parsing
  • Use gws tasks lists first to get task list IDs
  • Use gws tasks list <tasklist-id> to get individual task IDs for get, update, delete, complete, and move commands
  • Use gws tasks get to fetch full task details (notes, due date, parent, completion time)
  • The default task list ID is @default — use this when users don't specify a list
  • Due dates accept both RFC3339 (2024-02-01T00:00:00Z) and simple date (2024-02-01) formats
  • Completed tasks are hidden by default; use --show-completed to include them, or clear to permanently hide them
  • Use move --destination-list to transfer tasks between lists, --parent to make subtasks, --previous to reorder
  • Use --quiet on create/update/delete/complete operations to suppress JSON output in scripts

Sponsors

Details

Marketplace
omriariav/workspace-cli
Category
Community