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

terminal Command Reference

Generated from source. Global flags apply to all commands.

Global Flags

--config string Config path override
--cursor string Continuation cursor
--debug bool Enable debug diagnostics
--json bool Alias for --output json
--jsonl bool Alias for --output jsonl
--limit int = 50 Maximum items to emit
--no-paginate bool Fetch only one page
--output, -o string = human Output mode: human|json|jsonl
--page-size int = 50 Requested upstream page size
--profile string = default Config/auth profile
--quiet, -q bool Suppress non-essential diagnostics
--trace-id string Trace identifier
--view string = summary View mode: summary|full

gmail attachment — Work with Gmail attachments

gmail attachment get Download a Gmail attachment
--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 --message-id m1 --attachment-id a1 --output-file ./invoice.pdf
$ gmail attachment get --message-id m1 --attachment-id a1 --emit-content --output json
$ gmail message get m1
$ gmail message list --query 'has:attachment' --limit 1 --output jsonl | gmail message get --output json

gmail auth — Manage Gmail authentication

gmail auth login Start Gmail OAuth login
$ gmail auth login
$ gmail --profile work auth login
gmail auth logout Clear auth state
$ gmail auth logout
$ gmail --profile work auth logout
gmail auth refresh Refresh stored token
$ gmail auth refresh
$ gmail auth refresh --output json
gmail auth status Show auth status
$ gmail auth status
$ gmail auth status --output json
gmail auth whoami Return the authenticated Gmail address
$ gmail auth whoami
$ gmail auth whoami --output json
gmail capabilities Describe Gmail adapter capabilities
gmail doctor Run Gmail adapter diagnostics

gmail draft — Work with Gmail drafts

gmail draft create Create a Gmail draft
--attach stringSlice = [] File path(s) to attach
--body string Draft body
--subject string Draft subject
--to string Comma-separated recipients
$ 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
--id string Draft id
$ gmail draft delete d1
$ gmail draft list --limit 1 --output jsonl | gmail draft delete
gmail draft get Get a draft
--id string Draft id
$ gmail draft get d1
$ gmail draft list --limit 1 --output jsonl | gmail draft get
gmail draft list List drafts
$ gmail draft list --limit 10
$ gmail draft list --limit 1 --output jsonl | gmail draft get
$ gmail draft list --limit 1 --output jsonl | gmail draft send
$ gmail draft list --limit 20 --output json
gmail draft send Send a draft
--id string Draft id
$ gmail draft send d1
$ gmail draft list --limit 1 --output jsonl | gmail draft send
gmail draft update Update a 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 update d1 --to alice@example.com --subject 'Status' --body 'Updated text'
$ gmail draft list --limit 1 --output jsonl | gmail draft update --to alice@example.com --subject 'Status' --body 'Updated text'

gmail label — Work with Gmail labels

gmail label list List Gmail labels
$ gmail label list
$ gmail label list --output json

gmail message — Work with Gmail messages

gmail message archive Archive a message by removing INBOX
--id string Gmail message id
$ gmail message archive m1
$ gmail message list --unread --limit 1 --output jsonl | gmail message archive
gmail message create Send a new email message
--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 --to sterne@gmail.com --subject 'How are you?' --body 'Long time, no chat!'
$ gmail message create --to sterne@gmail.com --subject 'How are you?' --body 'Long time, no chat!' --draft
gmail message delete Permanently delete a message
--id string Gmail message id
$ gmail message delete m1
gmail message forward Create a forward draft
--body string Forward body text
--id string Gmail message id
--to string Comma-separated recipients
$ gmail message forward m1 --to bob@example.com --body 'Please review.'
$ gmail message list --query 'has:attachment' --limit 1 --output jsonl | gmail message forward --to bob@example.com --body 'Please review.'
gmail message get Get a full message with parsed MIME content
--id string Gmail message id
$ gmail message get m1
$ gmail message get 19d…9b7
$ gmail message list --unread --limit 1 --output jsonl | gmail message get
$ gmail message list --query 'subject:"Quarterly review"' --limit 1 --output jsonl | gmail message get
gmail message label Modify Gmail labels
gmail message list List messages
--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 --unread --limit 10
$ 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 --output jsonl | gmail message get
$ gmail message list --unread --limit 1 --output jsonl | gmail message get
gmail message read Mark a message as read
--id string Gmail message id
$ gmail message read m1
$ gmail message list --unread --limit 1 --output jsonl | gmail message read
gmail message reply Send a reply
--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 reply m1 --body 'Thanks, I will review this.'
$ gmail message list --query 'from:alice@example.com' --limit 1 --output jsonl | gmail message reply --body 'Received.'
$ gmail message reply m1 --body 'Looping everyone in.' --all
$ gmail message reply m1 --body 'Holding this for review.' --draft
gmail message trash Move a message to trash
--id string Gmail message id
$ gmail message trash m1
gmail message unread Mark a message as unread
--id string Gmail message id
$ gmail message unread m1
gmail message untrash Restore a message from trash
--id string Gmail message id
$ gmail message untrash m1
gmail resolve Resolve a local marker or stored short reference
gmail schema Emit Gmail adapter schema hints
--in bool Show input schema
--out bool Show output schema

gmail thread — Work with Gmail threads

gmail thread get Get a full thread
--id string Gmail thread id
$ gmail thread get t1
$ gmail thread list --limit 1 --output jsonl | gmail thread get
gmail thread list List threads
--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 --subject invoice --limit 10
$ gmail thread list --query 'label:IMPORTANT' --limit 1 --output jsonl | gmail thread get
$ gmail thread list --query 'label:IMPORTANT' --limit 1 --output jsonl | gmail thread reply --body 'Following up here.'
gmail thread reply Send a reply to the latest message in a thread
--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 reply t1 --body 'Following up here.'
$ gmail thread list --query 'label:IMPORTANT' --limit 1 --output jsonl | gmail thread reply --body 'Following up here.'
$ gmail thread reply t1 --body 'Holding this for review.' --draft
gmail version Show gmail version information

play_circle Live Examples

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

auth

Check current identity
$ gmail auth whoami
Mailbox: kestrelphilip@gmail.com
Messages: 11
Threads: 10

Stuck? Try `gmail message list --limit 10`

messages

List recent messages
$ gmail message list --limit 5
m1:  This is a test [kestrelphilip@gmail.com | 18h ago | SENT]
m2:  Re: Join your team on Notion [kestrelphilip@gmail.com | 1d ago | DRAFT]
m3:  Join your team on Notion [Notion Team <notify@updates.notion.so> | 8d ago | INBOX]
m4:  Security alert [Google <no-reply@accounts.google.com> | 9d ago | UNREAD, INBOX]
m5:  intent-cli exercise 1776087722 updated [kestrelphilip@gmail.com | 11d ago | SENT]

Stuck? Try `gmail message get m1`
Get a message
$ gmail message get m1
Message 19dbf6…
Subject: This is a test
From: kestrelphilip@gmail.com
To: sterne@gmail.com
Date: Fri, 24 Apr 2026 07:20:21 -0500
Labels: SENT

Guess it worked :-)

Attachments: none

Stuck? Try `gmail message reply 19dbf6… --body 'Received.'`

threads

List recent threads
$ gmail thread list --limit 3
t1:  This is a test [1 messages | kestrelphilip@gmail.com | 18h ago]
t2:  Join your team on Notion [2 messages | kestrelphilip@gmail.com | 1d ago]
t3:  Security alert [1 messages | Google <no-reply@accounts.google.com> | 9d ago]

Stuck? Try `gmail thread get t1`
Get a thread
$ gmail thread get t1
Thread 19dbf6… (1 messages)

Message 19dbf6…
Subject: This is a test
From: kestrelphilip@gmail.com
To: sterne@gmail.com
Date: Fri, 24 Apr 2026 07:20:21 -0500
Labels: SENT

Guess it worked :-)

Attachments: none

Stuck? Try `gmail thread reply 19dbf6… --body 'Following up here.'`

labels

List mailbox labels
$ gmail label list
l1:  CHAT [system | msg:hide | label:labelHide]
l2:  SENT [system]
l3:  INBOX [system]
l4:  IMPORTANT [system | msg:hide | label:labelHide]
l5:  TRASH [system | msg:hide | label:labelHide]
l6:  DRAFT [system]
l7:  SPAM [system | msg:hide | label:labelHide]
l8:  CATEGORY_FORUMS [system | msg:hide | label:labelHide]
l9:  CATEGORY_UPDATES [system | msg:hide | label:labelHide]
l10:  CATEGORY_PERSONAL [system | msg:hide | label:labelHide]
l11:  CATEGORY_PROMOTIONS [system | msg:hide | label:labelHide]
l12:  CATEGORY_SOCIAL [system | msg:hide | label:labelHide]
l13:  STARRED [system]
l14:  UNREAD [system]

Stuck? Try `gmail message list --label INBOX --limit 10`

drafts

List drafts
$ gmail draft list
d1:  Re: Join your team on Notion [Notion Team <notify@updates.notion.so> | 1d ago]

Stuck? Try `gmail draft get d1`

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 --output jsonl \
  | agent adapt --to "gcal event create"