npm package: @mrprincerawat/gmail-cli
Description: A modern Gmail CLI — read, send, and manage email from the terminal
Author: Prince Rawat
Latest version: 0.1.0

# Gmail CLI

A modern Gmail CLI — read, send, and manage email from the terminal.

```
$ gmail inbox

  ● 1.  2m   Jane Smith           Meeting tomorrow at 3pm
  ● 2.  1h   GitHub               [project] New issue #12
  ● 3.  3h   John Doe             Re: Quick question
    4.  1d   Stripe               Your payout is on the way
    5.  2d   Vercel               Usage alert
```

## Install

```bash
npm install -g @princerawat/gmail-cli
```

## Setup

You need a Google Cloud project with the Gmail API enabled.

1. Go to [console.cloud.google.com](https://console.cloud.google.com)
2. Create a project (or use an existing one)
3. Enable the **Gmail API**
4. Go to **Credentials** → Create **OAuth client ID** (Desktop app)
5. Copy your Client ID and Client Secret

Then run:

```bash
gmail setup
```

It will prompt for your credentials and open a browser to sign in.

## Commands

### Read

```bash
gmail inbox                    # Interactive inbox — arrow keys, enter to read
gmail inbox --limit 10         # Limit number of emails
gmail inbox --json             # JSON output
gmail read 1                   # Read first email
gmail search "invoices"        # Search emails
```

### Send

```bash
gmail compose                                         # Interactive — To, Subject, Body step by step
gmail compose user@example.com -s "hey" -b "call?"   # Direct send
gmail reply                                           # Select email, type reply inline
gmail reply 1                                         # Reply to first email
gmail forward 1 user@example.com                      # Forward
```

### Manage

```bash
gmail archive 1               # Archive first email
gmail star 1                   # Star/unstar
gmail trash 1                  # Move to trash
gmail labels                   # List all labels
```

### Account

```bash
gmail setup                    # Connect Gmail
gmail logout                   # Disconnect
```

## Interactive Inbox

`gmail inbox` opens a full interactive view:

- **j/k or arrow keys** — navigate emails
- **enter** — read email (fetches body on demand)
- **c** — compose new email
- **r** — reply to selected email
- **a** — archive
- **s** — star/unstar
- **d** — trash
- **q** — quit

Inside an email, **arrow keys** scroll the body. Press **x** or **esc** to go back.

## Composing

When composing or replying, you get a multiline editor right in the terminal:

```
  Body: (ctrl+d to finish)

  1 │ Hey,
  2 │
  3 │ Just wanted to follow up on our call.
  4 │ Let me know when works.
  5 │
  6 │ Best,
  7 │ █

  ctrl+d finish  esc cancel
```

Emails are sent as clean HTML with proper formatting — they look great in any inbox.

## How it works

- **Commands** print to stdout — pipe-friendly, greppable, supports `--json`
- **Interactive prompts** appear when args are missing — step by step, no flags to memorize
- **Contact autocomplete** on the To field — fuzzy search over recent contacts
- **OAuth2** with your own Google Cloud credentials — your tokens stay on your machine at `~/.gmail-cli/`
- **Fast** — inbox loads in parallel, email bodies fetched on demand

## License

MIT