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-cliRun it inside Claude Code after adding the marketplace with /plugin marketplace add omriariav/workspace-cli.
Contents
Discovered from sourceSkills 16
Google Workspace Auth (gws auth)
gws auth manages OAuth2 authentication for all Google Workspace services.
Disclaimer:
gwsis 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
| Task | Command |
|---|---|
| Check auth status | gws auth status |
| Login (all scopes) | gws auth login |
| Login (specific services) | gws auth login --services gmail,calendar,chat |
| Login with credentials | gws 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.
| Mode | Required settings | Behavior |
|---|---|---|
oauth (default) | none | Interactive OAuth2 + PKCE via gws auth login |
service-account-dwd | service_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-app | service_account_key_file | Admin-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 loginfails fast in service-account modes (no login needed);gws auth statusreports the configured mode instead of token state.- Incomplete or mixed configuration is rejected: DWD without
impersonate_user, app mode withimpersonate_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:
- Create a Google Cloud project
- Enable the required Workspace APIs
- Create OAuth 2.0 credentials (Desktop app type)
- Set credentials via environment variables or config file
- 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):
- Command-line flags (
--client-id,--client-secret) - Environment variables (
GWS_CLIENT_ID,GWS_CLIENT_SECRET) - 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
--servicesto 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 statusbefore 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 logoutthengws auth login
Google Calendar (gws calendar)
gws calendar provides CLI access to Google Calendar with structured JSON output.
Disclaimer:
gwsis 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
| Task | Command |
|---|---|
| List calendars | gws calendar list |
| View upcoming events | gws calendar events |
| View next 14 days | gws calendar events --days 14 |
| 3-day window (yesterday–tomorrow) | gws calendar events --from "2026-03-24" --days 3 |
| Search events by text | gws calendar events --query "standup" |
| View pending invites | gws calendar events --days 30 --pending |
| Filter by event type | gws calendar events --event-types focusTime,outOfOffice |
| Get event by ID | gws calendar get --id <event-id> |
| Create an event | gws calendar create --title "Meeting" --start "2024-02-01 14:00" --end "2024-02-01 15:00" |
| Quick add from text | gws calendar quick-add --text "Lunch with John tomorrow at noon" |
| Update an event | gws calendar update <event-id> --title "New Title" |
| Delete an event | gws calendar delete <event-id> |
| RSVP to an event | gws calendar rsvp <event-id> --response accepted |
| List recurring instances | gws calendar instances --id <event-id> |
| Move event to calendar | gws calendar move --id <event-id> --destination <cal-id> |
Calendar Management
| Task | Command |
|---|---|
| Get calendar metadata | gws calendar get-calendar --id <cal-id> |
| Create secondary calendar | gws calendar create-calendar --summary "Projects" |
| Update calendar | gws calendar update-calendar --id <cal-id> --summary "New Name" |
| Delete secondary calendar | gws calendar delete-calendar --id <cal-id> |
| Clear all events | gws calendar clear |
Subscriptions
| Task | Command |
|---|---|
| Subscribe to calendar | gws calendar subscribe --id <cal-id> |
| Unsubscribe | gws calendar unsubscribe --id <cal-id> |
| Get subscription info | gws calendar calendar-info --id <cal-id> |
| Update subscription | gws calendar update-subscription --id <cal-id> --color-id 7 |
Access Control (ACL)
| Task | Command |
|---|---|
| List ACL rules | gws calendar acl |
| Share with user | gws calendar share --email user@example.com --role reader |
| Remove access | gws calendar unshare --rule-id "user:user@example.com" |
| Update access | gws calendar update-acl --rule-id "user:user@example.com" --role writer |
Other
| Task | Command |
|---|---|
| Query free/busy | gws calendar freebusy --from "2024-03-01 09:00" --to "2024-03-01 17:00" |
| List colors | gws calendar colors |
| List settings | gws 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--maxwhen using--pendingover long date ranges, since--maxlimits 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):
| Category | Fields |
|---|---|
| Core | id, summary, status |
| Time | start, end, all_day |
| Details | description, location, hangout_link, html_link, created, updated, color_id, visibility, transparency, event_type |
| People | organizer (email), creator (email), response_status (your RSVP) |
| Attendees | attendees[] -- { email, response_status, optional, organizer, self } |
| Conference | conference -- { conference_id, solution, entry_points[]: { type, uri } } |
| Attachments | attachments[] -- { file_url, title, mime_type, file_id } |
| Recurrence | recurrence[] -- RRULE strings |
| Reminders | reminders -- { 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 orYYYY-MM-DD HH:MMformat (required)--end string-- End time in RFC3339 orYYYY-MM-DD HH:MMformat (required)--calendar-id string-- Calendar ID (default: "primary")--description string-- Event description--location string-- Event location--attendees strings-- Attendee email addresses--add-self bool(defaulttrue) -- Add the authenticated user as anacceptedattendee. Pass--add-self=falseto 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 eventsto 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
updatecommand uses PATCH (not PUT), so only changed fields are sent - For non-primary calendars, get the calendar ID from
gws calendar listfirst - Use
quick-addfor natural language event creation (e.g. "Meeting with Bob next Tuesday 2pm") - Use
freebusyto check availability before creating events - ACL roles:
freeBusyReader<reader<writer<owner - Default event window is 7 days; increase with
--daysfor broader views
Google Chat (gws chat)
gws chat provides CLI access to Google Chat with structured JSON output.
Disclaimer:
gwsis not the official Google CLI. This is an independent, open-source project not endorsed by or affiliated with Google.
Dependency Check
Before executing any gws command, verify the CLI is installed:
gws version
If not found, install: go install github.com/omriariav/workspace-cli/cmd/gws@latest
Authentication
Requires OAuth2 credentials. Run gws auth status to check.
If not authenticated: gws auth login (opens browser for OAuth consent).
For initial setup, see the gws-auth skill.
Note: Google Chat API requires additional setup:
- Enable the Chat API in your Google Cloud project
- Configure the OAuth consent screen for Chat scopes
- For some operations, you may need a service account with domain-wide
delegation — configure it with
auth_mode: service-account-dwd(see thegws-authskill). Note:auth_mode: service-account-app(admin-approved Chat app credentials) is restricted togws eventssubscriptions on individual Chat spaces; it does NOT enable normal Chat operations such as send, notify, or space management.
Quick Command Reference
| Task | Command |
|---|---|
| Spaces | |
| List chat spaces | gws chat list |
| List spaces (filtered) | gws chat list --filter 'spaceType = "SPACE"' |
| Get space details | gws chat get-space <space-id> |
| Create a space | gws chat create-space --display-name "Team" --type SPACE |
| Delete a space | gws chat delete-space <space-id> |
| Update a space | gws chat update-space <space-id> --display-name "New Name" |
| Search spaces (admin only) | gws chat search-spaces --query "Engineering" |
| Find DM with user | gws chat find-dm --email user@example.com |
| Create space + members | gws chat setup-space --display-name "Team" --members "users/1,users/2" |
| Create DM | gws chat setup-space --type DIRECT_MESSAGE --members "users/123" |
| Create group chat | gws chat setup-space --type GROUP_CHAT --members "users/1,users/2" |
| Build member cache | gws chat build-cache |
| Find group by members | gws chat find-group --members "user1@example.com,user2@example.com" |
| Find space by name | gws chat find-space --name "sales-skills" |
| Messages | |
| Read messages | gws chat messages <space-id> |
| Read recent messages | gws chat messages <space-id> --order-by "createTime DESC" --max 10 |
| Messages after a date | gws chat messages <space-id> --after "2026-02-17T00:00:00Z" |
| Messages in a range | gws chat messages <space-id> --after "2026-02-17T00:00:00Z" --before "2026-02-20T00:00:00Z" |
| Recap recent messages | gws chat recent --since 2h |
| Recap last 7 days | gws chat recent --since 7d --max 1000 |
| Send a message | gws chat send --space <space-id> --text "Hello" |
| Quote a message | gws chat send --space <space-id> --text "Reply" --quote <message-id> |
| Get a single message | gws chat get <message-name> |
| Update a message | gws chat update <message-name> --text "New text" |
| Delete a message | gws chat delete <message-name> |
| Members | |
| List space members | gws chat members <space-id> |
| Get member details | gws chat get-member <member-name> |
| Add a member | gws chat add-member <space-id> --user users/123 |
| Remove a member | gws chat remove-member <member-name> |
| Update member role | gws chat update-member <member-name> --role ROLE_MANAGER |
| Reactions | |
| List reactions | gws chat reactions <message-name> |
| Add a reaction | gws chat react <message-name> --emoji "👍" |
| Remove a reaction | gws chat unreact <reaction-name> |
| Read State | |
| Get read state | gws chat read-state <space-id> |
| Mark space as read | gws chat mark-read <space-id> |
| Get thread read state | gws chat thread-read-state <thread-name> |
| List unread messages | gws chat unread <space-id> |
| Attachments & Media | |
| Get attachment info | gws chat attachment <attachment-name> |
| Upload a file | gws chat upload <space-id> --file ./report.pdf |
| Download media | gws chat download <resource-name> --output ./file.pdf |
| Events | |
| List space events | gws chat events <space-id> --filter 'event_types:"google.workspace.chat.message.v1.created"' |
| Get event details | gws chat event <event-name> |
Detailed Usage
list — List chat spaces
gws chat list [flags]
Lists all Chat spaces (rooms, DMs, group chats) you have access to. Supports filtering and pagination.
Flags:
--filter string— Filter spaces (e.g.spaceType = "SPACE")--page-size int— Number of spaces per page (default 100)
messages — List messages in a space
gws chat messages <space-id> [flags]
Flags:
--max int— Maximum number of messages to return (default 25)--after string— Show messages after this time (RFC3339, e.g.2026-02-17T00:00:00Z)--before string— Show messages before this time (RFC3339, e.g.2026-02-20T00:00:00Z)--filter string— Filter messages (e.g.createTime > "2024-01-01T00:00:00Z")--order-by string— Order messages (e.g.createTime DESC)--show-deleted— Include deleted messages in results--resolve-senders— Make extra API calls to fill missingsender_display_name(via space membership listing) and add aselfboolean (via People APIpeople/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). Default2h.--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 bylastActiveTimeDESC (default0= all)--resolve-senders— Fillsender_display_name(one extra membership-list call per active space) and addselfvia 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-sendersis set and the People API self lookup succeeds. Omitted otherwise rather than guessed.--resolve-sendersonly adds work for the cases the payload alone can't satisfy: fillingsender_display_namewhen the API didn't include one, and addingself. 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:replyorforward(default API behavior is reply).--notify string— Notification behavior:none,force, orsilent(defaultnone).forceandsilentrequire Chat app authentication for message sends, which gws does not support: theservice-account-appauth mode only coversgws eventssubscriptions, 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 onchat 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.spacesscope. 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 onchat 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
--refreshso 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--typeif set, otherwise all types)
Output Modes
gws chat list --format json # Structured JSON (default)
gws chat list --format yaml # YAML format
gws chat list --format text # Human-readable text
Common Mistakes
| Mistake | Correct Usage |
|---|---|
--limit N on messages | Use --max N — --limit does not exist |
find-dm --user email@example.com | Use users/email@example.com format — the --user flag requires a resource name prefix |
setup-space --display-name "X" --type DIRECT_MESSAGE | Omit --display-name for DM/GROUP_CHAT — API rejects it |
find-group without cache | Run gws chat build-cache first, or use --refresh |
Recipe: Find a Group Chat by Member Names
Preferred method — use the member cache:
# 1. Build the cache (one-time, or periodically)
gws chat build-cache
# 2. Search by email
gws chat find-group --members "alice@example.com,bob@example.com"
# 3. Get recent messages from the matched space
gws chat messages spaces/AAAApznBCFA --after "2026-02-20T00:00:00Z" --order-by "createTime DESC" --max 25
Alternative — manual search (no cache needed):
# 1. List all spaces, filter to group chats
gws chat list --format json | jq '.spaces | map(select(.type == "GROUP_CHAT")) | .[:10]'
# 2. Check members of candidate spaces
gws chat members spaces/AAAApznBCFA --format json
Key insight: DMs and group chats often have empty display_name — you must check members to identify participants.
Recipe: Create a DM via Contacts
# 1. Resolve email to user resource name
gws contacts resolve --email "user@example.com"
# 2. Check if DM already exists
gws chat find-dm --user users/123456
# 3. If not found, create the DM
gws chat setup-space --type DIRECT_MESSAGE --members "users/123456"
# 4. Send a message
gws chat send --space spaces/DMXYZ --text "Hello!"
Tips for AI Agents
- Always use
--format json(the default) for programmatic parsing - Use
gws chat listfirst to get space IDs - Space IDs are in the format
spaces/AAAA1234 - Message names are in the format
spaces/AAAA/messages/msg1 membersauto-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-stateauto-expands bare space IDs (e.g.AAAA→users/me/spaces/AAAA/spaceReadState)eventsrequires a--filterwith event types — see API docs- Chat API requires additional GCP setup beyond standard OAuth — see the
gws-authskill - For continuous push notifications of Chat events (messages, memberships, reactions, read-state) use Workspace Events subscriptions — see the
gws-eventsskill
Google Contacts (gws contacts)
gws contacts provides CLI access to Google Contacts via the People API with structured JSON output.
Disclaimer:
gwsis 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
| Task | Command |
|---|---|
| List contacts | gws contacts list |
| List more contacts | gws contacts list --max 100 |
| Search by name | gws contacts search "John Doe" |
| Search by email | gws contacts search "john@example.com" |
| Get contact details | gws contacts get <resource-name> |
| Create a contact | gws contacts create --name "Jane Smith" --email "jane@example.com" |
| Update a contact | gws contacts update <resource-name> --name "New Name" |
| Delete a contact | gws contacts delete <resource-name> |
| Batch create contacts | gws contacts batch-create --file contacts.json |
| Batch update contacts | gws contacts batch-update --file updates.json |
| Batch delete contacts | gws contacts batch-delete --resources people/c1 --resources people/c2 |
| List directory people | gws contacts directory |
| Search directory | gws contacts directory-search --query "John" |
| Update contact photo | gws contacts photo <resource-name> --file photo.jpg |
| Delete contact photo | gws contacts delete-photo <resource-name> |
| Resolve multiple contacts | gws 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 nameemails— Array of email addressesphones— Array of phone numbersorganization— 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 identifiername— Contact's display nameemails— Array of email addressesphones— Array of phone numbersorganization— 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 listorsearchto get resource names, then use those withgetordelete - Resource names have the format
people/c<numeric-id>(e.g.,people/c1234567890) - The
listcommand paginates automatically up to the--maxlimit (default 50) - Search is more efficient than listing all contacts and filtering client-side
- When creating contacts,
--nameis required, but--emailand--phoneare optional - Organization info can be set via
updatecommand (--organization,--titleflags) - Use
--quieton any command to suppress JSON output (useful for scripted actions) - For bulk operations, use
batch-create,batch-update,batch-deletefor better efficiency - Use
resolveto fetch multiple contacts in one request instead of multiplegetcalls - Directory commands (
directory,directory-search) require Google Workspace anddirectory.readonlyscope
Google Docs (gws docs)
gws docs provides CLI access to Google Docs with structured JSON output.
Disclaimer:
gwsis 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
| Task | Command |
|---|---|
| Read a document | gws docs read <doc-id> |
| Read with formatting | gws docs read <doc-id> --include-formatting |
| Get document info | gws docs info <doc-id> |
| Create a document | gws docs create --title "My Doc" |
| Create with markdown | gws docs create --title "My Doc" --text "# Heading\n\n**Bold**" |
| Create with plain text | gws docs create --title "My Doc" --text "Plain" --content-format plaintext |
| Append text | gws docs append <doc-id> --text "New paragraph" |
| Insert text at position | gws docs insert <doc-id> --text "Hello" --at 1 |
| Find and replace | gws docs replace <doc-id> --find "old" --replace "new" |
| Replace all content | gws docs replace-content <doc-id> --text "# New content" |
| Replace from file | gws docs replace-content <doc-id> --file ./content.md |
| Delete content | gws docs delete <doc-id> --from 5 --to 10 |
| Add a table | gws docs add-table <doc-id> --rows 3 --cols 4 |
| Format text | gws docs format <doc-id> --from 1 --to 10 --bold |
| Set paragraph style | gws docs set-paragraph-style <doc-id> --from 1 --to 100 --alignment CENTER |
| Set heading style | gws docs set-paragraph-style <doc-id> --from 1 --to 100 --style HEADING_1 |
| Add a list | gws docs add-list <doc-id> --at 1 --type bullet --items "A;B;C" |
| Remove list | gws docs remove-list <doc-id> --from 1 --to 50 |
| Trash document | gws docs trash <doc-id> |
| Permanently delete | gws docs trash <doc-id> --permanent |
| Add a tab | gws docs add-tab <doc-id> --title "Tab 2" |
| Delete a tab | gws docs delete-tab <doc-id> --tab-id <id> |
| Rename a tab | gws docs rename-tab <doc-id> --tab-id <id> --title "New Name" |
| Read specific tab | gws docs read <doc-id> --tab "Tab 2" |
| Add an image | gws docs add-image <doc-id> --uri <url> |
| Insert table row | gws docs insert-table-row <doc-id> --table-start 5 --row 0 --col 0 |
| Delete table row | gws docs delete-table-row <doc-id> --table-start 5 --row 0 --col 0 |
| Insert table column | gws docs insert-table-col <doc-id> --table-start 5 --row 0 --col 0 |
| Delete table column | gws docs delete-table-col <doc-id> --table-start 5 --row 0 --col 0 |
| Merge table cells | gws docs merge-cells <doc-id> --table-start 5 --row 0 --col 0 --row-span 2 --col-span 2 |
| Unmerge table cells | gws docs unmerge-cells <doc-id> --table-start 5 --row 0 --col 0 --row-span 2 --col-span 2 |
| Pin header rows | gws docs pin-rows <doc-id> --table-start 5 --count 1 |
| Insert page break | gws docs page-break <doc-id> --at 10 |
| Insert section break | gws docs section-break <doc-id> --at 10 |
| Add header | gws docs add-header <doc-id> |
| Delete header | gws docs delete-header <doc-id> <header-id> |
| Add footer | gws docs add-footer <doc-id> |
| Delete footer | gws docs delete-footer <doc-id> <footer-id> |
| Add named range | gws docs add-named-range <doc-id> --name "range1" --from 1 --to 10 |
| Delete named range | gws docs delete-named-range <doc-id> --name "range1" |
| Add footnote | gws docs add-footnote <doc-id> --at 5 |
| Delete object | gws docs delete-object <doc-id> <object-id> |
| Replace image | gws docs replace-image <doc-id> --object-id <id> --uri <url> |
| Replace named range | gws docs replace-named-range <doc-id> --name "range1" --text "new" |
| Update doc margins | gws docs update-style <doc-id> --margin-top 72 |
| Update section style | gws docs update-section-style <doc-id> --from 1 --to 100 --column-count 2 |
| Update cell style | gws docs update-table-cell-style <doc-id> --table-start 5 --row 0 --col 0 --bg-color "#FF0000" |
| Update column width | gws docs update-table-col-properties <doc-id> --table-start 5 --col-index 0 --width 200 |
| Update row height | gws 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, orrichformat
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, orrichformat
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, orrichformat
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.
| Format | Description |
|---|---|
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. |
plaintext | Text 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)
appendis the simplest way to add content — it adds to the end with an automatic newlinereplacereplaces 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
--quieton 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:
gwsis 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
| Task | Command |
|---|---|
| List files | gws drive list |
| List files in folder | gws drive list --folder <folder-id> |
| Search files | gws drive search "quarterly report" |
| Get file info | gws drive info <file-id> |
| Download a file | gws drive download <file-id> |
| Upload a file | gws drive upload report.pdf |
| Create a folder | gws drive create-folder --name "Project Files" |
| Move a file | gws drive move <file-id> --to <folder-id> |
| Delete a file | gws drive delete <file-id> |
| Copy a file | gws drive copy <file-id> |
| Convert Office file | gws drive convert <file-id> |
| Export file | gws drive export --file-id <id> --mime-type application/pdf --output report.pdf |
| Update metadata | gws drive update --file-id <id> --name "New Name" |
| Empty trash | gws drive empty-trash |
| Drive info | gws drive about |
| Recent changes | gws drive changes |
Permissions
| Task | Command |
|---|---|
| List permissions | gws drive permissions --file-id <id> |
| Share with user | gws drive share --file-id <id> --type user --role writer --email user@example.com |
| Share with anyone | gws drive share --file-id <id> --type anyone --role reader |
| Get permission | gws drive permission --file-id <id> --permission-id <perm-id> |
| Update permission | gws drive update-permission --file-id <id> --permission-id <perm-id> --role reader |
| Remove permission | gws drive unshare --file-id <id> --permission-id <perm-id> |
Comments & Replies
| Task | Command |
|---|---|
| List comments | gws drive comments <file-id> |
| Get comment | gws drive comment --file-id <id> --comment-id <cid> |
| Add comment | gws drive add-comment --file-id <id> --content "Great work!" |
| Delete comment | gws drive delete-comment --file-id <id> --comment-id <cid> |
| Resolve comment | gws drive resolve-comment --file-id <id> --comment-id <cid> |
| Unresolve comment | gws drive unresolve-comment --file-id <id> --comment-id <cid> |
| List replies | gws drive replies --file-id <id> --comment-id <cid> |
| Reply to comment | gws drive reply --file-id <id> --comment-id <cid> --content "Thanks!" |
| Get reply | gws drive get-reply --file-id <id> --comment-id <cid> --reply-id <rid> |
| Delete reply | gws drive delete-reply --file-id <id> --comment-id <cid> --reply-id <rid> |
Approvals
| Task | Command |
|---|---|
| List approvals | gws drive approvals <file-id> |
| Get approval | gws drive approval <file-id> <approval-id> |
| Start approval | gws drive start-approval --file-id <id> --reviewers reviewer@example.com |
| Approve | gws drive approve --file-id <id> --approval-id <approval-id> |
| Decline | gws drive decline --file-id <id> --approval-id <approval-id> |
| Reassign reviewers | gws drive reassign-approval --file-id <id> --approval-id <approval-id> --add-reviewer reviewer@example.com |
| Cancel approval | gws drive cancel-approval --file-id <id> --approval-id <approval-id> |
| Comment on approval | gws drive comment-approval --file-id <id> --approval-id <approval-id> --message "Looks good" |
Revisions
| Task | Command |
|---|---|
| List revisions | gws drive revisions --file-id <id> |
| Get revision | gws drive revision --file-id <id> --revision-id <rid> |
| Delete revision | gws drive delete-revision --file-id <id> --revision-id <rid> |
Shared Drives
| Task | Command |
|---|---|
| List shared drives | gws drive shared-drives |
| Get shared drive | gws drive shared-drive --id <drive-id> |
| Create shared drive | gws drive create-drive --name "Engineering" |
| Update shared drive | gws drive update-drive --id <drive-id> --name "New Name" |
| Delete shared drive | gws 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 inold@example.com=new@example.comform--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 searchto find files by name, thengws 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
--permanentonly when explicitly requested - When uploading, MIME type is auto-detected from the file extension
- The
commentscommand works on any Drive file type (Docs, Sheets, Slides, etc.) - Resolved comments are excluded by default; use
--include-resolvedto see them - Use
gws drive aboutto check storage quota before large uploads - Use
gws drive changesto monitor recent file activity - For sharing, use
--type anyone --role readerfor 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:
gwsis 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
| Task | Command |
|---|---|
| List subscriptions | gws events subscriptions list --event-type <type> [--target <resource>] |
| Get a subscription | gws events subscriptions get <id> |
| Create a subscription | gws events subscriptions create --target <resource> --event-types <types> --topic projects/P/topics/T |
| Update event types / TTL | gws events subscriptions update <id> --event-types <types> --ttl 86400s |
| Renew (extend expiration) | gws events subscriptions renew <id> (--ttl 0s = maximum) |
| Delete | gws events subscriptions delete <id> |
| Reactivate a suspended subscription | gws 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)
| Target | Format | Notes |
|---|---|---|
| Chat space | //chat.googleapis.com/spaces/SPACE | user 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/USER | user auth only; Chat membership + read-state, or Meet events |
| Drive file | //drive.googleapis.com/files/FILE | file + permission events |
| Shared drive | //drive.googleapis.com/drives/DRIVE | file + permission events |
| Meet space | //meet.googleapis.com/spaces/SPACE | Meet 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) plusgoogle.workspace.chat.spaceReadState.v1.updatedandgoogle.workspace.chat.threadReadState.v1.updated(user targets, user auth). - Drive (baseline):
google.workspace.drive.file.v3.{added,moved,contentChanged,deleted,renamed,trashed,untrashed}andgoogle.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(theeventsservice 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 usechat.bot; mutations mint only the granularchat.app.*.readonlyscope(s) matching the subscription's event classes (derived from the existing subscription via achat.botGet 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/TOPICand confirm it already exists;gwswill not create it. - Prefer the default least-privilege scopes; only pass
--meet-created-scopewhen the subscription covers Meet spaces the authenticated user created. - Renew before expiry: subscriptions with
--include-resource-dataexpire sooner.renewwith the default--ttl 0srequests the maximum. - In
service-account-appmode, 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:
gwsis 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
| Task | Command |
|---|---|
| Get form info | gws forms info <form-id> |
| Get form details (alias) | gws forms get <form-id> |
| Get all form responses | gws forms responses <form-id> |
| Get a single response | gws forms response <form-id> --response-id <id> |
| Create a new form | gws forms create --title "My Form" |
| Update a form | gws 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
infoto understand the form structure before fetching responses - Use
createto make a new blank form, thenupdate --fileto add questions via batchUpdate - The
getcommand is an alias forinfo— both return the same output - Use
--quieton 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:
gwsis 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
| Task | Command |
|---|---|
| List recent emails | gws gmail list |
| List with labels | gws gmail list --include-labels |
| List all matches | gws gmail list --query "label:work" --all |
| List unread emails | gws gmail list --query "is:unread" |
| Search emails | gws gmail list --query "from:user@example.com" |
| Read a message | gws gmail read <message-id> |
| Extract HTML links | gws gmail links <message-id> |
| Read full thread | gws gmail thread <thread-id> |
| Send an email | gws gmail send --to user@example.com --subject "Hi" --body "Hello" |
| List all labels | gws gmail labels |
| Get label details | gws gmail label-info --id Label_1 |
| Create a label | gws gmail create-label --name "MyLabel" |
| Update a label | gws gmail update-label --id Label_1 --name "NewName" |
| Delete a label | gws gmail delete-label --id Label_1 |
| Add labels | gws gmail label <message-id> --add "STARRED" |
| Remove labels | gws gmail label <message-id> --remove "UNREAD" |
| Batch modify labels | gws gmail batch-modify --ids "msg1,msg2" --add-labels "STARRED" |
| Archive a message | gws gmail archive <message-id> |
| Archive a thread | gws gmail archive-thread <thread-id> |
| Trash a message | gws gmail trash <message-id> |
| Untrash a message | gws gmail untrash <message-id> |
| Delete a message | gws gmail delete <message-id> |
| Batch delete | gws gmail batch-delete --ids "msg1,msg2" |
| Trash a thread | gws gmail trash-thread <thread-id> |
| Untrash a thread | gws gmail untrash-thread <thread-id> |
| Delete a thread | gws gmail delete-thread <thread-id> |
| Reply to a message | gws gmail reply <message-id> --body "Thanks!" |
| Reply to all | gws gmail reply <message-id> --body "Got it" --all |
| Forward a message | gws gmail forward <message-id> --to "user@example.com" |
| Extract event ID | gws gmail event-id <message-id> |
| List drafts | gws gmail drafts |
| Get a draft | gws gmail draft --id <draft-id> |
| Create a draft | gws gmail create-draft --to user@example.com --subject "Hi" --body "Hello" |
| Update a draft | gws gmail update-draft --id <draft-id> --body "Updated body" |
| Send a draft | gws gmail send-draft --id <draft-id> |
| Delete a draft | gws gmail delete-draft --id <draft-id> |
| Download attachment | gws 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 withgws gmail thread)message_id— Latest message ID (use withread,label,archive,trash)message_count— Number of messages in the thread
Flags:
--max int— Maximum number of results (default 10, use--allfor 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 texthref— Full URLmime_part— Always"text/html"google_docs_id— (Google Docs only) document ID parsed from the URL pathquery— (Google Docs only) raw query string, e.g.usp=sharingfragment— (Google Docs only) URL fragment including#, e.g.#heading=h.abctab_id— (Google Docs only) tab ID from thetabquery 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 listto get IDs:message_idforread/label/archive/trash,thread_idforthread - 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 labelsfirst 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-labelswithlistto see which Gmail labels are applied to each thread - Use
--allwithlistto fetch every matching result (bypasses the default 10 limit) - Use
--quieton 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:
gwsis 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
| Task | Command |
|---|---|
| List groups | gws groups list |
| List groups in a domain | gws groups list --domain example.com |
| List groups for a user | gws groups list --user-email user@example.com |
| List more groups | gws groups list --max 200 |
| List group members | gws groups members group@example.com |
| List group owners | gws 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 IDemail-- Group email addressname-- Group display namedescription-- 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, orMEMBER
Output includes:
id-- Member IDemail-- Member email addressrole-- 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
listcommand returns groups for the entire customer account by default; use--domainor--user-emailto narrow results --domainand--user-emailcannot be used together -- pick one filter- Use
--roleon thememberscommand to quickly find group owners or managers - The
memberscommand requires the exact group email address as a positional argument - Use
--quieton 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
jqto 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.
gwsis 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 thegwsSessionStartandUserPromptSubmitentries, 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:
gwsis 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
| Task | Command |
|---|---|
| List notes | gws keep list |
| List more notes | gws keep list --max 50 |
| Get a specific note | gws keep get <note-id> |
| Create a note | gws 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 titletext-- 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/abc123or justabc123)
Output includes:
name-- Note resource nametitle-- Note titletext-- 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 nametitle-- Note titletext-- Note text contentcreate_time-- Creation timestampupdate_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 listto discover note IDs, then usegetfor full details - Note IDs follow the format
notes/<alphanumeric-id>(e.g.,notes/abc123) - The
getcommand accepts bothnotes/abc123andabc123-- thenotes/prefix is added automatically if missing - Both
--titleand--textare required when creating a note - The
listcommand default is 20 notes; increase with--maxif you need more - Use
--quieton 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:
gwsis 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:
- Create a Programmable Search Engine at https://programmablesearchengine.google.com/
- Get an API key from Google Cloud Console
- Set
GWS_SEARCH_ENGINE_IDandGWS_SEARCH_API_KEYenvironment variables, or addsearch_engine_idandsearch_api_keyto your config file
Quick Command Reference
| Task | Command |
|---|---|
| Web search | gws search "query" |
| Limit results | gws search "query" --max 5 |
| Search a site | gws search "query" --site example.com |
| Image search | gws search "query" --type image |
| Paginate results | gws search "query" --start 11 |
| Override API key | gws 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:imageor 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
--startto paginate - The
--siteflag 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:
gwsis 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
| Task | Command |
|---|---|
| Get spreadsheet info | gws sheets info <id> |
| List sheets | gws sheets list <id> |
| Read a range | gws sheets read <id> "Sheet1!A1:D10" |
| Read entire sheet | gws sheets read <id> "Sheet1" |
Writing Data
| Task | Command |
|---|---|
| Create spreadsheet | gws sheets create --title "My Sheet" |
| Write to cells | gws sheets write <id> "Sheet1!A1" --values "a,b,c" |
| Write multiple rows | gws sheets write <id> "A1" --values "a,b,c;d,e,f" |
| Write JSON data | gws sheets write <id> "A1" --values-json '[["a","b"],["c","d"]]' |
| Append rows | gws sheets append <id> "Sheet1" --values "x,y,z" |
| Clear cells | gws sheets clear <id> "Sheet1!A1:D10" |
Batch & Cross-Spreadsheet Operations
| Task | Command |
|---|---|
| Read multiple ranges | gws sheets batch-read <id> --ranges "A1:B5" --ranges "Sheet2!A1:C10" |
| Write multiple ranges | gws sheets batch-write <id> --ranges "A1:B2" --values '[[1,2],[3,4]]' |
| Copy sheet to another | gws sheets copy-to <id> --sheet-id 0 --destination <dest-id> |
Sheet Management
| Task | Command |
|---|---|
| Add a sheet | gws sheets add-sheet <id> --name "New Sheet" |
| Delete a sheet | gws sheets delete-sheet <id> --name "Old Sheet" |
| Rename a sheet | gws sheets rename-sheet <id> --sheet "Old" --name "New" |
| Duplicate a sheet | gws sheets duplicate-sheet <id> --sheet "Template" |
Row/Column Operations
| Task | Command |
|---|---|
| Insert rows | gws sheets insert-rows <id> --sheet "Sheet1" --at 5 --count 3 |
| Delete rows | gws sheets delete-rows <id> --sheet "Sheet1" --from 5 --to 8 |
| Insert columns | gws sheets insert-cols <id> --sheet "Sheet1" --at 2 --count 1 |
| Delete columns | gws sheets delete-cols <id> --sheet "Sheet1" --from 2 --to 4 |
Named Ranges
| Task | Command |
|---|---|
| Add a named range | gws sheets add-named-range <id> "Sheet1!A1:D10" --name "MyRange" |
| List named ranges | gws sheets list-named-ranges <id> |
| Delete a named range | gws sheets delete-named-range <id> --named-range-id "nr-123" |
Filters
| Task | Command |
|---|---|
| Add a basic filter | gws sheets add-filter <id> "Sheet1!A1:D10" |
| Clear a basic filter | gws sheets clear-filter <id> --sheet "Sheet1" |
| Add a filter view | gws sheets add-filter-view <id> "Sheet1!A1:D10" --name "My View" |
Cell Operations
| Task | Command |
|---|---|
| Merge cells | gws sheets merge <id> "Sheet1!A1:D4" |
| Unmerge cells | gws sheets unmerge <id> "Sheet1!A1:D4" |
| Sort a range | gws sheets sort <id> "A1:D10" --by B --desc |
| Find and replace | gws sheets find-replace <id> --find "old" --replace "new" |
| Format cells | gws sheets format <id> "A1:D10" --bold --bg-color "#FFFF00" |
| Set column width | gws sheets set-column-width <id> --sheet "Sheet1" --col A --width 200 |
| Set row height | gws sheets set-row-height <id> --sheet "Sheet1" --row 1 --height 50 |
| Freeze panes | gws sheets freeze <id> --sheet "Sheet1" --rows 1 --cols 1 |
Charts
| Task | Command |
|---|---|
| Add a chart | gws sheets add-chart <id> --type BAR --data "Sheet1!A1:B10" |
| List charts | gws sheets list-charts <id> |
| Delete a chart | gws sheets delete-chart <id> --chart-id 12345 |
Conditional Formatting
| Task | Command |
|---|---|
| Add a rule | gws sheets add-conditional-format <id> "A1:D10" --rule ">" --value "100" --bg-color "#FFFF00" |
| List rules | gws sheets list-conditional-formats <id> --sheet "Sheet1" |
| Delete a rule | gws 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:jsonorcsv(default: "json")
Range format:
Sheet1!A1:D10— Specific range in Sheet1Sheet1!A:D— Columns A through DSheet1— All data in Sheet1A1: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 fromlist-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 fromlist-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,
--fromis inclusive and--tois exclusive - Use
--values-jsonfor data that might contain commas or semicolons appendfinds the last row with data and adds below it — great for log-style dataread --headers(default true) uses the first row as JSON keys — disable with--headers=falsefor 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
--quieton 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:
gwsis 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
| Task | Command |
|---|---|
| Get presentation info | gws slides info <id> |
| List all slides | gws slides list <id> |
| Read slide content | gws slides read <id> |
| Read specific slide | gws slides read <id> 3 |
| Read with speaker notes | gws slides read <id> --notes |
| Create presentation | gws slides create --title "My Deck" |
| Add a slide | gws slides add-slide <id> --title "Slide Title" --body "Content" |
| Add blank slide | gws slides add-slide <id> --layout BLANK |
| Delete a slide | gws slides delete-slide <id> --slide-number 3 |
| Duplicate a slide | gws slides duplicate-slide <id> --slide-number 2 |
| Add a shape | gws slides add-shape <id> --slide-number 1 --type RECTANGLE |
| Add an image | gws slides add-image <id> --slide-number 1 --url "https://..." |
| Add text to shape | gws slides add-text <id> --object-id <obj-id> --text "Hello" |
| Add text to table cell | gws slides add-text <id> --table-id <tbl-id> --row 0 --col 0 --text "Cell" |
| Add speaker notes | gws slides add-text <id> --notes --slide-number 1 --text "Notes here" |
| Clear speaker notes | gws slides delete-text <id> --notes --slide-number 1 |
| Find and replace | gws slides replace-text <id> --find "old" --replace "new" |
| Delete any element | gws slides delete-object <id> --object-id <obj-id> |
| Clear text from shape | gws slides delete-text <id> --object-id <obj-id> |
| Style text | gws slides update-text-style <id> --object-id <obj-id> --bold --color "#FF0000" |
| Move/resize element | gws slides update-transform <id> --object-id <obj-id> --x 200 --y 100 |
| Create a table | gws slides create-table <id> --slide-number 1 --rows 3 --cols 4 |
| Insert table rows | gws slides insert-table-rows <id> --table-id <tbl-id> --at 1 --count 2 |
| Delete table row | gws slides delete-table-row <id> --table-id <tbl-id> --row 2 |
| Style table cell | gws slides update-table-cell <id> --table-id <tbl-id> --row 0 --col 0 --background-color "#FFFF00" |
| Style table border | gws slides update-table-border <id> --table-id <tbl-id> --row 0 --col 0 --color "#000000" |
| Paragraph style | gws slides update-paragraph-style <id> --object-id <obj-id> --alignment CENTER |
| Shape properties | gws slides update-shape <id> --object-id <obj-id> --background-color "#0000FF" |
| Reorder slides | gws slides reorder-slides <id> --slide-ids "slide1,slide2" --to 0 |
| Set slide background color | gws slides update-slide-background <id> --slide-number 1 --color "#005843" |
| Set slide background image | gws slides update-slide-background <id> --slide-number 1 --image-url "https://..." |
| List available layouts | gws slides list-layouts <id> |
| Add slide with custom layout | gws slides add-slide <id> --layout-id <layout-id> |
| Add a line | gws slides add-line <id> --slide-number 1 --start-x 50 --start-y 50 --end-x 300 --end-y 200 |
| Group elements | gws slides group <id> --object-ids "obj1,obj2,obj3" |
| Ungroup elements | gws slides ungroup <id> --group-id <group-id> |
| Get slide thumbnail | gws 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 intor--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, orall--color string— Hex color#RRGGBB--width float— Border width in points--style string—solid,dashed, ordotted
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, orCURVED(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
--quieton 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, thenupdate-text-stylefor font/color, thenupdate-paragraph-stylefor alignment update-shapesets fill and outline colors on shapes, not textupdate-text-stylesets font properties (bold, italic, size, color) on text within shapes
Gotchas & Workarounds
add-slide --layoutmay fail on presentations with custom slide masters; uselist-layoutsto get layout IDs andadd-slide --layout-idinsteadreplace-textoperates across ALL slides in the presentation — cannot target specific slides- Image URLs must be publicly accessible — Google Slides fetches them server-side
add-textinserts into shapes/text boxes or table cells; useadd-shape --type TEXT_BOXto 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 withupdate-text-style, (5) align withupdate-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:
gwsis 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
| Task | Command |
|---|---|
| List task lists | gws tasks lists |
| Get task list details | gws tasks list-info <tasklist-id> |
| Create a task list | gws tasks create-list --title "My List" |
| Update a task list | gws tasks update-list <tasklist-id> --title "New Name" |
| Delete a task list | gws tasks delete-list <tasklist-id> |
| List tasks | gws tasks list <tasklist-id> |
| List with completed | gws tasks list <tasklist-id> --show-completed |
| Get a task | gws tasks get <tasklist-id> <task-id> |
| Create a task | gws tasks create --title "Buy groceries" |
| Create with due date | gws tasks create --title "Report" --due "2024-02-01" |
| Update a task | gws tasks update <tasklist-id> <task-id> --title "New title" |
| Delete a task | gws tasks delete <tasklist-id> <task-id> |
| Complete a task | gws tasks complete <tasklist-id> <task-id> |
| Reopen a task | gws tasks reopen <tasklist-id> <task-id> |
| Move a task | gws tasks move <tasklist-id> <task-id> --previous <sibling-id> |
| Clear completed | gws 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 orYYYY-MM-DDformat
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 orYYYY-MM-DDformat
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 listsfirst to get task list IDs - Use
gws tasks list <tasklist-id>to get individual task IDs forget,update,delete,complete, andmovecommands - Use
gws tasks getto 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-completedto include them, orclearto permanently hide them - Use
move --destination-listto transfer tasks between lists,--parentto make subtasks,--previousto reorder - Use
--quieton create/update/delete/complete operations to suppress JSON output in scripts
Hooks 2
Sponsors
Details
- Marketplace
- omriariav/workspace-cli
- Category
- Community
