| name | gmcli |
| description | Gmail CLI for searching emails, reading threads, sending messages, managing drafts, and handling labels/attachments. Triggers: Gmail, send email, search email, read email, email thread, email draft, email labels, gmcli. |
| compatibility | Requires Google OAuth credentials configured via gmcli setup |
| allowed-tools | Bash(gmcli:*) |
| metadata | {"version":"1.0","author":"canvas-studios"} |
Gmail CLI
Command-line interface for Gmail operations.
Installation
In Canvas Notebook Docker, a container admin installs this once:
npm install -g @mariozechner/gmcli
Check if installed:
gmcli --help
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