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

   mkdir -p ~/.gmaillm
   mv ~/Downloads/client_secret_*.json ~/.gmaillm/oauth-keys.json
   chmod 600 ~/.gmaillm/oauth-keys.json
   

Step 2: Install gmaillm

# Install from source
cd ~/.claude/plugins/gmail-plugin/scripts/gmaillm
make install

Step 3: Authenticate

Run the setup command:

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:

gmail setup-auth --port 8081

Step 4: Verify Installation

gmail verify

Expected output:

Gmail API authentication: OK

Troubleshooting

"Credentials file is empty" Error

# Re-run authentication
python3 -m gmaillm.setup_auth

# If port is blocked
python3 -m gmaillm.setup_auth --port 9999

"Address already in use" Error

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

gmail --install-completion
exec $SHELL

Related Commands

• /gmail - Usage guide for gmail CLI