Minimal Gmail CLI for searching, reading threads, managing labels, drafts, and sending emails.
npm install -g @mariozechner/gmcliBefore adding an account, you need OAuth2 credentials from Google Cloud Console:
- Create a new project (or select existing)
- Enable the Gmail API
- Set app name in OAuth branding
- Add test users (all Gmail addresses you want to use with gmcli)
- 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]gmcli accounts <action> Account management
gmcli <email> <command> [options] Gmail operations
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 accountSearch 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:spamis:unread,is:starred,is:importantfrom:[email protected],to:[email protected]subject:keywordhas:attachment,filename:pdfafter:2024/01/01,before:2024/12/31label: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"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 attachmentsAttachments are saved to ~/.gmcli/attachments/.
gmcli <email> labels list # List all labels (ID, name, type)
gmcli <email> labels <threadIds...> [--add L] [--remove L] # Modify labels on threadsYou 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 STARREDgmcli <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 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.pdfGenerate 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 19aea1f2f3532db6All data is stored in ~/.gmcli/:
credentials.json- OAuth client credentialsaccounts.json- Account tokensattachments/- Downloaded attachments
npm install
npm run build
npm run check# Update version in package.json and CHANGELOG.md
npm run build
npm publish --access public
git tag v<version>
git push --tagsMIT