Home Original page

GitHub - badlogic/gmcli: Minimal Gmail CLI

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 you@gmail.com

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:sender@example.com, to:recipient@example.com
  • 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:boss@company.com

Examples:

gmcli you@gmail.com search "in:inbox"
gmcli you@gmail.com search "is:unread" --max 50
gmcli you@gmail.com search "from:someone@example.com 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 you@gmail.com labels list
gmcli you@gmail.com labels abc123 --remove UNREAD
gmcli you@gmail.com labels abc123 --add Work --remove INBOX
gmcli you@gmail.com 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 you@gmail.com drafts create --to a@x.com --subject "Hi" --body "Hello"

# Create reply draft
gmcli you@gmail.com drafts create --to a@x.com --subject "Re: Topic" \
    --body "My reply" --reply-to 19aea1f2f3532db5

# Send draft
gmcli you@gmail.com drafts send r1234567890

# Send directly
gmcli you@gmail.com send --to a@x.com --subject "Hi" --body "Hello"

# Send reply with attachment
gmcli you@gmail.com send --to a@x.com --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 you@gmail.com 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