@cli4ai/gmail

Official @cli4ai package • https://cli4ai.com • Install cli4ai: npm i -g cli4ai

Full-featured Gmail CLI via Google API. Fast search, send/reply/forward, drafts, attachments, and labels.

Setup

npm i -g cli4ai
cli4ai add -g gmail

1) Google Cloud OAuth

Go to https://console.cloud.google.com
Create a project (or use an existing one)
Enable the Gmail API
Create OAuth 2.0 credentials (Desktop app recommended)
Download the OAuth client JSON

2) Point the tool at your credentials

Set GMAIL_CREDENTIALS_PATH to the downloaded JSON (optional: GMAIL_TOKEN_PATH).

Example:

GMAIL_CREDENTIALS_PATH="$HOME/Downloads/credentials.json" cli4ai run gmail inbox

On first run, the tool prints an authorization URL and prompts for the code, then stores a token at GMAIL_TOKEN_PATH (default: token.json inside the installed package directory).

Commands

Reading

cli4ai run gmail inbox [limit]              # Recent inbox messages (default: 20)
cli4ai run gmail unread [limit]             # Unread messages only
cli4ai run gmail search <query> [limit]     # Search with Gmail syntax
cli4ai run gmail read <id>                  # Read full message
cli4ai run gmail thread <id>                # Full conversation thread
cli4ai run gmail threads [limit] [query]    # List recent threads

Actions

cli4ai run gmail archive <id>               # Archive (remove from inbox)
cli4ai run gmail trash <id>                 # Move to trash
cli4ai run gmail untrash <id>               # Restore from trash
cli4ai run gmail star <id>                  # Star message
cli4ai run gmail unstar <id>                # Unstar message
cli4ai run gmail markread <id>              # Mark as read
cli4ai run gmail markunread <id>            # Mark as unread

Sending

cli4ai run gmail send <to> <subject> <body>      # Send new email
cli4ai run gmail reply <id> <body>               # Reply to message
cli4ai run gmail replyall <id> <body>            # Reply to all
cli4ai run gmail forward <id> <to> [body]        # Forward message
cli4ai run gmail draft <to> <subject> <body>     # Create draft (legacy)

Drafts

cli4ai run gmail drafts                          # List all drafts
cli4ai run gmail draft-get <id>                  # Get draft content
cli4ai run gmail draft-create <to> <subj> <body> # Create new draft
cli4ai run gmail draft-reply <msg-id> <body>     # Create draft reply to message
cli4ai run gmail draft-update <id> <to> <s> <b>  # Update existing draft
cli4ai run gmail draft-delete <id>               # Delete draft
cli4ai run gmail draft-send <id>                 # Send draft

Attachments

cli4ai run gmail attachments <id>                # List attachments in message
cli4ai run gmail download <id> [filename] [out]  # Download specific attachment
cli4ai run gmail download-all <id> [dir]         # Download all attachments

Labels

cli4ai run gmail labels                     # List all labels
cli4ai run gmail label <id> <label>         # Add label to message
cli4ai run gmail unlabel <id> <label>       # Remove label
cli4ai run gmail label-info <label>         # Get label with counts
cli4ai run gmail label-create <name>        # Create new label
cli4ai run gmail label-delete <name>        # Delete label

Output Flags

--raw, -r              # Full JSON output
--compact, -c          # One-line per message (great for quick scans)
--body, -b             # Include body in search results
--full, -f             # Full body (no truncation)
--limit=N              # Override default limit
--cc=email             # Add CC recipient
--bcc=email            # Add BCC recipient
--attach=/path/file    # Add attachment (repeatable)

Gmail Search Syntax

The search command uses Gmail's powerful search syntax:

# By sender/recipient
cli4ai run gmail search "from:boss@company.com"
cli4ai run gmail search "to:me"
cli4ai run gmail search "cc:team@company.com"

# By status
cli4ai run gmail search "is:unread"
cli4ai run gmail search "is:starred"
cli4ai run gmail search "is:important"

# By content
cli4ai run gmail search "subject:meeting"
cli4ai run gmail search "has:attachment"
cli4ai run gmail search "filename:pdf"

# By date
cli4ai run gmail search "after:2024/12/01"
cli4ai run gmail search "before:2024/12/31"
cli4ai run gmail search "newer_than:7d"
cli4ai run gmail search "older_than:1m"

# By label/location
cli4ai run gmail search "label:work"
cli4ai run gmail search "in:inbox"
cli4ai run gmail search "in:sent"

# Combine queries
cli4ai run gmail search "from:boss@company.com is:unread newer_than:7d"
cli4ai run gmail search "has:attachment larger:5M"

Examples

# Quick inbox scan
cli4ai run gmail inbox 10 --compact

# Find unread from specific sender
cli4ai run gmail search "from:important@client.com is:unread"

# Read a specific email
cli4ai run gmail read 19b176a2f49b681f

# View full conversation thread
cli4ai run gmail thread 19b176a2f49b681f

# Send an email
cli4ai run gmail send "john@example.com" "Meeting tomorrow" "Hi John,\n\nAre we still on for tomorrow?\n\nThanks"

# Reply to an email
cli4ai run gmail reply 19b176a2f49b681f "Thanks for the update, looks good!"

# Forward an email
cli4ai run gmail forward 19b176a2f49b681f "colleague@example.com" "FYI - see below"

# Archive old emails
cli4ai run gmail archive 19b176a2f49b681f

# Label management
cli4ai run gmail label 19b176a2f49b681f "Work"
cli4ai run gmail label-info "INBOX"

# Send with attachment
cli4ai run gmail send "john@example.com" "Report" "See attached" --attach=./report.pdf

# Multiple attachments
cli4ai run gmail send "john@example.com" "Files" "Here are the files" --attach=./a.pdf --attach=./b.pdf

# List and download attachments
cli4ai run gmail attachments 19b176a2f49b681f
cli4ai run gmail download 19b176a2f49b681f "report.pdf" ./downloads/report.pdf
cli4ai run gmail download-all 19b176a2f49b681f ./downloads/

# Draft management
cli4ai run gmail drafts
cli4ai run gmail draft-create "john@example.com" "Draft" "Will finish later"
cli4ai run gmail draft-reply 19b176a2f49b681f "Thanks, need to think about this"
cli4ai run gmail draft-send r123456789

Project Structure

gmail/
├── run.ts           # CLI entry point
├── lib/
│   ├── api.ts         # Gmail API client + OAuth
│   ├── messages.ts    # inbox, unread, search, read, archive...
│   ├── threads.ts     # Thread operations
│   ├── send.ts        # send, reply, forward (with attachment support)
│   ├── drafts.ts      # Draft management, reply drafts
│   ├── attachments.ts # List, download attachments
│   └── labels.ts      # Label management
├── credentials.json   # OAuth credentials (gitignored)
└── token.json         # Auth token (gitignored)

Required Scopes

gmail.modify - Read, send, delete, manage labels
gmail.compose - Create drafts and send
gmail.send - Send emails

gmail

About