create-neomutt-gmail

Interactive setup wizard for Neomutt + Gmail + OAuth2.0

Features

• ✅ Interactive wizard - Answer a few questions, get a working config
• ✅ Prerequisites check - Verifies all dependencies before starting
• ✅ Safe operations - Automatic backups, confirmation prompts
• ✅ Dry-run mode - Preview changes without modifying files
• ✅ Automatic downloads - Fetches OAuth2 script from official source
• ✅ Helpful guidance - Clear next steps after installation

Quick Start

npx create-neomutt-gmail

That's it! Answer the questions and follow the on-screen instructions.

Prerequisites

The wizard checks for these automatically, but you'll need:

• neomutt - Email client
• python3 - For OAuth2 script
• gpg - For token encryption

On macOS:

brew install neomutt python3 gnupg

On Linux:

# Debian/Ubuntu
sudo apt install neomutt python3 gnupg

# Arch
sudo pacman -S neomutt python gnupg

GPG Key Setup

If you don't have a GPG key yet:

gpg --full-generate-key

Choose:

• RSA and RSA
• 4096 bits
• No expiration (or as preferred)
• Enter your name and email

Usage

Standard Installation

npx create-neomutt-gmail

Dry Run (Preview Only)

npx create-neomutt-gmail --dry-run

Shows what would be created without actually creating any files.

Skip Prerequisites Check

npx create-neomutt-gmail --skip-prereqs

Skips the dependency verification (not recommended).

Help

npx create-neomutt-gmail --help

What It Does

The wizard will:

1. Check prerequisites - Verify neomutt, python3, gpg are installed
2. Ask configuration questions:
   • Gmail address
   • Your name
   • Preferred editor (nvim, vim, nano, emacs)
   • Gmail language (Japanese or English)
   • GPG key ID (optional)
3. Create directories:
   • ~/.config/mutt/
   • ~/.config/mutt/accounts/
   • ~/.local/etc/oauth-tokens/
   • ~/.cache/mutt/
4. Generate config files:
   • ~/.config/mutt/muttrc
   • ~/.config/mutt/accounts/YOUR_EMAIL.muttrc
5. Download OAuth script:
   • ~/.config/mutt/mutt_oauth2.py
6. Display next steps for Google Cloud Console setup

After Installation

Understanding the Authentication Flow

This setup uses two different security mechanisms:

| Component | Purpose | Where to get it | |-----------|---------|----------------| | GPG Key | Encrypts OAuth token on your disk | Create with gpg --full-generate-key | | OAuth2 Credentials | Authenticates with Gmail | Google Cloud Console |

Common mistake: These are NOT the same thing. You need both.

Step 1: Google Cloud Console

1. Visit https://console.cloud.google.com/
2. Create a new project (e.g., "neomutt-gmail")
3. Enable Gmail API:
   • Go to "APIs & Services" → "Enable APIs and Services"
   • Search for "Gmail API" and enable it
4. Configure OAuth consent screen:
   • User Type: External (for personal Gmail)
   • App name: Any name (e.g., "Mutt Email Client")
   • Add scope: https://mail.google.com/
   • Add your email as test user
5. Create OAuth client ID:
   • Go to "Credentials" → "Create Credentials" → "OAuth client ID"
   • Application type: Desktop app
   • Name: Any name (e.g., "Mutt")
6. Save these credentials (you'll need them in Step 2):
   • Client ID (looks like: 123456789-abc.apps.googleusercontent.com)
   • Client Secret (looks like: GOCSPX-abc123xyz)

Step 2: Obtain OAuth Token

Run this command (the wizard shows you the exact command):

python3 ~/.config/mutt/mutt_oauth2.py \
  --authorize \
  --authflow localhostauthcode \
  --encryption-pipe 'gpg --encrypt --recipient [email protected]' \
  --client-id YOUR_CLIENT_ID.apps.googleusercontent.com \
  --client-secret YOUR_CLIENT_SECRET \
  --provider google \
  --email [email protected] \
  ~/.local/etc/oauth-tokens/gmail.tokens

What each parameter means:

| Parameter | Example | Where from | |-----------|---------|-----------| | --recipient | [email protected] | Your GPG key (created with gpg --full-generate-key) | | --client-id | 123...apps.googleusercontent.com | Google Cloud Console (Step 1) | | --client-secret | GOCSPX-... | Google Cloud Console (Step 1) | | --email | [email protected] | Your Gmail address |

What happens:

1. Browser opens for Google authentication
2. You authorize the app
3. Token is downloaded and encrypted with your GPG key
4. You'll be prompted for your GPG passphrase

Step 3: Launch Neomutt

neomutt

You'll be prompted for your GPG passphrase when Neomutt reads the encrypted token.

Keyboard Shortcuts

Once Neomutt is running:

| Key | Action | |-----|--------| | gi | Go to inbox | | gt | Go to trash | | gs | Go to sent mail | | gd | Go to drafts | | m | Compose new email | | r | Reply | | q | Quit |

Safety Features

Automatic Backups

Existing config files are backed up with timestamps:

~/.config/mutt/muttrc.backup-2026-01-26T12-34-56-789Z

Confirmation Prompts

The wizard asks for confirmation before:

• Overwriting existing configurations
• Creating files
• Proceeding with installation

Dry-Run Mode

Preview all changes before applying them:

npx create-neomutt-gmail --dry-run

File Permissions

Created files have appropriate permissions:

• Config files: 0o600 (owner read/write only)
• OAuth script: 0o755 (owner rwx, others rx)

Troubleshooting

"Command not found: neomutt"

Install neomutt:

brew install neomutt  # macOS
sudo apt install neomutt  # Linux

"No GPG keys found"

Create a GPG key:

gpg --full-generate-key

Remember: This GPG key is for encrypting the OAuth token on your disk, not for Google authentication.

"Failed to download mutt_oauth2.py"

Download manually:

curl -o ~/.config/mutt/mutt_oauth2.py \
  https://raw.githubusercontent.com/neomutt/neomutt/main/contrib/oauth2/mutt_oauth2.py
chmod +x ~/.config/mutt/mutt_oauth2.py

OAuth Token Issues

"Invalid credentials": Check that your Client ID and Secret are correct.

"Error decrypting token": Your GPG key might not be set up correctly. Run:

gpg --list-secret-keys

See the detailed troubleshooting guide for more help.

Common Misconceptions

GPG vs OAuth2

These are two completely different things:

• GPG: Local encryption tool
  • Purpose: Encrypt the OAuth token file on your disk
  • Where: Your computer (gpg --full-generate-key)
  • When: Once, during initial setup
• OAuth2: Google's authentication protocol
  • Purpose: Prove your identity to Gmail
  • Where: Google Cloud Console
  • When: You need Client ID and Secret from Google

You need BOTH:

1. Create a GPG key (once)
2. Get OAuth credentials from Google (once)
3. Run mutt_oauth2.py (uses both to create encrypted token)

Why use GPG encryption?

The OAuth token allows full access to your Gmail. GPG encryption ensures:

• Token is encrypted on disk
• Only you (with GPG passphrase) can decrypt it
• Safer than storing plain text

Powered By

This wizard uses:

• mutt-config-core - Configuration generation
• config-fs-utils - File system operations

Related Projects

• mutt-config-core - Core config generator
• config-fs-utils - FS utilities
• terminal-blog - Detailed setup guide

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

⚠️ Important Notice

This tool modifies files in your home directory:

• ~/.config/mutt/
• ~/.local/etc/oauth-tokens/
• ~/.cache/mutt/

Before running:

1. ✅ Backup existing Neomutt configuration (if any)
2. ✅ Review the code on GitHub
3. ✅ Use --dry-run to preview changes

The tool creates automatic backups, but it's your responsibility to:

• Verify the configuration before use
• Keep OAuth tokens secure
• Review file permissions

No warranty is provided. Use at your own risk.

License

MIT © a-lost-social-misfit

Author

Created by a-lost-social-misfit

Based on practical experience and lessons learned from setting up Neomutt with Gmail OAuth2.0 on macOS.