菜单
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.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Google Chat CLI operations via gws. Use when users need to list/create/manage chat spaces, read/send messages, manage members, track read state, handle attachments, or monitor space events. Triggers: google chat, gchat, chat spaces, chat messages.
Google Drive CLI operations via gws. Use when users need to list, search, upload, download, manage files/folders, permissions, approvals, revisions, comments, shared drives, and more. Triggers: drive, files, upload, download, folders, google drive, file management, permissions, approvals, share, shared drives.
Google Chat CLI operations via gws. Use when users need to list/create/manage chat spaces, read/send messages, manage members, track read state, handle attachments, or monitor space events. Triggers: google chat, gchat, chat spaces, chat messages.
Google Drive CLI operations via gws. Use when users need to list, search, upload, download, manage files/folders, permissions, approvals, revisions, comments, shared drives, and more. Triggers: drive, files, upload, download, folders, google drive, file management, permissions, approvals, share, shared drives.
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.
Google Contacts CLI operations via gws. Use when users need to list, search, view, create, or delete contacts. Triggers: contacts, google contacts, people api, contact management.
| 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"} |
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.
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
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.
| 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 |
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 threadFlags:
--max int — Maximum number of results (default 10, use --all for unlimited)--all — Fetch all matching results (may take time for large result sets)--query string — Gmail search query (e.g., is:unread, from:someone@example.com)--include-labels — Include Gmail label IDs in the output for each threadExamples:
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
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.
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
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
gws gmail labels
Lists all Gmail labels in the account, including system labels (INBOX, SENT, etc.) and user-created 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"
gws gmail archive <message-id>
Archives a Gmail message by removing the INBOX label. The message remains accessible via search and labels.
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.
gws gmail trash <message-id>
Moves a Gmail message to the trash. Messages in trash are permanently deleted after 30 days.
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 recipientsExamples:
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
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"
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
gws gmail list --format json # Structured JSON (default)
gws gmail list --format yaml # YAML format
gws gmail list --format text # Human-readable text
gws gmail untrash <message-id>
Removes a Gmail message from the trash, restoring it to its previous location.
gws gmail delete <message-id>
Permanently deletes a Gmail message. This action cannot be undone.
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"
gws gmail batch-delete --ids <comma-separated-ids>
Flags:
--ids string — Comma-separated message IDs (required)gws gmail trash-thread <thread-id>
Moves all messages in a Gmail thread to the trash.
gws gmail untrash-thread <thread-id>
Removes all messages in a Gmail thread from the trash.
gws gmail delete-thread <thread-id>
Permanently deletes all messages in a Gmail thread. This action cannot be undone.
gws gmail label-info --id <label-id>
Flags:
--id string — Label ID (required)Returns detailed information including message/thread counts and visibility settings.
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, labelHideExamples:
gws gmail create-label --name "ProjectX"
gws gmail create-label --name "Archive/2024" --visibility labelHide
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, labelHidegws gmail delete-label --id <label-id>
Flags:
--id string — Label ID (required)Permanently deletes a Gmail label. Messages with this label are not deleted.
gws gmail drafts [flags]
Flags:
--max int — Maximum number of results (default 10)--query string — Gmail search querygws gmail draft --id <draft-id>
Flags:
--id string — Draft ID (required)Returns full draft content including headers and body.
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
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)gws gmail send-draft --id <draft-id>
Flags:
--id string — Draft ID (required)gws gmail delete-draft --id <draft-id>
Flags:
--id string — Draft ID (required)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
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 the tab query parameter, e.g. t.0All 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"
--format json (the default) for programmatic parsinggws gmail list to get IDs: message_id for read/label/archive/trash, thread_id for threadgws gmail thread <thread-id> to view full conversations with all messagesis:, from:, to:, subject:, after:, before:, has:, label:gws gmail labels first to see available label names and IDsgws gmail label <id> --remove "INBOX"gws gmail archive-thread <thread-id> to archive all messages in a conversation at once (archives + marks read)gws gmail label <id> --remove "UNREAD"gws gmail label <id> --add "STARRED"--include-labels with list to see which Gmail labels are applied to each thread--all with list to fetch every matching result (bypasses the default 10 limit)--quiet on any command to suppress JSON output (useful for scripted archive/label actions)