gws-gmail

name	gws-gmail
version	1.2.0
description	Google Gmail CLI operations via gws. Use when users need to list emails, read messages, send email, manage labels, drafts, attachments, batch operations, or trash messages. Triggers: gmail, email, inbox, send email, mail, labels, archive, trash, drafts, attachments.
metadata	{"short-description":"Google Gmail CLI operations","compatibility":"claude-code, codex-cli"}

Google Gmail (gws gmail)

gws gmail provides CLI access to Gmail with structured JSON output.

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

Dependency Check

Before executing any gws command, verify the CLI is installed:

gws version

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

Authentication

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

Quick Command Reference

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:[e-mail]"
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 [e-mail] --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 "[e-mail]"
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 [e-mail] --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 with gws gmail thread)
• message_id — Latest message ID (use with read, label, archive, trash)
• message_count — Number of messages in the thread

Flags:

• --max int — Maximum number of results (default 10, use --all for unlimited)
• --all — Fetch all matching results (may take time for large result sets)
• --query string — Gmail search query (e.g., is:unread, from:[e-mail])
• --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:[e-mail] 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 [e-mail] --subject "Meeting" --body "Let's meet at 3pm"
gws gmail send --to [e-mail] --cc [e-mail] --subject "Update" --body "Status update"
gws gmail send --to [e-mail] --subject "Report" --body "See attached" --attachment /tmp/report.pdf
gws gmail send --to [e-mail] --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 [e-mail]
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 "[e-mail]"
gws gmail forward 18abc123 --to "[e-mail],[e-mail]" --body "FYI"
gws gmail forward 18abc123 --to "[e-mail]" --cc "[e-mail]"

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 [e-mail] --subject "Draft" --body "Work in progress"
gws gmail create-draft --to [e-mail] --subject "Re: Topic" --thread-id thread123
gws gmail create-draft --to [e-mail] --subject "Draft" --body "See attached" --attachment /tmp/file.pdf

update-draft — Update a draft

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

Flags:

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

send-draft — Send an existing draft

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

Flags:

• --id string — Draft ID (required)

delete-draft — Delete a draft

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

Flags:

• --id string — Draft ID (required)

attachment — Download an attachment

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

Flags:

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

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

Examples:

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

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

links — Extract HTML anchor links from a message

gws gmail links <message-id>

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

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

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

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

Examples:

gws gmail links 18abc123 --format json

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

Tips for AI Agents

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