gmcli

badlogic's avatarfrom badlogic

Gmail CLI for searching emails, reading threads, sending messages, managing drafts, and handling labels/attachments.

⭐72stars🔀6forks📁View on GitHub🕐Updated Dec 23, 2025
[Email and Outreach]

When & Why to Use This Skill

The Gmail CLI (gmcli) skill enables Claude to perform comprehensive email management tasks directly through the Gmail API. It allows for advanced searching using Gmail's native query syntax, reading full conversation threads, composing and sending messages, and managing drafts, labels, and attachments. This tool is designed to streamline communication workflows and automate inbox organization within an agentic environment.

Use Cases

  • 1. Automated Email Retrieval: Efficiently search and filter through large volumes of emails using specific keywords, dates, or senders to extract critical information.
  • 2. Communication Automation: Draft and send professional emails or follow-ups programmatically, reducing the time spent on manual outreach.
  • 3. Thread Summarization and Analysis: Retrieve entire email threads to provide context-aware summaries or track the history of long-term projects and conversations.
  • 4. Inbox Organization: Manage labels and attachments at scale to maintain a clean and structured mailbox, facilitating better data management.
namegmcli
descriptionGmail CLI for searching emails, reading threads, sending messages, managing drafts, and handling labels/attachments.

Gmail CLI

Command-line interface for Gmail operations.

Installation

npm install -g @mariozechner/gmcli

Setup

Google Cloud Console (one-time)

  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)
  5. Create OAuth client:
    • Click "Create Client"
    • Application type: "Desktop app"
    • Download the JSON file

Configure gmcli

First check if already configured:

gmcli accounts list

If no accounts, guide the user through setup:

  1. Ask if they have a Google Cloud project with Gmail API enabled
  2. If not, walk them through the Google Cloud Console steps above
  3. Have them download the OAuth credentials JSON
  4. Run: gmcli accounts credentials ~/path/to/credentials.json
  5. Run: gmcli accounts add <email> (use --manual for browserless OAuth)

Usage

Run gmcli --help for full command reference.

Common operations:

  • gmcli <email> search "<query>" - Search emails using Gmail query syntax
  • gmcli <email> thread <threadId> - Read a thread with all messages
  • gmcli <email> send --to <emails> --subject <s> --body <b> - Send email
  • gmcli <email> labels list - List all labels
  • gmcli <email> drafts list - List drafts

Data Storage

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