Skip to main content
skill CX Codex

gmcli — Claude Code skill: manage Gmail from the terminal

gmcli — a skill that gives your AI agent command-line access to Gmail. Search messages, read threads, send emails, manage drafts, and handle labels and attachments directly from your code.

MIT 160 installs ★ 2,663 updated 2026-06-06

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add badlogic/pi-skills --skill gmcli -a claude-code
Open on GitHub

What gmcli does

gmcli provides a command-line interface for Gmail operations. The agent can search emails with Gmail query syntax, fetch complete threads with full message history, send emails with a subject and body, view and apply labels, list and manage drafts, and download attachments. All commands run through the standard Gmail search language.

Setup requires a one-time Google Cloud project configuration: create a project, enable the Gmail API, set up an OAuth desktop application, and download the credentials JSON file. Once configured with gmcli accounts credentials and gmcli accounts add <email>, tokens are stored locally in ~/.gmcli/. Attachments go to ~/.gmcli/attachments/.

After installation for your chosen platform, the agent has full Gmail access—from searching to managing drafts and labels.

What it helps with

  • search emails by subject, sender, or date range
  • fetch and read entire email threads with message history
  • compose and send emails with subject and body
  • manage draft emails and Gmail labels
  • retrieve and process email attachments

Example prompts for the agent

  • Find me emails from the manager about next week's meeting
  • Show me the full thread for message ID 17abc4d9e5f6g7h8
  • Send an email to [email protected] titled 'Report ready' saying I've uploaded the file

How to install gmcli

1Skills CLI (Vercel)

npx skills add badlogic/pi-skills --skill gmcli -a claude-code

2Manually: put the files in place

~/.claude/skills/gmcli/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/gmcli/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about gmcli

How do I install gmcli in Claude Code?

Run npx skills add badlogic/pi-skills --skill gmcli -a claude-code. The skill will be available at ~/.claude/skills/gmcli/SKILL.md.

What's required before first use?

Create a project in Google Cloud Console, enable the Gmail API, add test email addresses, create a desktop OAuth application, and download the credentials JSON. Then run gmcli accounts credentials ~/path/to/credentials.json and gmcli accounts add <email>.

Where are credentials and attachments stored?

Credentials and account tokens live in ~/.gmcli/, and downloaded attachments go to ~/.gmcli/attachments/.

Source text

SKILL.md · MIT
---
name: gmcli
description: Gmail CLI for searching emails, reading threads, sending messages, managing drafts, and handling labels/attachments.
---

# Gmail CLI

Command-line interface for Gmail operations.

## Installation

```bash
npm install -g @mariozechner/gmcli
```

## Setup

### Google Cloud Console (one-time)

1. [Create a new project](https://console.cloud.google.com/projectcreate) (or select existing)
2. [Enable the Gmail API](https://console.cloud.google.com/apis/api/gmail.googleapis.com)
3. [Set app name](https://console.cloud.google.com/auth/branding) in OAuth branding
4. [Add test users](https://console.cloud.google.com/auth/audience) (all Gmail addresses you want to use)
5. [Create OAuth client](https://console.cloud.google.com/auth/clients):
   - Click "Create Client"
   - Application type: "Desktop app"
   - Download the JSON file

### Configure gmcli

First check if already configured:
```bash
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

© badlogic · MIT · badlogic/pi-skills

Similar skills

All skills for Notes, tasks and projects →

From the same set8

More in the catalog

Project sponsors

Companies that keep this analytics open