CLI tool for reading, sending, and replying to Gmail emails. Designed for Claude Code integration.
-
Get OAuth credentials:
- Copy
credentials.jsonfrom../gmail_to_md/, or - Create new credentials in Google Cloud Console
- Copy
-
First run:
uv run gmail_cli.py list --limit 1
This will open a browser for OAuth authorization. Token is saved to
token.json.
# Recent emails
uv run gmail_cli.py list --limit 10
# Search with Gmail query
uv run gmail_cli.py list --query "from:alice@example.com" --limit 5
uv run gmail_cli.py list --query "is:unread subject:urgent"# By message ID
uv run gmail_cli.py read abc123def
# Multiple IDs
uv run gmail_cli.py read abc123 def456 ghi789
# By query (list + read in one step)
uv run gmail_cli.py read --query "from:bob@example.com" --limit 3# Inline body
uv run gmail_cli.py send --to "user@example.com" --subject "Hello" --body "Message here"
# From file
uv run gmail_cli.py send --to "user@example.com" --subject "Update" --file message.md
# Create draft instead of sending
uv run gmail_cli.py send --to "user@example.com" --subject "Hello" --body "Message" --draft
# With BCC recipient
uv run gmail_cli.py send --to "user@example.com" --bcc "hidden@example.com" --subject "Hello" --body "Message"# Reply to a message (maintains threading)
uv run gmail_cli.py reply abc123def --body "Thanks for your message!"
# Reply from file
uv run gmail_cli.py reply abc123def --file response.md
# Create draft reply instead of sending
uv run gmail_cli.py reply abc123def --body "Thanks!" --draft
# Reply with BCC
uv run gmail_cli.py reply abc123def --body "Thanks!" --bcc "hidden@example.com"from:user@example.com- From addressto:user@example.com- To addresssubject:keyword- Subject containsis:unread- Unread messagesis:starred- Starred messageshas:attachment- Has attachmentsafter:2024/01/01- Date filterlabel:important- By label