npm package: @inbounter/cli
Description: Official CLI for Inbounter
Latest version: 0.1.0

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://inbounter.com/logos/inbounter_light.svg" />
    <source media="(prefers-color-scheme: light)" srcset="https://inbounter.com/logos/inbounter_dark.svg" />
    <img src="https://inbounter.com/logos/inbounter_dark.svg" alt="Inbounter" width="300" />
  </picture>
</p>

<p align="center">
  <b>Official CLI for <a href="https://inbounter.com">Inbounter</a></b><br/>
  Manage inboxes, messages, sources, and routing right from your terminal.
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@inbounter/cli">
    <img src="https://img.shields.io/npm/v/@inbounter/cli.svg?style=flat-square" alt="NPM Version" />
  </a>
  <a href="https://github.com/inbounter/inbounter-cli/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/inbounter/inbounter-cli.svg?style=flat-square" alt="License" />
  </a>
</p>

# Inbounter CLI

## What is Inbounter?

**Inbounter** is infrastructure that gives AI agents their own inboxes — email, SMS, and more — with built-in security and smart routing.

- :mailbox_with_mail: **Inboxes** — Provision dedicated email & SMS inboxes for AI agents
- :shield: **Shield Mode** — Block spam, phishing, and unwanted messages automatically
- :twisted_rightwards_arrows: **Smart Routing** — Route inbound messages with filters, AI extraction, and webhooks
- :incoming_envelope: **Outbound** — Send emails and SMS directly from agent inboxes
- :link: **Webhooks** — Real-time event notifications for contacts, messages, and more
- :credit_card: **Credits** — Usage-based billing with auto-replenish

> [Get your API key](https://inbounter.com)

## Installation

```bash
npm install -g @inbounter/cli
```

Requires Node.js 18 or later.

## Authentication

**Browser-based login (recommended):**

```bash
inbounter auth login
```

This opens your browser to authenticate and automatically saves credentials to your local config.

**Manual login:**

```bash
inbounter login
```

You will be prompted to enter your API key, workspace ID, and API URL interactively.

**Verify your credentials:**

```bash
inbounter auth whoami
```

## Commands

### Authentication

| Command | Description |
|---|---|
| `inbounter auth login` | Authenticate via browser (recommended) |
| `inbounter auth logout` | Remove stored credentials |
| `inbounter auth whoami` | Show current credentials |
| `inbounter auth upgrade` | Link your agent account to an email and password |
| `inbounter login` | Configure API credentials manually |
| `inbounter whoami` | Show current configuration and identity |

### Config

| Command | Description |
|---|---|
| `inbounter config set <key> <value>` | Set a config value (`apiKey`, `workspaceId`, `apiUrl`, `defaultInbox`) |
| `inbounter config get <key>` | Get a config value |
| `inbounter config list` | Show all configuration |

### Inboxes

| Command | Description |
|---|---|
| `inbounter inboxes list` | List all inboxes |
| `inbounter inboxes get [inbox]` | Get inbox details (by email, ID, or default) |
| `inbounter inboxes create` | Create a new inbox |
| `inbounter inboxes update [inbox]` | Update an inbox |
| `inbounter inboxes delete [inbox]` | Delete an inbox |
| `inbounter inboxes stats [inbox]` | Get inbox statistics |

```bash
# Create an inbox with shield mode enabled
inbounter inboxes create --name "support-agent" --type EMAIL --shield

# Create an SMS inbox
inbounter inboxes create --name "notifications" --type SMS

# Get stats for an inbox
inbounter inboxes stats support-agent@your-domain.com
```

### Messages

| Command | Description |
|---|---|
| `inbounter messages list` | List messages (all inboxes or filtered) |
| `inbounter messages get <messageId>` | Get a specific message |
| `inbounter messages search <query>` | Search messages across inboxes |

```bash
# List messages for a specific inbox
inbounter messages list --inbox support-agent@your-domain.com

# Search messages semantically
inbounter messages search "billing question" --mode semantic

# Keyword search with a limit
inbounter messages search "password reset" --mode keyword --limit 10
```

### Threads

| Command | Description |
|---|---|
| `inbounter threads list` | List threads (all inboxes or filtered) |
| `inbounter threads get <threadId>` | Get a specific thread with messages |

```bash
# List threads for an inbox
inbounter threads list --inbox support-agent@your-domain.com
```

### Sending

| Command | Description |
|---|---|
| `inbounter send` | Send a single email |
| `inbounter send:batch` | Send a batch of emails from a JSON file |
| `inbounter reply <threadId>` | Reply to a thread |

```bash
# Send an email
inbounter send --to user@example.com --subject "Hello" --markdown "Hi there!"

# Send with CC and BCC
inbounter send --to user@example.com --subject "Update" --text "Hello" --cc "team@co.com" --bcc "log@co.com"

# Send a batch of emails
inbounter send:batch --file ./emails.json

# Reply to a thread
inbounter reply thread_abc123 --markdown "Thanks for reaching out!"
```

### Email Providers

| Command | Description |
|---|---|
| `inbounter connect gmail` | Connect a Gmail account via OAuth |
| `inbounter connect outlook` | Connect an Outlook account via OAuth |

```bash
# Connect your Gmail account
inbounter connect gmail

# Connect your Outlook account
inbounter connect outlook
```

### Shield Mode

| Command | Description |
|---|---|
| `inbounter shield rules` | Get shield rules for an inbox |
| `inbounter shield update` | Update shield rules |
| `inbounter shield toggle` | Enable or disable shield mode |
| `inbounter shield stats` | Get shield statistics |

```bash
# View shield rules
inbounter shield rules --inbox support-agent@your-domain.com

# Enable shield mode
inbounter shield toggle --enable

# Disable shield mode
inbounter shield toggle --disable

# Update rules from a JSON file
inbounter shield update --rules @rules.json
```

### Webhooks

| Command | Description |
|---|---|
| `inbounter webhooks list` | List all webhooks |
| `inbounter webhooks create` | Create a webhook |
| `inbounter webhooks test <webhookId>` | Send a test event to a webhook |

```bash
# Create a webhook for new messages
inbounter webhooks create --url "https://example.com/webhook" --events "message.received,message.sent"

# Test a webhook
inbounter webhooks test whk_abc123
```

### Routes

| Command | Description |
|---|---|
| `inbounter routes list` | List routes for an inbox |
| `inbounter routes create` | Create a route |
| `inbounter routes add-destination <routeId>` | Add a destination to a route |

```bash
# List routes
inbounter routes list --inbox support-agent@your-domain.com

# Create a route
inbounter routes create --id "urgent" --name "Urgent Messages" --default

# Add a webhook destination to a route
inbounter routes add-destination urgent --type WEBHOOK --name "Slack Alert" --config '{"url":"https://hooks.slack.com/..."}'
```

### Credits

| Command | Description |
|---|---|
| `inbounter credits` | Get workspace credit balance |

### MCP

| Command | Description |
|---|---|
| `inbounter mcp config` | Print MCP remote server config for your AI agent |
| `inbounter mcp stdio` | Print MCP stdio config for Claude Desktop / Cursor |
| `inbounter mcp test` | Test MCP connection to remote server |

```bash
# Get MCP config for Claude Desktop
inbounter mcp stdio

# Get MCP remote server config
inbounter mcp config

# Test MCP connection
inbounter mcp test
```

## Global Options

These flags can be passed to any command to override your saved configuration:

| Flag | Description |
|---|---|
| `--api-key <key>` | API key (overrides stored config) |
| `--workspace-id <id>` | Workspace ID (overrides stored config) |
| `--api-url <url>` | API URL (overrides stored config) |

```bash
# Use a specific API key for a single command
inbounter inboxes list --api-key "sk_..."

# Point to a different API server
inbounter messages list --api-url "http://localhost:3000"
```

## Documentation

Full API reference and guides at **[inbounter.com/docs](https://inbounter.com/docs)**

## Contributing

We love PRs!

1. **Fork** the repo and create your branch: `git checkout -b feat/awesome`
2. Add tests and docs
3. Open a **PR** against `main`

## License

[MIT](LICENSE)