home / skills / badlogic / pi-skills / gmcli

gmcli skill

safe

This skill empowers you to manage Gmail via CLI, enabling search, read threads, send messages, and handle drafts and labels efficiently.

npx playbooks add skill badlogic/pi-skills --skill gmcli

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.8 KB

---
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

Overview

This skill provides a command-line Gmail client for searching messages, reading threads, sending emails, managing drafts, labels, and attachments. It streamlines common Gmail workflows from terminals and scripts, using OAuth credentials to access one or more Gmail accounts. Installation is via npm and a one-time Google Cloud Console setup to enable the Gmail API and provide OAuth credentials.

How this skill works

The tool communicates with the Gmail REST API using OAuth tokens stored locally. It exposes commands for account setup, search queries, thread viewing, sending messages, label management, draft handling, and attachment download. Credentials and account tokens are saved under ~/.gmcli so subsequent commands run without repeated authentication.

When to use it

Send and script emails from the terminal or CI pipelines.
Search inboxes or read full conversation threads quickly without a browser.
Automate label management or bulk operations across accounts.
Manage and sync drafts between local workflows and Gmail.
Download or manage attachments from messages programmatically.

Best practices

Complete the Google Cloud Console setup and add test users before first run.
Keep OAuth credentials.json secure and never commit it to source control.
Run gmcli accounts list after setup to verify tokens and account state.
Use Gmail query syntax for targeted searches to avoid large result sets.
Automate repeatable tasks with shell scripts that call gmcli and handle outputs conservatively.

Example use cases

Search an account for receipts: gmcli [email protected] search "from:store subject:receipt" and export results to a script.
Read a full conversation: gmcli [email protected] thread <threadId> to review all messages and attachments on the terminal.
Send an email from a CI job: gmcli [email protected] send --to [email protected] --subject "Deployment" --body "Completed".
List and manage labels for cleanup: gmcli [email protected] labels list then apply or remove labels via script.
Manage drafts: gmcli [email protected] drafts list and edit or send drafts as part of a content workflow.

FAQ

How do I set up OAuth credentials?

Create a Google Cloud project, enable the Gmail API, configure OAuth branding, add test users, create a Desktop app OAuth client, download the JSON, and run gmcli accounts credentials <path>.

Where are credentials and attachments stored?

OAuth client and token files are stored in ~/.gmcli (credentials.json and accounts.json) and downloaded attachments go to ~/.gmcli/attachments/.