gmcli

Minimal Gmail CLI for searching, reading threads, managing labels, drafts, and sending emails.

Install

npm install -g @mariozechner/gmcli

Setup

Before adding an account, you need OAuth2 credentials from Google Cloud Console:

1. Create a new project (or select existing)
2. Enable the Gmail API
3. Set app name in OAuth branding
4. Add test users (all Gmail addresses you want to use with gmcli)
5. Create OAuth client:
   • Click "Create Client"
   • Application type: "Desktop app"
   • Download the JSON file

Then:

gmcli accounts credentials ~/path/to/credentials.json
gmcli accounts add [email protected]

Usage

gmcli accounts <action>                Account management
gmcli <email> <command> [options]      Gmail operations

Commands

accounts

gmcli accounts credentials <file.json>   # Set OAuth credentials (once)
gmcli accounts list                      # List configured accounts
gmcli accounts add <email>               # Add account (opens browser)
gmcli accounts add <email> --manual      # Add account (browserless, paste redirect URL)
gmcli accounts remove <email>            # Remove account

search

Search threads using Gmail query syntax. Returns thread ID, date, sender, subject, and labels.

gmcli <email> search <query> [--max N] [--page TOKEN]

Query examples:

• in:inbox, in:sent, in:drafts, in:trash, in:spam
• is:unread, is:starred, is:important
• from:[email protected], to:[email protected]
• subject:keyword
• has:attachment, filename:pdf
• after:2024/01/01, before:2024/12/31
• label:Work, label:UNREAD
• Combine with spaces: in:inbox is:unread from:[email protected]

Examples:

gmcli [email protected] search "in:inbox"
gmcli [email protected] search "is:unread" --max 50
gmcli [email protected] search "from:[email protected] has:attachment"

thread

Get a thread with all messages. Shows Message-ID, headers, body, and attachments for each message.

gmcli <email> thread <threadId>              # View thread
gmcli <email> thread <threadId> --download   # Download attachments

Attachments are saved to ~/.gmcli/attachments/.

labels

gmcli <email> labels list                              # List all labels (ID, name, type)
gmcli <email> labels <threadIds...> [--add L] [--remove L]  # Modify labels on threads

You can use label names or IDs when modifying (names are case-insensitive).

System labels: INBOX, UNREAD, STARRED, IMPORTANT, TRASH, SPAM

Examples:

gmcli [email protected] labels list
gmcli [email protected] labels abc123 --remove UNREAD
gmcli [email protected] labels abc123 --add Work --remove INBOX
gmcli [email protected] labels abc123 def456 --add STARRED

drafts

gmcli <email> drafts list                      # List all drafts
gmcli <email> drafts get <draftId>             # View draft with attachments
gmcli <email> drafts get <draftId> --download  # Download draft attachments
gmcli <email> drafts delete <draftId>          # Delete draft
gmcli <email> drafts send <draftId>            # Send draft

gmcli <email> drafts create --to <emails> --subject <s> --body <b> [options]

send

Send an email directly.

gmcli <email> send --to <emails> --subject <s> --body <b> [options]

Options for drafts create and send:

• --to <emails> - Recipients (comma-separated, required)
• --subject <s> - Subject line (required)
• --body <b> - Message body (required)
• --cc <emails> - CC recipients (comma-separated)
• --bcc <emails> - BCC recipients (comma-separated)
• --reply-to <messageId> - Reply to message (sets In-Reply-To/References headers and thread)
• --attach <file> - Attach file (can be used multiple times)

Examples:

# Create draft
gmcli [email protected] drafts create --to [email protected] --subject "Hi" --body "Hello"

# Create reply draft
gmcli [email protected] drafts create --to [email protected] --subject "Re: Topic" \
    --body "My reply" --reply-to 19aea1f2f3532db5

# Send draft
gmcli [email protected] drafts send r1234567890

# Send directly
gmcli [email protected] send --to [email protected] --subject "Hi" --body "Hello"

# Send reply with attachment
gmcli [email protected] send --to [email protected] --subject "Re: Topic" \
    --body "See attached" --reply-to 19aea1f2f3532db5 --attach doc.pdf

url

Generate Gmail web URLs for threads. Uses canonical URL format with email parameter (works regardless of account order in browser).

gmcli <email> url <threadIds...>

Example:

gmcli [email protected] url 19aea1f2f3532db5 19aea1f2f3532db6

Data Storage

All data is stored in ~/.gmcli/:

• credentials.json - OAuth client credentials
• accounts.json - Account tokens
• attachments/ - Downloaded attachments

Development

npm install
npm run build
npm run check

Publishing

# Update version in package.json and CHANGELOG.md
npm run build
npm publish --access public
git tag v<version>
git push --tags

License

MIT