@cli4ai/gmail
v1.0.14
Published
Gmail CLI tool for messages, threads, and drafts
Maintainers
cliforaiReadme
@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 gmail1) 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 inboxOn 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 threadsActions
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 unreadSending
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 draftAttachments
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 attachmentsLabels
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 labelOutput 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:[email protected]"
cli4ai run gmail search "to:me"
cli4ai run gmail search "cc:[email protected]"
# 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:[email protected] 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:[email protected] 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 "[email protected]" "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 "[email protected]" "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 "[email protected]" "Report" "See attached" --attach=./report.pdf
# Multiple attachments
cli4ai run gmail send "[email protected]" "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 "[email protected]" "Draft" "Will finish later"
cli4ai run gmail draft-reply 19b176a2f49b681f "Thanks, need to think about this"
cli4ai run gmail draft-send r123456789Project 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 labelsgmail.compose- Create drafts and sendgmail.send- Send emails