npm package: @inbox-api/cli
Description: Command-line client for the Inbox API
Author: CloudWorks
Latest version: 0.1.4

# @inbox-api/cli

Command-line client for the [Inbox API](https://inbox-api.com). Manage email accounts, read and send messages, search, handle drafts, and browse threads from your terminal.

## Installation

```bash
npm install -g @inbox-api/cli
```

## Quick Start

```bash
# Configure your credentials (interactive)
inbox-api configure

# Or use environment variables
export INBOX_API_TOKEN=cw_your_token
export INBOX_API_URL=https://api.inbox-api.com

# List email accounts
inbox-api accounts list

# Read recent messages
inbox-api messages list

# Search across all accounts
inbox-api search "invoice from:billing@vendor.com"

# Send an email
inbox-api send --account <id> --to "user@example.com" --subject "Hello" --text "Hi there"
```

## Configuration

The CLI resolves authentication in this order:

1. **CLI flags:** `--token` and `--api-url`
2. **Environment variables:** `INBOX_API_TOKEN` and `INBOX_API_URL`
3. **Config file:** `~/.inbox-api/config.json` (created by `inbox-api configure`)

### Interactive Setup

```bash
inbox-api configure
```

Prompts for API URL and token, validates the connection with a health check, and saves to `~/.inbox-api/config.json`.

## Global Options

| Option | Description |
|--------|-------------|
| `--json` | Output raw JSON instead of formatted tables |
| `--no-color` | Disable colored output |
| `--debug` | Enable debug output |
| `--api-url <url>` | Override API base URL |
| `--token <token>` | Override API token |

## Commands

### `accounts` — Email Account Management

```bash
inbox-api accounts list                              # List all accounts
inbox-api accounts list --provider gmail             # Filter by provider
inbox-api accounts list --status error               # Filter by status
inbox-api accounts list --sort email                 # Sort by email address
inbox-api accounts folders <id>                      # List folders for an account
```

### `messages` — Email Messages

```bash
inbox-api messages list                              # List messages (default: 10 per page)
inbox-api messages list --account <id> --unread      # Unread messages for an account
inbox-api messages list --starred                    # Starred messages only
inbox-api messages list --has-attachments             # Messages with attachments
inbox-api messages list --start-date 2026-01-01      # Date range filter
inbox-api messages list --sort subject               # Sort by subject
inbox-api messages list -q "quarterly report"        # Inline full-text search
inbox-api messages read <id>                         # Read full message with body
inbox-api messages update <id> --read                # Mark as read
inbox-api messages update <id> --star                # Star a message
inbox-api messages move <id> --folder-id <fid>       # Move to folder
inbox-api messages archive <id>                      # Archive a message
inbox-api messages attachments <id>                  # List attachments
inbox-api messages download <id> <attachmentId>      # Download an attachment
inbox-api messages delete <id>                       # Delete a message
```

### `send` — Send Email

```bash
inbox-api send --account <id> \
  --to "Recipient <user@example.com>" \
  --cc "other@example.com" \
  --subject "Meeting tomorrow" \
  --text "Let's meet at 10am."
```

Recipients support both `"Name <email>"` and `"email"` formats.

### `reply` — Reply to a Message

```bash
inbox-api reply <messageId> --text "Thanks, got it."
inbox-api reply <messageId> --reply-all --text "Sounds good to everyone."
```

### `forward` — Forward a Message

```bash
inbox-api forward <messageId> --to "user@example.com"
inbox-api forward <messageId> --to "user@example.com" --text "FYI, see below."
```

### `search` — Full-Text Search

```bash
inbox-api search "quarterly report"
inbox-api search "from:boss@company.com" --account <id>
inbox-api search "invoice" --starred --sort relevance
inbox-api search "urgent" --unread --start-date 2026-03-01
```

### `drafts` — Draft Management

```bash
inbox-api drafts list                              # List drafts
inbox-api drafts list --account <id>               # Drafts for an account
inbox-api drafts list --start-date 2026-03-01      # Filter by date
inbox-api drafts get <id>                          # View a draft
inbox-api drafts create --account <id> --to "user@example.com" --subject "WIP"
inbox-api drafts update <id> --account <id> --text "Updated content"
inbox-api drafts send <id>                         # Send a draft
inbox-api drafts delete <id>                       # Delete a draft
```

### `threads` — Email Threads

```bash
inbox-api threads list                             # List threads
inbox-api threads list --account <id>              # Threads for an account
inbox-api threads list --unread-only               # Unread threads only
inbox-api threads list --start-date 2026-03-01     # Filter by date range
inbox-api threads get <id>                         # View thread with all messages
```

### `webhooks` — Webhook Management

```bash
inbox-api webhooks list                            # List webhooks
inbox-api webhooks get <id>                        # Get webhook details
inbox-api webhooks create --url https://... --events message.received
inbox-api webhooks update <id> --url https://...   # Update a webhook
inbox-api webhooks delete <id>                     # Delete a webhook
inbox-api webhooks deliveries <id>                 # List delivery attempts
inbox-api webhooks retry <id> <deliveryId>         # Retry a failed delivery
inbox-api webhooks purge <id>                      # Purge old delivery records
inbox-api webhooks templates                       # List webhook event templates
```

### `batch` — Bulk Operations

```bash
inbox-api batch mark-read <id1> <id2> ...          # Mark multiple messages as read
inbox-api batch mark-read --unread <id1> <id2>     # Mark multiple as unread
inbox-api batch archive <id1> <id2> ...            # Archive multiple messages
inbox-api batch move --folder-id <fid> <id1> <id2> # Move multiple messages
```

### `contacts` — Contact Discovery

```bash
inbox-api contacts list                            # List frequency-ranked contacts
inbox-api contacts list --account <id>             # Contacts for an account
```

### `digest` — Email Digest

```bash
inbox-api digest                                   # Digest of recent emails across accounts
inbox-api digest --hours 24                        # Last 24 hours
inbox-api digest --account <id>                    # Digest for a specific account
```

### `health` — Account Health

```bash
inbox-api health <accountId>                       # Check IMAP connection health
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | General error / API error |
| 2 | Authentication error (401/403) |
| 3 | Connection error (server unreachable) |

## Prerequisites

- Node.js >= 18
- An Inbox API account with an API token (`cw_` prefix)

## Development

```bash
# Build (requires @inbox-api/client built first)
npm run build

# Watch mode
npm run dev
```

## License

MIT