# Gmail CLI

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

## Install

```bash
cmdhub get gmail
```

## Authentication

OAuth2

## Agent-Readable Catalog

- Machine-readable command catalog: `/cli/gmail/catalog.json`
- Stable command anchors use the `cmd-...` IDs listed under each command.
- Inspect this catalog before planning tool use for command paths, examples, flags, mutation markers, and dry-run support.

## Overview

```bash
# 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"
```

## CLI Overview

Gmail adapter CLI

Work with Gmail messages, threads, drafts, labels, and attachments.

The intended workflow is:
- list first
- follow up with a short ref such as m1 or t1, or pipe jsonl into the next command
- use resolve when you need to inspect what a short ref expands to

Use --jsonl for self-pipe flows such as:
  gmail message list --unread --limit 1 --jsonl | gmail message get
  gmail draft list --limit 1 --jsonl | gmail draft get

## Generated Coverage

- Command groups: `19`
- Total documented command nodes: `83`
- Live examples: `7`
- Lifecycle surfaces: `auth`, `doctor`, `capabilities`, `schema`, `resolve`, `version`
- Machine-readable output: `--json`, `--jsonl`
- Human views: `summary`, `full`

## Auth Contract

- Auth mode: OAuth2
- Provider permission model: Google OAuth
- Auth scopes: `openid`, `email`, `profile`, `https://mail.google.com/`
- Scope note: Used for Gmail messages, threads, drafts, labels, and attachments.
- Standard commands: `auth login`, `auth logout`, `auth refresh`, `auth status`, `auth whoami`
- `auth status --json` reports `tool`, `profile`, `provider`, `authenticated`, and `suggested_next_step`.
- `auth whoami --json` is the stable way to answer identity questions.

## Agent Safety Notes

- Discovery commands such as `list`, `search`, `get`, `resolve`, `schema`, `doctor`, `capabilities`, `status`, and `whoami` are the safest commands to run first.
- Treat commands marked as mutating as state-changing local or provider operations.
- Mutating command paths: `gmail auth login`, `gmail auth logout`, `gmail auth refresh`, `gmail draft create`, `gmail draft delete`, `gmail draft send`, `gmail draft update`, `gmail filter create`, `gmail filter delete`, `gmail label`, `gmail label create`, `gmail label delete`, `gmail label update`, `gmail login`, `gmail logout`, `gmail message archive`, `gmail message create`, `gmail message delete`, `gmail message forward`, `gmail message label`, `gmail message label add`, `gmail message label remove`, `gmail message read`, `gmail message reply`, `gmail message trash`, `gmail message unread`, `gmail message untrash`, `gmail profile create`, `gmail profile delete`, `gmail profile use`, `gmail thread archive`, `gmail thread delete`, `gmail thread read`, `gmail thread reply`, `gmail thread trash`, `gmail thread unread`, `gmail thread untrash`, `gmail vacation update`
- No generated `--dry-run` flag was detected for this CLI. Use discovery commands before mutating commands.

## Global Flags

- `--json` (bool): Emit JSON machine output
- `--jsonl` (bool): Emit JSONL records for piping
- `--output` (string): Compatibility output mode: json|jsonl. Prefer --json or --jsonl
- `--view` (string): View mode: summary|full Default: `summary`.
- `--profile` (string): Config/auth profile Default: `default`.
- `--config` (string): Config path override
- `--quiet` (bool): Suppress non-essential diagnostics
- `--debug` (bool): Enable debug diagnostics
- `--limit` (int): Maximum items to emit Default: `50`.
- `--page-size` (int): Requested upstream page size Default: `50`.
- `--cursor` (string): Continuation cursor
- `--no-paginate` (bool): Fetch only one page
- `--version` (bool): Print version information

## Command Reference

### `gmail attachment`

- Anchor: `cmd-gmail-attachment`
- Mutates state: `no`
- Supports dry run: `no`

Work with Gmail attachments

#### `gmail attachment get`

- Anchor: `cmd-gmail-attachment-get`
- Mutates state: `no`
- Supports dry run: `no`

Download a Gmail attachment

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.

Example:

```bash
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
```

Flags:

- `--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 auth`

- Anchor: `cmd-gmail-auth`
- Mutates state: `no`
- Supports dry run: `no`

Manage Gmail authentication

#### `gmail auth login`

- Anchor: `cmd-gmail-auth-login`
- Mutates state: `yes`
- Supports dry run: `no`

Start Gmail OAuth login

Example:

```bash
gmail --profile work auth login
gmail auth login
gmail auth login --help
```

#### `gmail auth logout`

- Anchor: `cmd-gmail-auth-logout`
- Mutates state: `yes`
- Supports dry run: `no`

Clear auth state

Example:

```bash
gmail --profile work auth logout
gmail auth logout
gmail auth logout --help
```

#### `gmail auth refresh`

- Anchor: `cmd-gmail-auth-refresh`
- Mutates state: `yes`
- Supports dry run: `no`

Refresh stored token

Example:

```bash
gmail auth refresh
gmail auth refresh --help
gmail auth refresh --json
```

#### `gmail auth status`

- Anchor: `cmd-gmail-auth-status`
- Mutates state: `no`
- Supports dry run: `no`

Show auth status

Example:

```bash
gmail auth status
gmail auth status --help
gmail auth status --json
```

#### `gmail auth whoami`

- Anchor: `cmd-gmail-auth-whoami`
- Mutates state: `no`
- Supports dry run: `no`

Return the authenticated Gmail address

Example:

```bash
gmail auth whoami
gmail auth whoami --help
gmail auth whoami --json
```

### `gmail capabilities`

- Anchor: `cmd-gmail-capabilities`
- Mutates state: `no`
- Supports dry run: `no`

Describe capabilities

Example:

```bash
gmail capabilities --help
```

### `gmail config`

- Anchor: `cmd-gmail-config`
- Mutates state: `no`
- Supports dry run: `no`

Inspect local configuration

#### `gmail config explain`

- Anchor: `cmd-gmail-config-explain`
- Mutates state: `no`
- Supports dry run: `no`

Explain resolved configuration

Example:

```bash
gmail config explain --help
```

### `gmail doctor`

- Anchor: `cmd-gmail-doctor`
- Mutates state: `no`
- Supports dry run: `no`

Run Gmail adapter diagnostics

Example:

```bash
gmail doctor
gmail doctor --help
gmail doctor --json
```

### `gmail draft`

- Anchor: `cmd-gmail-draft`
- Mutates state: `no`
- Supports dry run: `no`

Work with Gmail drafts

#### `gmail draft create`

- Anchor: `cmd-gmail-draft-create`
- Mutates state: `yes`
- Supports dry run: `no`

Create a Gmail draft

Create a new Gmail draft.

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

Example:

```bash
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
```

Flags:

- `--attach` (stringSlice): File path(s) to attach
- `--body` (string): Draft body
- `--subject` (string): Draft subject
- `--to` (string): Comma-separated recipients

#### `gmail draft delete`

- Anchor: `cmd-gmail-draft-delete`
- Mutates state: `yes`
- Supports dry run: `no`

Delete a draft

Delete one Gmail draft.

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

Example:

```bash
gmail draft delete --help
gmail draft delete d1
gmail draft list --limit 1 --jsonl | gmail draft delete
```

Flags:

- `--id` (string): Draft id

#### `gmail draft get`

- Anchor: `cmd-gmail-draft-get`
- Mutates state: `no`
- Supports dry run: `no`

Get a draft

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.

Example:

```bash
gmail draft get
gmail draft get d1
gmail draft list --limit 1 --jsonl | gmail draft get
```

Flags:

- `--id` (string): Draft id

#### `gmail draft list`

- Anchor: `cmd-gmail-draft-list`
- Mutates state: `no`
- Supports dry run: `no`

List drafts

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.

Example:

```bash
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
```

Flags:

- `--query` (string): Raw Gmail search query for drafts

#### `gmail draft send`

- Anchor: `cmd-gmail-draft-send`
- Mutates state: `yes`
- Supports dry run: `no`

Send a draft

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.

Example:

```bash
gmail draft list --limit 1 --jsonl | gmail draft send
gmail draft send --help
gmail draft send d1
```

Flags:

- `--id` (string): Draft id

#### `gmail draft update`

- Anchor: `cmd-gmail-draft-update`
- Mutates state: `yes`
- Supports dry run: `no`

Update a draft

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.

Example:

```bash
gmail draft list --limit 1 --jsonl | gmail draft update --subject 'Status'
gmail draft update --help
gmail draft update d1 --subject 'Status' --body 'Updated text'
```

Flags:

- `--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 filter`

- Anchor: `cmd-gmail-filter`
- Mutates state: `no`
- Supports dry run: `no`

Manage simple Gmail filters

#### `gmail filter create`

- Anchor: `cmd-gmail-filter-create`
- Mutates state: `yes`
- Supports dry run: `no`

Create a simple Gmail filter

Example:

```bash
gmail filter create --from alerts@example.com --label cmdhub-demo --archive --yes
gmail filter create --help
gmail filter create --subject "cmdhub-demo" --star --yes
```

Flags:

- `--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 delete`

- Anchor: `cmd-gmail-filter-delete`
- Mutates state: `yes`
- Supports dry run: `no`

Delete a Gmail filter

Example:

```bash
gmail filter delete --help
gmail filter delete f1 --yes
```

Flags:

- `--id` (string): Gmail filter id or local ref
- `--yes` (bool): Confirm filter deletion

#### `gmail filter get`

- Anchor: `cmd-gmail-filter-get`
- Mutates state: `no`
- Supports dry run: `no`

Get a Gmail filter

Example:

```bash
gmail filter get
gmail filter get f1
```

Flags:

- `--id` (string): Gmail filter id or local ref

#### `gmail filter list`

- Anchor: `cmd-gmail-filter-list`
- Mutates state: `no`
- Supports dry run: `no`

List Gmail filters

Example:

```bash
gmail filter list
gmail filter list --json
```

### `gmail history`

- Anchor: `cmd-gmail-history`
- Mutates state: `no`
- Supports dry run: `no`

Inspect Gmail mailbox history

#### `gmail history list`

- Anchor: `cmd-gmail-history-list`
- Mutates state: `no`
- Supports dry run: `no`

List Gmail history records from a known historyId

Example:

```bash
gmail history list
gmail history list --start-history-id 123456 --history-type messageAdded
```

Flags:

- `--history-type` (stringSlice): History type filter; repeat or comma-separate
- `--start-history-id` (string): Gmail historyId from message/thread metadata

### `gmail label`

- Anchor: `cmd-gmail-label`
- Mutates state: `yes`
- Supports dry run: `no`

Work with Gmail labels

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`

- Anchor: `cmd-gmail-label-create`
- Mutates state: `yes`
- Supports dry run: `no`

Create a user Gmail label

Example:

```bash
gmail label create --help
gmail label create --name cmdhub-demo
```

Flags:

- `--name` (string): New user label name

#### `gmail label delete`

- Anchor: `cmd-gmail-label-delete`
- Mutates state: `yes`
- Supports dry run: `no`

Delete a user Gmail label

Example:

```bash
gmail label delete --help
gmail label delete l1 --yes
```

Flags:

- `--id` (string): Gmail label id, name, or local ref
- `--yes` (bool): Confirm destructive label deletion

#### `gmail label get`

- Anchor: `cmd-gmail-label-get`
- Mutates state: `no`
- Supports dry run: `no`

Get a Gmail label

Example:

```bash
gmail label get
gmail label get INBOX
gmail label get l1
```

Flags:

- `--id` (string): Gmail label id, name, or local ref

#### `gmail label list`

- Anchor: `cmd-gmail-label-list`
- Mutates state: `no`
- Supports dry run: `no`

List Gmail labels

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

Example:

```bash
gmail label list
gmail label list --json
gmail label search --query cmdhub
```

Flags:

- `--query` (string): Filter labels locally by name or id

#### `gmail label update`

- Anchor: `cmd-gmail-label-update`
- Mutates state: `yes`
- Supports dry run: `no`

Rename a user Gmail label

Example:

```bash
gmail label update --help
gmail label update l1 --name cmdhub-demo-done
```

Flags:

- `--id` (string): Gmail label id, name, or local ref
- `--name` (string): Updated user label name

### `gmail login`

- Anchor: `cmd-gmail-login`
- Mutates state: `yes`
- Supports dry run: `no`

Start Gmail OAuth login

Example:

```bash
gmail --profile work login
gmail login
```

### `gmail logout`

- Anchor: `cmd-gmail-logout`
- Mutates state: `yes`
- Supports dry run: `no`

Clear auth state

Example:

```bash
gmail --profile work logout
gmail logout
```

### `gmail message`

- Anchor: `cmd-gmail-message`
- Mutates state: `no`
- Supports dry run: `no`

Work with Gmail messages

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>`.

Example:

```bash
gmail message list --query 'subject:"Quarterly review"' --limit 1 --jsonl
  gmail message get m1
  gmail message 19d8712e0a4159b7 --jsonl
```

#### `gmail message archive`

- Anchor: `cmd-gmail-message-archive`
- Mutates state: `yes`
- Supports dry run: `no`

Archive a message by removing INBOX

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.

Example:

```bash
gmail message archive --all m1 m2
gmail message archive --help
gmail message archive m1
gmail message list --unread --jsonl | gmail message archive --all
```

Flags:

- `--all` (bool): Confirm batch archive
- `--id` (string): Gmail message id

#### `gmail message create`

- Anchor: `cmd-gmail-message-create`
- Mutates state: `yes`
- Supports dry run: `no`

Create a new Gmail message or draft

Create a new Gmail message.

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

Example:

```bash
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'
```

Flags:

- `--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 delete`

- Anchor: `cmd-gmail-message-delete`
- Mutates state: `yes`
- Supports dry run: `no`

Permanently delete a message

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.

Example:

```bash
gmail message delete --all --yes m1 m2
gmail message delete --help
gmail message delete m1
```

Flags:

- `--all` (bool): Confirm batch permanent delete
- `--id` (string): Gmail message id
- `--yes` (bool): Confirm destructive permanent delete

#### `gmail message forward`

- Anchor: `cmd-gmail-message-forward`
- Mutates state: `yes`
- Supports dry run: `no`

Create a forward draft

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.

Example:

```bash
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.'
```

Flags:

- `--body` (string): Forward body text
- `--id` (string): Gmail message id
- `--to` (string): Comma-separated recipients

#### `gmail message get`

- Anchor: `cmd-gmail-message-get`
- Mutates state: `no`
- Supports dry run: `no`

Get a full message with parsed MIME content

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.

Example:

```bash
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
```

Flags:

- `--id` (string): Gmail message id

#### `gmail message important`

- Anchor: `cmd-gmail-message-important`
- Mutates state: `no`
- Supports dry run: `no`

Mark a message as important

Example:

```bash
gmail message important --help
gmail message important m1
```

Flags:

- `--all` (bool): Confirm batch important
- `--id` (string): Gmail message id

#### `gmail message label`

- Anchor: `cmd-gmail-message-label`
- Mutates state: `yes`
- Supports dry run: `no`

Modify Gmail labels

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`

- Anchor: `cmd-gmail-message-label-add`
- Mutates state: `yes`
- Supports dry run: `no`

Add labels to a message

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.

Example:

```bash
gmail label list
gmail message label add --all m1 m2 --label STARRED
gmail message label add --help
gmail message label add m1 --label l1
```

Flags:

- `--all` (bool): Confirm batch label add
- `--id` (string): Gmail message id
- `--label` (string): Comma-separated label IDs, names, or local refs to add

##### `gmail message label remove`

- Anchor: `cmd-gmail-message-label-remove`
- Mutates state: `yes`
- Supports dry run: `no`

Remove labels from a message

Remove one or more Gmail labels from 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.

Example:

```bash
gmail message label remove --all m1 m2 --label STARRED
gmail message label remove --help
gmail message label remove m1 --label l1
```

Flags:

- `--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 list`

- Anchor: `cmd-gmail-message-list`
- Mutates state: `no`
- Supports dry run: `no`

List messages

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

Example:

```bash
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
```

Flags:

- `--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 not-important`

- Anchor: `cmd-gmail-message-not-important`
- Mutates state: `no`
- Supports dry run: `no`

Remove important marker from a message

Example:

```bash
gmail message not-important --help
gmail message not-important m1
```

Flags:

- `--all` (bool): Confirm batch not-important
- `--id` (string): Gmail message id

#### `gmail message read`

- Anchor: `cmd-gmail-message-read`
- Mutates state: `yes`
- Supports dry run: `no`

Mark a message as read

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.

Example:

```bash
gmail message list --unread --jsonl | gmail message read --all
gmail message read --all m1 m2
gmail message read --help
gmail message read m1
```

Flags:

- `--all` (bool): Confirm batch read marking
- `--id` (string): Gmail message id

#### `gmail message reply`

- Anchor: `cmd-gmail-message-reply`
- Mutates state: `yes`
- Supports dry run: `no`

Send or draft a reply

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.

Example:

```bash
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.'
```

Flags:

- `--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 star`

- Anchor: `cmd-gmail-message-star`
- Mutates state: `no`
- Supports dry run: `no`

Star a message

Example:

```bash
gmail message list --query cmdhub-demo --jsonl | gmail message star --all
gmail message star --help
gmail message star m1
```

Flags:

- `--all` (bool): Confirm batch star
- `--id` (string): Gmail message id

#### `gmail message trash`

- Anchor: `cmd-gmail-message-trash`
- Mutates state: `yes`
- Supports dry run: `no`

Move a message to trash

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.

Example:

```bash
gmail message trash --all m1 m2
gmail message trash --help
gmail message trash m1
```

Flags:

- `--all` (bool): Confirm batch trash
- `--id` (string): Gmail message id

#### `gmail message unread`

- Anchor: `cmd-gmail-message-unread`
- Mutates state: `yes`
- Supports dry run: `no`

Mark a message as unread

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.

Example:

```bash
gmail message unread --all m1 m2
gmail message unread --help
gmail message unread m1
```

Flags:

- `--all` (bool): Confirm batch unread marking
- `--id` (string): Gmail message id

#### `gmail message unstar`

- Anchor: `cmd-gmail-message-unstar`
- Mutates state: `no`
- Supports dry run: `no`

Remove star from a message

Example:

```bash
gmail message unstar --help
gmail message unstar m1
```

Flags:

- `--all` (bool): Confirm batch unstar
- `--id` (string): Gmail message id

#### `gmail message untrash`

- Anchor: `cmd-gmail-message-untrash`
- Mutates state: `yes`
- Supports dry run: `no`

Restore a message from trash

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.

Example:

```bash
gmail message untrash --all m1 m2
gmail message untrash --help
gmail message untrash m1
```

Flags:

- `--all` (bool): Confirm batch untrash
- `--id` (string): Gmail message id

### `gmail profile`

- Anchor: `cmd-gmail-profile`
- Mutates state: `no`
- Supports dry run: `no`

Manage provider profiles

#### `gmail profile create`

- Anchor: `cmd-gmail-profile-create`
- Mutates state: `yes`
- Supports dry run: `no`

Create an unauthenticated provider profile

Example:

```bash
gmail profile create --help
```

#### `gmail profile delete`

- Anchor: `cmd-gmail-profile-delete`
- Mutates state: `yes`
- Supports dry run: `no`

Delete a local provider profile

Example:

```bash
gmail profile delete --help
```

#### `gmail profile list`

- Anchor: `cmd-gmail-profile-list`
- Mutates state: `no`
- Supports dry run: `no`

List provider profiles

Example:

```bash
gmail profile list --help
```

#### `gmail profile rename`

- Anchor: `cmd-gmail-profile-rename`
- Mutates state: `no`
- Supports dry run: `no`

Rename a local provider profile

Example:

```bash
gmail profile rename --help
```

#### `gmail profile use`

- Anchor: `cmd-gmail-profile-use`
- Mutates state: `yes`
- Supports dry run: `no`

Set the default provider profile

Example:

```bash
gmail profile use --help
```

### `gmail resolve`

- Anchor: `cmd-gmail-resolve`
- Mutates state: `no`
- Supports dry run: `no`

Resolve a local marker or stored short reference

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.

Example:

```bash
gmail resolve --help
gmail resolve 19d…9b7
gmail resolve m1
gmail resolve t1
gmail resolve u1
```

### `gmail schema`

- Anchor: `cmd-gmail-schema`
- Mutates state: `no`
- Supports dry run: `no`

Emit Gmail adapter schema hints

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.

Example:

```bash
gmail schema
gmail schema --help
gmail schema draft.create --in --json
gmail schema message.get --out --json
```

Flags:

- `--in` (bool): Show input schema
- `--out` (bool): Show output schema

### `gmail send-as`

- Anchor: `cmd-gmail-send-as`
- Mutates state: `no`
- Supports dry run: `no`

Inspect Gmail send-as aliases

#### `gmail send-as get`

- Anchor: `cmd-gmail-send-as-get`
- Mutates state: `no`
- Supports dry run: `no`

Get one send-as alias

Example:

```bash
gmail send-as get
gmail send-as get me@example.com
```

#### `gmail send-as list`

- Anchor: `cmd-gmail-send-as-list`
- Mutates state: `no`
- Supports dry run: `no`

List verified sender aliases

Example:

```bash
gmail send-as list
gmail send-as list --json
```

### `gmail thread`

- Anchor: `cmd-gmail-thread`
- Mutates state: `no`
- Supports dry run: `no`

Work with Gmail threads

#### `gmail thread archive`

- Anchor: `cmd-gmail-thread-archive`
- Mutates state: `yes`
- Supports dry run: `no`

Archive a thread by removing INBOX from existing messages

Example:

```bash
gmail thread archive --help
gmail thread archive t1
```

Flags:

- `--all` (bool): Confirm batch thread mutation
- `--id` (string): Gmail thread id

#### `gmail thread delete`

- Anchor: `cmd-gmail-thread-delete`
- Mutates state: `yes`
- Supports dry run: `no`

Permanently delete a thread

Example:

```bash
gmail thread delete --all --yes t1 t2
gmail thread delete --help
gmail thread delete t1 --yes
```

Flags:

- `--all` (bool): Confirm batch permanent delete
- `--id` (string): Gmail thread id
- `--yes` (bool): Confirm destructive permanent delete

#### `gmail thread get`

- Anchor: `cmd-gmail-thread-get`
- Mutates state: `no`
- Supports dry run: `no`

Get a full thread

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.

Example:

```bash
gmail thread get
gmail thread get t1
gmail thread list --limit 1 --jsonl | gmail thread get
```

Flags:

- `--id` (string): Gmail thread id

#### `gmail thread important`

- Anchor: `cmd-gmail-thread-important`
- Mutates state: `no`
- Supports dry run: `no`

Mark existing messages in a thread as important

Example:

```bash
gmail thread important --help
gmail thread important t1
```

Flags:

- `--all` (bool): Confirm batch thread mutation
- `--id` (string): Gmail thread id

#### `gmail thread list`

- Anchor: `cmd-gmail-thread-list`
- Mutates state: `no`
- Supports dry run: `no`

List threads

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.

Example:

```bash
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
```

Flags:

- `--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 not-important`

- Anchor: `cmd-gmail-thread-not-important`
- Mutates state: `no`
- Supports dry run: `no`

Remove important from existing messages in a thread

Example:

```bash
gmail thread not-important --help
gmail thread not-important t1
```

Flags:

- `--all` (bool): Confirm batch thread mutation
- `--id` (string): Gmail thread id

#### `gmail thread read`

- Anchor: `cmd-gmail-thread-read`
- Mutates state: `yes`
- Supports dry run: `no`

Mark a thread as read

Example:

```bash
gmail thread read --help
gmail thread read t1
```

Flags:

- `--all` (bool): Confirm batch thread mutation
- `--id` (string): Gmail thread id

#### `gmail thread reply`

- Anchor: `cmd-gmail-thread-reply`
- Mutates state: `yes`
- Supports dry run: `no`

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

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.

Example:

```bash
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.'
```

Flags:

- `--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 star`

- Anchor: `cmd-gmail-thread-star`
- Mutates state: `no`
- Supports dry run: `no`

Star existing messages in a thread

Example:

```bash
gmail thread star --help
gmail thread star t1
```

Flags:

- `--all` (bool): Confirm batch thread mutation
- `--id` (string): Gmail thread id

#### `gmail thread trash`

- Anchor: `cmd-gmail-thread-trash`
- Mutates state: `yes`
- Supports dry run: `no`

Move a thread to trash

Example:

```bash
gmail thread search --query cmdhub-demo --jsonl | gmail thread trash --all
gmail thread trash --help
gmail thread trash t1
```

Flags:

- `--all` (bool): Confirm batch thread trash
- `--id` (string): Gmail thread id

#### `gmail thread unread`

- Anchor: `cmd-gmail-thread-unread`
- Mutates state: `yes`
- Supports dry run: `no`

Mark a thread as unread

Example:

```bash
gmail thread unread --help
gmail thread unread t1
```

Flags:

- `--all` (bool): Confirm batch thread mutation
- `--id` (string): Gmail thread id

#### `gmail thread unstar`

- Anchor: `cmd-gmail-thread-unstar`
- Mutates state: `no`
- Supports dry run: `no`

Unstar existing messages in a thread

Example:

```bash
gmail thread unstar --help
gmail thread unstar t1
```

Flags:

- `--all` (bool): Confirm batch thread mutation
- `--id` (string): Gmail thread id

#### `gmail thread untrash`

- Anchor: `cmd-gmail-thread-untrash`
- Mutates state: `yes`
- Supports dry run: `no`

Restore a thread from trash

Example:

```bash
gmail thread untrash --help
gmail thread untrash t1
```

Flags:

- `--all` (bool): Confirm batch thread restore
- `--id` (string): Gmail thread id

### `gmail vacation`

- Anchor: `cmd-gmail-vacation`
- Mutates state: `no`
- Supports dry run: `no`

Manage Gmail vacation responder

#### `gmail vacation disable`

- Anchor: `cmd-gmail-vacation-disable`
- Mutates state: `no`
- Supports dry run: `no`

Disable vacation responder

Example:

```bash
gmail vacation disable --help
gmail vacation disable --yes
```

Flags:

- `--yes` (bool): Confirm vacation responder disable

#### `gmail vacation get`

- Anchor: `cmd-gmail-vacation-get`
- Mutates state: `no`
- Supports dry run: `no`

Get vacation responder settings

Example:

```bash
gmail vacation get
gmail vacation get --json
```

#### `gmail vacation update`

- Anchor: `cmd-gmail-vacation-update`
- Mutates state: `yes`
- Supports dry run: `no`

Enable or update vacation responder settings

Example:

```bash
gmail vacation update --help
gmail vacation update --subject "Out of office" --body "Back Monday" --yes
```

Flags:

- `--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 version`

- Anchor: `cmd-gmail-version`
- Mutates state: `no`
- Supports dry run: `no`

Show gmail version information

Example:

```bash
gmail version --help
```

## Live Examples

### Auth

#### Check current identity

Returns the active Gmail address.

_Example metadata: requires auth; provider state: live._

```bash
gmail auth whoami
```

```text
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.

_Example metadata: requires auth; provider state: live._

```bash
gmail message list --limit 5
```

```text
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.

_Example metadata: requires auth; provider state: live._

```bash
gmail message get m1
```

Error:

```text
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.

_Example metadata: requires auth; provider state: live._

```bash
gmail thread list --limit 3
```

```text
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.

_Example metadata: requires auth; provider state: live._

```bash
gmail thread get t1
```

Error:

```text
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.

_Example metadata: requires auth; provider state: live._

```bash
gmail label list
```

```text
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.

_Example metadata: requires auth; provider state: live._

```bash
gmail draft list
```

```text
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
```