120 lines
2.7 KiB
Markdown
120 lines
2.7 KiB
Markdown
---
|
|
description: Set up Gmail CLI authentication with OAuth2
|
|
---
|
|
|
|
# Gmail CLI Setup
|
|
|
|
This command guides you through setting up the `gmail` CLI for the first time.
|
|
|
|
## Prerequisites
|
|
|
|
You need OAuth2 credentials from Google Cloud Console.
|
|
|
|
## Step 1: Get OAuth2 Credentials
|
|
|
|
1. Go to [Google Cloud Console](https://console.cloud.google.com/apis/credentials)
|
|
2. Create a new project or select an existing one
|
|
3. Enable the **Gmail API**:
|
|
- Go to "APIs & Services" > "Enable APIs and Services"
|
|
- Search for "Gmail API" and enable it
|
|
4. Create OAuth2 credentials:
|
|
- Go to "Credentials" > "Create Credentials" > "OAuth client ID"
|
|
- Application type: **Desktop app**
|
|
- Name: "Gmail CLI" (or any name)
|
|
- Click "Create"
|
|
5. Download the credentials JSON file
|
|
6. Save it as `~/.gmaillm/oauth-keys.json`:
|
|
```bash
|
|
mkdir -p ~/.gmaillm
|
|
mv ~/Downloads/client_secret_*.json ~/.gmaillm/oauth-keys.json
|
|
chmod 600 ~/.gmaillm/oauth-keys.json
|
|
```
|
|
|
|
## Step 2: Install gmaillm
|
|
|
|
```bash
|
|
# Install from source
|
|
cd /Users/wz/.claude/plugins/marketplaces/warren-claude-code-plugin-marketplace/gmail-integration-plugin/scripts/gmaillm
|
|
make install
|
|
```
|
|
|
|
## Step 3: Authenticate
|
|
|
|
Run the setup command:
|
|
```bash
|
|
gmail setup-auth
|
|
```
|
|
|
|
This will:
|
|
1. Open your browser for Google authentication
|
|
2. Ask you to grant Gmail access to the CLI
|
|
3. Save credentials to `~/.gmaillm/credentials.json`
|
|
|
|
**If port 8080 is in use:**
|
|
```bash
|
|
gmail setup-auth --port 8081
|
|
```
|
|
|
|
## Step 4: Verify Installation
|
|
|
|
```bash
|
|
gmail verify
|
|
```
|
|
|
|
Expected output:
|
|
```
|
|
Gmail API authentication: OK
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### "Credentials file is empty" Error
|
|
```bash
|
|
# Re-run authentication
|
|
python3 -m gmaillm.setup_auth
|
|
|
|
# If port is blocked
|
|
python3 -m gmaillm.setup_auth --port 9999
|
|
```
|
|
|
|
### "Address already in use" Error
|
|
```bash
|
|
# Kill any existing auth processes
|
|
pkill -f "gmaillm.setup_auth"
|
|
|
|
# Try a different port
|
|
gmail setup-auth --port 8081
|
|
```
|
|
|
|
### OAuth Keys Location
|
|
The CLI searches for OAuth keys in this order:
|
|
1. `~/.gmaillm/oauth-keys.json` (recommended)
|
|
2. `${CLAUDE_PLUGIN_ROOT}/credentials/oauth-keys.json` (plugin mode)
|
|
3. `~/Desktop/OAuth2/gcp-oauth.keys.json` (fallback)
|
|
|
|
## File Structure After Setup
|
|
|
|
```
|
|
~/.gmaillm/
|
|
├── oauth-keys.json # OAuth2 client secrets (0600)
|
|
├── credentials.json # Saved credentials (0600)
|
|
├── email-groups.json # Email distribution groups
|
|
├── output-style.json # Output formatting preferences
|
|
└── email-styles/ # Email style templates
|
|
├── professional-formal.md
|
|
├── professional-friendly.md
|
|
└── casual-friend.md
|
|
```
|
|
|
|
## Optional: Shell Completion
|
|
|
|
Enable tab completion for faster typing:
|
|
```bash
|
|
gmail --install-completion
|
|
exec $SHELL
|
|
```
|
|
|
|
## Related Commands
|
|
|
|
- `/gmail` - Usage guide for gmail CLI
|