gmcli

Command-line interface for Gmail operations.

Installation

npm install -g @mariozechner/gmcli

Setup

Google Cloud Console (one-time)

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

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

• Ask if they have a Google Cloud project with Gmail API enabled

• If not, walk them through the Google Cloud Console steps above

• Have them download the OAuth credentials JSON

• Run: gmcli accounts credentials ~/path/to/credentials.json

• 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