mail

cmdhub adapter

Gmail CLI
for cmdhub.

Messages, threads, drafts, labels, and attachments with command-level schema.

lock Auth: OAuth2

Quick Install cmdhub get gmail

data_object Agent Contract

Agents should start with auth/status and discovery commands, inspect schemas before composition, and treat commands marked as mutating as state-changing operations.

catalog.json Markdown

Output

Use human output for reading, `--json` for one object, and `--jsonl` for pipes.

Auth

Google OAuth. Used for Gmail messages, threads, drafts, labels, and attachments.

Refs

Prefer list/search, then short refs or piped JSONL. Use `resolve` to inspect cached refs.

Schemas

Use `gmail schema` and `catalog.json` to inspect fields, flags, examples, and side effects.

Auth scopes

openidemailprofilehttps://mail.google.com/

terminal Command Reference

Generated from source. Global flags apply to all commands.

Global Flags

--json bool Emit JSON machine output

--jsonl bool Emit JSONL records for piping

--output, -o string Compatibility output mode: json|jsonl. Prefer --json or --jsonl

--view string = summary View mode: summary|full

--profile string = default Config/auth profile

--config string Config path override

--quiet, -q bool Suppress non-essential diagnostics

--debug bool Enable debug diagnostics

--limit int = 50 Maximum items to emit

--page-size int = 50 Requested upstream page size

--cursor string Continuation cursor

--no-paginate bool Fetch only one page

--version, -v bool Print version information

gmail attachment Work with Gmail attachments

#cmd-gmail-attachment discovery safe

gmail attachment get Download a Gmail attachment

#cmd-gmail-attachment-get discovery safe

Download one Gmail attachment to a local file or emit its contents.

Pass –message-id and –attachment-id directly, or pipe one full message item that contains exactly one attachment. If the message contains multiple attachments, pass –attachment-id explicitly. With –message-id, a local attachment ref such as a1 is resolved within that message if it is not already cached. Use –emit-content to include a UTF-8 text preview and base64 payload in the command output for agent-visible verification.

--attachment-id string Gmail attachment id

--emit-content bool Include text/base64 content in the response

--message-id string Gmail message id

--output-file string Path to save the attachment

$ gmail attachment get

$ gmail attachment get --message-id m1 --attachment-id a1 --emit-content --json

$ gmail attachment get --message-id m1 --attachment-id a1 --output-file ./invoice.pdf

$ gmail message get m1

$ gmail message list --query 'has:attachment' --limit 1 --jsonl | gmail message get --json

gmail auth Manage Gmail authentication

#cmd-gmail-auth discovery safe

gmail auth logout Clear auth state

#cmd-gmail-auth-logout mutates state

$ gmail --profile work auth logout

$ gmail auth logout

$ gmail auth logout --help

gmail auth refresh Refresh stored token

#cmd-gmail-auth-refresh mutates state

$ gmail auth refresh

$ gmail auth refresh --help

$ gmail auth refresh --json

gmail auth status Show auth status

#cmd-gmail-auth-status discovery safe

$ gmail auth status

$ gmail auth status --help

$ gmail auth status --json

gmail auth whoami Return the authenticated Gmail address

#cmd-gmail-auth-whoami discovery safe

$ gmail auth whoami

$ gmail auth whoami --help

$ gmail auth whoami --json

gmail capabilities Describe capabilities

#cmd-gmail-capabilities discovery safe

$ gmail capabilities --help

gmail config Inspect local configuration

#cmd-gmail-config discovery safe

gmail config explain Explain resolved configuration

#cmd-gmail-config-explain discovery safe

$ gmail config explain --help

gmail doctor Run Gmail adapter diagnostics

#cmd-gmail-doctor discovery safe

$ gmail doctor

$ gmail doctor --help

$ gmail doctor --json

gmail draft Work with Gmail drafts

#cmd-gmail-draft discovery safe

gmail draft create Create a Gmail draft

#cmd-gmail-draft-create mutates state

Create a new Gmail draft.

Pass recipients with –to, then provide –subject and –body. Use repeated –attach flags to include local files.

--attach stringSlice = [] File path(s) to attach

--body string Draft body

--subject string Draft subject

--to string Comma-separated recipients

$ gmail draft create --help

$ gmail draft create --to alice@example.com --subject 'Status' --body 'Draft text'

$ gmail draft create --to alice@example.com,bob@example.com --subject 'Agenda' --body 'Attached.' --attach ./agenda.pdf

gmail draft delete Delete a draft

#cmd-gmail-draft-delete mutates state

Delete one Gmail draft.

The target may be a canonical draft id, a short ref such as d1, or one piped draft item.

--id string Draft id

$ gmail draft delete --help

$ gmail draft delete d1

$ gmail draft list --limit 1 --jsonl | gmail draft delete

gmail draft get Get a draft

#cmd-gmail-draft-get discovery safe

Get one Gmail draft.

The target may be a canonical draft id, a short ref such as d1, a shortened canonical id, or one piped draft item.

--id string Draft id

$ gmail draft get

$ gmail draft get d1

$ gmail draft list --limit 1 --jsonl | gmail draft get

gmail draft list List drafts

#cmd-gmail-draft-list discovery safe

List Gmail drafts and cache local draft references such as d1.

Use –query with Gmail search syntax to narrow drafts by subject, recipient, or tokens. Use –jsonl when the next step is another draft command such as get, send, or delete.

--query string Raw Gmail search query for drafts

$ gmail draft list

$ gmail draft list --limit 1 --jsonl | gmail draft get

$ gmail draft list --limit 1 --jsonl | gmail draft send

$ gmail draft list --limit 10

$ gmail draft list --limit 20 --json

$ gmail draft list --query 'subject:"Quarterly review"' --limit 1 --jsonl | gmail draft get

gmail draft send Send a draft

#cmd-gmail-draft-send mutates state

Send one Gmail draft.

The target may be a canonical draft id, a short ref such as d1, or one piped draft item from stdin.

--id string Draft id

$ gmail draft list --limit 1 --jsonl | gmail draft send

$ gmail draft send --help

$ gmail draft send d1

gmail draft update Update a draft

#cmd-gmail-draft-update mutates state

Update one Gmail draft.

The target may be a canonical draft id, a short ref such as d1, or one piped draft item. Omitted fields are preserved from the current draft.

--attach stringSlice = [] File path(s) to attach

--body string Draft body

--id string Draft id

--subject string Draft subject

--to string Comma-separated recipients

$ gmail draft list --limit 1 --jsonl | gmail draft update --subject 'Status'

$ gmail draft update --help

$ gmail draft update d1 --subject 'Status' --body 'Updated text'

gmail filter Manage simple Gmail filters

#cmd-gmail-filter discovery safe

gmail filter create Create a simple Gmail filter

#cmd-gmail-filter-create mutates state

--archive bool Skip inbox for matching mail

--from string Filter sender criteria

--important bool Mark matching mail important

--label string Comma-separated label IDs, names, or local refs to apply

--query string Provider-native Gmail filter query criteria

--read bool Mark matching mail read

--star bool Star matching mail

--subject string Filter subject criteria

--to string Filter recipient criteria

--yes bool Confirm filter creation

$ gmail filter create --from alerts@example.com --label cmdhub-demo --archive --yes

$ gmail filter create --help

$ gmail filter create --subject "cmdhub-demo" --star --yes

gmail filter delete Delete a Gmail filter

#cmd-gmail-filter-delete mutates state

--id string Gmail filter id or local ref

--yes bool Confirm filter deletion

$ gmail filter delete --help

$ gmail filter delete f1 --yes

gmail filter get Get a Gmail filter

#cmd-gmail-filter-get discovery safe

--id string Gmail filter id or local ref

$ gmail filter get

$ gmail filter get f1

gmail history Inspect Gmail mailbox history

#cmd-gmail-history discovery safe

gmail history list List Gmail history records from a known historyId

#cmd-gmail-history-list discovery safe

--history-type stringSlice = [] History type filter; repeat or comma-separate

--start-history-id string Gmail historyId from message/thread metadata

$ gmail history list

$ gmail history list --start-history-id 123456 --history-type messageAdded

gmail label Work with Gmail labels

#cmd-gmail-label mutates state

List Gmail labels and cache local label refs such as l1.

Use this before label add or label remove if you need to inspect available labels for the current mailbox.

gmail label create Create a user Gmail label

#cmd-gmail-label-create mutates state

--name string New user label name

$ gmail label create --help

$ gmail label create --name cmdhub-demo

gmail label delete Delete a user Gmail label

#cmd-gmail-label-delete mutates state

--id string Gmail label id, name, or local ref

--yes bool Confirm destructive label deletion

$ gmail label delete --help

$ gmail label delete l1 --yes

gmail label get Get a Gmail label

#cmd-gmail-label-get discovery safe

--id string Gmail label id, name, or local ref

$ gmail label get

$ gmail label get INBOX

$ gmail label get l1

gmail label list List Gmail labels

#cmd-gmail-label-list discovery safe

List Gmail labels for the active profile and cache local refs such as l1.

--query string Filter labels locally by name or id

$ gmail label list

$ gmail label list --json

$ gmail label search --query cmdhub

gmail label update Rename a user Gmail label

#cmd-gmail-label-update mutates state

--id string Gmail label id, name, or local ref

--name string Updated user label name

$ gmail label update --help

$ gmail label update l1 --name cmdhub-demo-done

gmail logout Clear auth state

#cmd-gmail-logout mutates state

$ gmail --profile work logout

$ gmail logout

gmail message Work with Gmail messages

#cmd-gmail-message discovery safe

Work with Gmail messages.

Use explicit subcommands such as list, get, reply, or archive. As a convenience, gmail message <message-id> is treated as gmail message get <message-id>.

$ gmail message list --query 'subject:"Quarterly review"' --limit 1 --jsonl

$ gmail message get m1

$ gmail message 19d8712e0a4159b7 --jsonl

gmail message archive Archive a message by removing INBOX

#cmd-gmail-message-archive mutates state

Archive one Gmail message.

The target may come from an explicit id, a short ref such as m1, or piped message items. Batch archive requires –all.

--all bool Confirm batch archive

--id string Gmail message id

$ gmail message archive --all m1 m2

$ gmail message archive --help

$ gmail message archive m1

$ gmail message list --unread --jsonl | gmail message archive --all

gmail message create Create a new Gmail message or draft

#cmd-gmail-message-create mutates state

Create a new Gmail message.

Pass –draft to save the message as a draft. Without –draft this command sends immediately.

--attach stringSlice = [] File path(s) to attach

--body string Message body

--draft bool Save as draft instead of sending

--subject string Message subject

--to string Comma-separated recipients

$ gmail message create --draft --to alice@example.com --subject 'Status' --body 'Save first'

$ gmail message create --help

$ gmail message create --to alice@example.com --subject 'Status' --body 'Send now'

gmail message delete Permanently delete a message

#cmd-gmail-message-delete mutates state

Permanently delete one Gmail message.

Use this carefully. The target may come from an explicit id, a short ref such as m1, or piped message items. Batch permanent delete requires –all –yes.

--all bool Confirm batch permanent delete

--id string Gmail message id

--yes bool Confirm destructive permanent delete

$ gmail message delete --all --yes m1 m2

$ gmail message delete --help

$ gmail message delete m1

gmail message forward Create a forward draft

#cmd-gmail-message-forward mutates state

Create a Gmail forward draft for one message.

The target may come from an explicit id, a short ref such as m1, or one piped message item. This command creates a draft rather than sending immediately.

--body string Forward body text

--id string Gmail message id

--to string Comma-separated recipients

$ gmail message forward --help

$ gmail message forward m1 --to bob@example.com --body 'Please review.'

$ gmail message list --query 'has:attachment' --limit 1 --jsonl | gmail message forward --to bob@example.com --body 'Please review.'

gmail message get Get a full message with parsed MIME content

#cmd-gmail-message-get discovery safe

Get one Gmail message in full detail.

The target may be:

a full Gmail message id
a stored short id such as 19d…9b7
a cached marker such as m1
one piped message item from stdin

If you already listed messages, prefer a short ref or piped jsonl instead of copying the full id. Use message get when you need the subject, parsed body, headers, or attachments for a message you just found with message list.

--id string Gmail message id

$ gmail message get

$ gmail message get 19d…9b7

$ gmail message get m1

$ gmail message list --query 'subject:"Quarterly review"' --limit 1 --jsonl | gmail message get

$ gmail message list --unread --limit 1 --jsonl | gmail message get

gmail message important Mark a message as important

#cmd-gmail-message-important discovery safe

--all bool Confirm batch important

--id string Gmail message id

$ gmail message important --help

$ gmail message important m1

gmail message label Modify Gmail labels

#cmd-gmail-message-label mutates state

Add or remove Gmail labels on one message.

List labels first if you need valid label refs, then pass the message target directly or via stdin.

gmail message label add Add labels to a message

#cmd-gmail-message-label-add mutates state

Add one or more Gmail labels to one message.

Pass –label with one or more Gmail label ids, names, or local refs such as l1. The target message may come from an explicit id, a short ref such as m1, or piped message items. Batch label changes require –all.

--all bool Confirm batch label add

--id string Gmail message id

--label string Comma-separated label IDs, names, or local refs to add

$ gmail label list

$ gmail message label add --all m1 m2 --label STARRED

$ gmail message label add --help

$ gmail message label add m1 --label l1

gmail message label remove Remove labels from a message

#cmd-gmail-message-label-remove mutates state

Remove one or more Gmail labels from one message.

--all bool Confirm batch label remove

--id string Gmail message id

--label string Comma-separated label IDs, names, or local refs to remove

$ gmail message label remove --all m1 m2 --label STARRED

$ gmail message label remove --help

$ gmail message label remove m1 --label l1

gmail message list List messages

#cmd-gmail-message-list discovery safe

List Gmail messages and cache local follow-up references.

Human output shows local markers such as m1 and shortened canonical ids. Use –jsonl when you want the results to feed directly into another gmail command. If you need message bodies, headers, or attachments, follow up with gmail message get rather than stopping at list output.

The most common next steps are:

gmail message get
gmail message reply
gmail message archive
gmail attachment get

--from string Filter by sender

--has-attachment bool Filter to messages with attachments

--in string Mailbox/search bucket, e.g. inbox, sent, trash

--include-spam-trash bool Include spam and trash in search results

--label string Comma-separated Gmail label IDs

--newer-than string Gmail relative time filter, e.g. 7d

--older-than string Gmail relative time filter, e.g. 30d

--query string Raw Gmail search query

--subject string Filter by subject terms

--to string Filter by recipient

--unread bool List unread messages only

$ gmail message list

$ gmail message list --from alice@example.com --limit 10

$ gmail message list --query 'has:attachment newer_than:7d' --limit 10

$ gmail message list --query 'subject:"Quarterly review"' --limit 1 --jsonl | gmail message get

$ gmail message list --unread --limit 1 --jsonl | gmail message get

$ gmail message list --unread --limit 10

gmail message not-important Remove important marker from a message

#cmd-gmail-message-not-important discovery safe

--all bool Confirm batch not-important

--id string Gmail message id

$ gmail message not-important --help

$ gmail message not-important m1

gmail message read Mark a message as read

#cmd-gmail-message-read mutates state

Mark one Gmail message as read.

The target may come from an explicit id, a short ref such as m1, or piped message items. Batch read marking requires –all.

--all bool Confirm batch read marking

--id string Gmail message id

$ gmail message list --unread --jsonl | gmail message read --all

$ gmail message read --all m1 m2

$ gmail message read --help

$ gmail message read m1

gmail message reply Send or draft a reply

#cmd-gmail-message-reply mutates state

Send or draft a Gmail reply for one message.

The target may come from an explicit id, a short ref such as m1, or one piped message item. Pass –draft to save the reply as a draft. Without –draft this command sends immediately.

--all bool Reply to all recipients

--body string Reply body text

--draft bool Save as draft instead of sending

--id string Gmail message id

$ gmail message list --query 'from:alice@example.com' --limit 1 --jsonl | gmail message reply --body 'Received.'

$ gmail message reply --help

$ gmail message reply m1 --body 'Looping everyone in.' --all

$ gmail message reply m1 --body 'Thanks, I will review this.'

$ gmail message reply m1 --draft --body 'Holding this for review.'

gmail message star Star a message

#cmd-gmail-message-star discovery safe

--all bool Confirm batch star

--id string Gmail message id

$ gmail message list --query cmdhub-demo --jsonl | gmail message star --all

$ gmail message star --help

$ gmail message star m1

gmail message trash Move a message to trash

#cmd-gmail-message-trash mutates state

Move one Gmail message to trash.

The target may come from an explicit id, a short ref such as m1, or piped message items. Batch trash requires –all.

--all bool Confirm batch trash

--id string Gmail message id

$ gmail message trash --all m1 m2

$ gmail message trash --help

$ gmail message trash m1

gmail message unread Mark a message as unread

#cmd-gmail-message-unread mutates state

Mark one Gmail message as unread.

The target may come from an explicit id, a short ref such as m1, or piped message items. Batch unread marking requires –all.

--all bool Confirm batch unread marking

--id string Gmail message id

$ gmail message unread --all m1 m2

$ gmail message unread --help

$ gmail message unread m1

gmail message unstar Remove star from a message

#cmd-gmail-message-unstar discovery safe

--all bool Confirm batch unstar

--id string Gmail message id

$ gmail message unstar --help

$ gmail message unstar m1

gmail message untrash Restore a message from trash

#cmd-gmail-message-untrash mutates state

Restore one Gmail message from trash.

The target may come from an explicit id, a short ref such as m1, or piped message items. Batch restore requires –all.

--all bool Confirm batch untrash

--id string Gmail message id

$ gmail message untrash --all m1 m2

$ gmail message untrash --help

$ gmail message untrash m1

gmail profile Manage provider profiles

#cmd-gmail-profile discovery safe

gmail profile create Create an unauthenticated provider profile

#cmd-gmail-profile-create mutates state

$ gmail profile create --help

gmail profile delete Delete a local provider profile

#cmd-gmail-profile-delete mutates state

$ gmail profile delete --help

gmail profile list List provider profiles

#cmd-gmail-profile-list discovery safe

$ gmail profile list --help

gmail profile rename Rename a local provider profile

#cmd-gmail-profile-rename discovery safe

$ gmail profile rename --help

gmail profile use Set the default provider profile

#cmd-gmail-profile-use mutates state

$ gmail profile use --help

gmail resolve Resolve a local marker or stored short reference

#cmd-gmail-resolve discovery safe

Resolve a Gmail short reference into its canonical payload.

Use this when you have a marker such as m1, t1, d1, l1, or u1, or a stored short id such as 19d…9b7, and want to inspect what it refers to.

Resolution is profile-scoped. If a marker does not resolve, verify –profile and rerun the relevant list command.

$ gmail resolve --help

$ gmail resolve 19d…9b7

$ gmail resolve m1

$ gmail resolve t1

$ gmail resolve u1

gmail schema Emit Gmail adapter schema hints

#cmd-gmail-schema discovery safe

Show schema hints for the Gmail resource payloads emitted or accepted by this CLI.

Use this when you need to understand the shape of structured output for follow-up automation or parsing.

--in bool Show input schema

--out bool Show output schema

$ gmail schema

$ gmail schema --help

$ gmail schema draft.create --in --json

$ gmail schema message.get --out --json

gmail send-as Inspect Gmail send-as aliases

#cmd-gmail-send-as discovery safe

gmail send-as get Get one send-as alias

#cmd-gmail-send-as-get discovery safe

$ gmail send-as get

$ gmail send-as get me@example.com

gmail send-as list List verified sender aliases

#cmd-gmail-send-as-list discovery safe

$ gmail send-as list

$ gmail send-as list --json

gmail thread Work with Gmail threads

#cmd-gmail-thread discovery safe

gmail thread archive Archive a thread by removing INBOX from existing messages

#cmd-gmail-thread-archive mutates state

--all bool Confirm batch thread mutation

--id string Gmail thread id

$ gmail thread archive --help

$ gmail thread archive t1

gmail thread delete Permanently delete a thread

#cmd-gmail-thread-delete mutates state

--all bool Confirm batch permanent delete

--id string Gmail thread id

--yes bool Confirm destructive permanent delete

$ gmail thread delete --all --yes t1 t2

$ gmail thread delete --help

$ gmail thread delete t1 --yes

gmail thread get Get a full thread

#cmd-gmail-thread-get discovery safe

Get one Gmail thread in full detail.

The target may be a canonical thread id, a short ref such as t1, a shortened canonical id, or one piped thread item.

--id string Gmail thread id

$ gmail thread get

$ gmail thread get t1

$ gmail thread list --limit 1 --jsonl | gmail thread get

gmail thread important Mark existing messages in a thread as important

#cmd-gmail-thread-important discovery safe

--all bool Confirm batch thread mutation

--id string Gmail thread id

$ gmail thread important --help

$ gmail thread important t1

gmail thread list List threads

#cmd-gmail-thread-list discovery safe

List Gmail threads and cache local thread references such as t1.

Use this when you want to act on conversation-level results rather than individual messages. Use –jsonl when the next step should consume one thread item from stdin.

--from string Filter by sender

--has-attachment bool Filter to threads with attachments

--in string Mailbox/search bucket, e.g. inbox, sent, trash

--include-spam-trash bool Include spam and trash in search results

--label string Comma-separated Gmail label IDs

--newer-than string Gmail relative time filter, e.g. 7d

--older-than string Gmail relative time filter, e.g. 30d

--query string Raw Gmail search query

--subject string Filter by subject terms

--to string Filter by recipient

--unread bool List unread threads only

$ gmail thread list

$ gmail thread list --query 'label:IMPORTANT' --limit 1 --jsonl | gmail thread get

$ gmail thread list --query 'label:IMPORTANT' --limit 1 --jsonl | gmail thread reply --body 'Following up here.'

$ gmail thread list --subject invoice --limit 10

gmail thread not-important Remove important from existing messages in a thread

#cmd-gmail-thread-not-important discovery safe

--all bool Confirm batch thread mutation

--id string Gmail thread id

$ gmail thread not-important --help

$ gmail thread not-important t1

gmail thread read Mark a thread as read

#cmd-gmail-thread-read mutates state

--all bool Confirm batch thread mutation

--id string Gmail thread id

$ gmail thread read --help

$ gmail thread read t1

gmail thread reply Send or draft a reply to the latest message in a thread

#cmd-gmail-thread-reply mutates state

Send or draft a Gmail reply using the latest message in a thread.

This is useful when your workflow is organized around conversation results from thread list rather than message list. Pass –draft to save the reply as a draft. Without –draft this command sends immediately.

--all bool Reply to all recipients

--body string Reply body text

--draft bool Save as draft instead of sending

--id string Gmail thread id

$ gmail thread list --query 'label:IMPORTANT' --limit 1 --jsonl | gmail thread reply --body 'Following up here.'

$ gmail thread reply --help

$ gmail thread reply t1 --body 'Following up here.'

$ gmail thread reply t1 --draft --body 'Holding this for review.'

gmail thread star Star existing messages in a thread

#cmd-gmail-thread-star discovery safe

--all bool Confirm batch thread mutation

--id string Gmail thread id

$ gmail thread star --help

$ gmail thread star t1

gmail thread trash Move a thread to trash

#cmd-gmail-thread-trash mutates state

--all bool Confirm batch thread trash

--id string Gmail thread id

$ gmail thread search --query cmdhub-demo --jsonl | gmail thread trash --all

$ gmail thread trash --help

$ gmail thread trash t1

gmail thread unread Mark a thread as unread

#cmd-gmail-thread-unread mutates state

--all bool Confirm batch thread mutation

--id string Gmail thread id

$ gmail thread unread --help

$ gmail thread unread t1

gmail thread unstar Unstar existing messages in a thread

#cmd-gmail-thread-unstar discovery safe

--all bool Confirm batch thread mutation

--id string Gmail thread id

$ gmail thread unstar --help

$ gmail thread unstar t1

gmail thread untrash Restore a thread from trash

#cmd-gmail-thread-untrash mutates state

--all bool Confirm batch thread restore

--id string Gmail thread id

$ gmail thread untrash --help

$ gmail thread untrash t1

gmail vacation Manage Gmail vacation responder

#cmd-gmail-vacation discovery safe

gmail vacation disable Disable vacation responder

#cmd-gmail-vacation-disable discovery safe

--yes bool Confirm vacation responder disable

$ gmail vacation disable --help

$ gmail vacation disable --yes

gmail vacation get Get vacation responder settings

#cmd-gmail-vacation-get discovery safe

$ gmail vacation get

$ gmail vacation get --json

gmail vacation update Enable or update vacation responder settings

#cmd-gmail-vacation-update mutates state

--body string Vacation responder plain-text body

--contacts-only bool Restrict replies to contacts

--domain-only bool Restrict replies to domain

--end string Optional provider end time

--start string Optional provider start time

--subject string Vacation responder subject

--yes bool Confirm vacation responder update

$ gmail vacation update --help

$ gmail vacation update --subject "Out of office" --body "Back Monday" --yes

gmail version Show gmail version information

#cmd-gmail-version discovery safe

$ gmail version --help

play_circle Live Examples

Output captured from a real workspace. Regenerate with scripts/gen-docs.sh --update.

auth

Check current identity Returns the active Gmail address.

$ gmail auth whoami

Authenticated as kestrelphilip@gmail.com

Next steps:
- Messages:     gmail message list --limit 10
- Drafts:       gmail draft list --limit 10
- Capabilities: gmail capabilities

messages

List recent messages Lists inbox messages and assigns short message refs.

$ gmail message list --limit 5

REF  TITLE                                                                                                                                      STATUS  WHEN                             OWNER
m1   A new device logged into your account                                                                                                      unread  Sat, 30 May 2026 07:45:31 +0000  Notion Team <notify@updates.notion.so>
m2   Declined: Location Timezone Target {id}... @ Tue Jun 2, 2026 10am - 10:30am (GMT+2) (kestrelphilip@gmail.com)  unread  Fri, 29 May 2026 06:48:47 +0000  Philip Sterne <sterne@gmail.com>
m3   Declined: Location Timezone Target {id} @ Tue Jun 2, 2026 10am - 10:30am (GMT+2) (kestrelphilip@gmail.com)      unread  Fri, 29 May 2026 06:48:44 +0000  Philip Sterne <sterne@gmail.com>
m4   Declined: Location Timezone Target {id} @ Tue Jun 2, 2026 10am - 10:30am (GMT+2) (kestrelphilip@gmail.com)   unread  Fri, 29 May 2026 06:48:43 +0000  Philip Sterne <sterne@gmail.com>
m5   Declined: Location Timezone Target {id} @ Tue Jun 2, 2026 10am - 10:30am (GMT+2) (kestrelphilip@gmail.com)      unread  Fri, 29 May 2026 06:48:42 +0000  Philip Sterne <sterne@gmail.com>

Next steps:
- More:     gmail message list --limit 5 --cursor c1
- Open:     gmail message get m1
- Messages: gmail message list --limit 10
- Drafts:   gmail draft list --limit 10

Get a message Returns subject, sender, date, and body snippet.

$ gmail message get m1

NOT_FOUND: message reference "m1" was not found Next steps: - List: gmail message list --limit 10 - Resolve: gmail resolve <reference> - Help: gmail message --help exit status 50

threads

List recent threads Lists conversation threads and assigns thread refs.

$ gmail thread list --limit 3

REF  TITLE                                                                                                                                      STATUS      WHEN                             OWNER
t1   A new device logged into your account                                                                                                      1 messages  Sat, 30 May 2026 07:45:31 +0000  Notion Team <notify@updates.notion.so>
t2   Declined: Location Timezone Target {id}... @ Tue Jun 2, 2026 10am - 10:30am (GMT+2) (kestrelphilip@gmail.com)  1 messages  Fri, 29 May 2026 06:48:47 +0000  Philip Sterne <sterne@gmail.com>
t3   Declined: Location Timezone Target {id} @ Tue Jun 2, 2026 10am - 10:30am (GMT+2) (kestrelphilip@gmail.com)      2 messages  Fri, 29 May 2026 06:48:44 +0000  Philip Sterne <sterne@gmail.com>

Next steps:
- More:     gmail thread list --limit 3 --cursor c1
- Open:     gmail thread get t1
- Messages: gmail message list --limit 10
- Drafts:   gmail draft list --limit 10

Get a thread Returns all messages in a conversation thread.

$ gmail thread get t1

NOT_FOUND: thread reference "t1" was not found Next steps: - List: gmail thread list --limit 10 - Resolve: gmail resolve <reference> - Help: gmail thread --help exit status 50

labels

List mailbox labels Returns Gmail system and user-created labels.

$ gmail label list

REF  TITLE
l1   CHAT
l2   SENT
l3   INBOX
l4   IMPORTANT
l5   TRASH
l6   DRAFT
l7   SPAM
l8   CATEGORY_FORUMS
l9   CATEGORY_UPDATES
l10  CATEGORY_PERSONAL
l11  {id}
l12  CATEGORY_SOCIAL
l13  STARRED
l14  UNREAD

Next steps:
- Open:         gmail label get l1
- Messages:     gmail message list --limit 10
- Drafts:       gmail draft list --limit 10
- Capabilities: gmail capabilities

drafts

List drafts Lists unsent draft messages.

$ gmail draft list

REF  TITLE                         STATUS  WHEN                             OWNER
d1   cmdhub-eval-draft             draft   Tue, 26 May 2026 11:37:20 -0500  test@example.com
d2   {id}        draft   Tue, 26 May 2026 12:31:26 -0400  kestrelphilip@gmail.com
d3   Re: Join your team on Notion  draft   Thu, 23 Apr 2026 09:40:22 -0500  Notion Team <notify@updates.notion.so>

Next steps:
- Open:         gmail draft get d1
- Messages:     gmail message list --limit 10
- Drafts:       gmail draft list --limit 10
- Capabilities: gmail capabilities

alt_route Composition Patterns

Bridge your ecosystem with zero middleware.

# Inspect one message and then hand it to an agent transform
gmail message list --label INBOX --limit 1 --jsonl \
  | agent adapt --to "gcal event create"

Gmail CLIfor cmdhub.

data_object Agent Contract

Output

Auth

Refs

Schemas

Auth scopes

terminal Command Reference

Global Flags

play_circle Live Examples

auth

messages

threads

labels

drafts

alt_route Composition Patterns

Gmail CLI
for cmdhub.