# create-neomutt-gmail

Interactive setup wizard for Neomutt + Gmail + OAuth2.0

[![npm version](https://badge.fury.io/js/create-neomutt-gmail.svg)](https://www.npmjs.com/package/create-neomutt-gmail)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
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:
```bash
brew install neomutt python3 gnupg
```

On Linux:
```bash
# 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:

```bash
gpg --full-generate-key
```

Choose:
- RSA and RSA
- 4096 bits
- No expiration (or as preferred)
- Enter your name and email

## Usage

### Standard Installation

```bash
npx create-neomutt-gmail
```

### Dry Run (Preview Only)

```bash
npx create-neomutt-gmail --dry-run
```

Shows what would be created without actually creating any files.

### Skip Prerequisites Check

```bash
npx create-neomutt-gmail --skip-prereqs
```

Skips the dependency verification (not recommended).

### Help

```bash
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):

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

**What each parameter means**:

| Parameter | Example | Where from |
|-----------|---------|-----------|
| `--recipient` | `your@gmail.com` | 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` | `your@gmail.com` | 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

```bash
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:
```bash
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:
```bash
brew install neomutt  # macOS
sudo apt install neomutt  # Linux
```

### "No GPG keys found"

Create a GPG key:
```bash
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:
```bash
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:
```bash
gpg --list-secret-keys
```

See the [detailed troubleshooting guide](https://github.com/a-lost-social-misfit/terminal-blog) 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](https://www.npmjs.com/package/mutt-config-core) - Configuration generation
- [config-fs-utils](https://www.npmjs.com/package/config-fs-utils) - File system operations

## Related Projects

- [mutt-config-core](https://github.com/a-lost-social-misfit/mutt-config-core) - Core config generator
- [config-fs-utils](https://github.com/a-lost-social-misfit/config-fs-utils) - FS utilities
- [terminal-blog](https://github.com/a-lost-social-misfit/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](https://github.com/a-lost-social-misfit)

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