> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Manage WhatsApp numbers, messages, templates, and webhooks from the terminal

The Kapso CLI gives you full control over your WhatsApp integration from the command line. Send messages, manage webhooks, inspect conversations, and automate workflows — all without leaving your terminal.

Using an MCP-capable agent? Use [Project MCP](/docs/whatsapp/mcp) when the agent should manage Kapso without shell access.

## Installation

```bash theme={null}
npm install -g @kapso/cli
```

Requires Node.js >= 20.19.

## Authentication

**Browser login (interactive)**

```bash theme={null}
kapso login
```

Opens your browser to authenticate. Your session is stored locally in `~/.kapso/cli/`.

**API key (CI / non-interactive environments)**

```bash theme={null}
export KAPSO_API_KEY=your_project_api_key
```

When set, all project-scoped commands use the API key directly — no browser needed. Use this for CI pipelines, Docker containers, scripts, or any headless environment.

You can create your project API key in the [Kapso dashboard](https://app.kapso.ai).

## Project context

After login, the CLI remembers your active project. Switch between projects with:

```bash theme={null}
kapso projects list
kapso projects use <project-id>
kapso projects current
```

Check your full setup status:

```bash theme={null}
kapso status
```

## Setup

Connect a WhatsApp number to your project:

```bash theme={null}
kapso setup
```

This resolves your project and customer, then generates a setup link to connect or provision a WhatsApp number.

For automation:

```bash theme={null}
kapso setup \
  --customer <customer-id> \
  --country US \
  --connection-type dedicated
```

## Numbers

```bash theme={null}
# List all numbers
kapso whatsapp numbers list

# Get a specific number
kapso whatsapp numbers get "+1234567890"
kapso whatsapp numbers get --phone-number-id <meta-id>

# Start WhatsApp number setup
kapso whatsapp numbers new

# Health check
kapso whatsapp numbers health "+1234567890"

# Resolve a number reference to its canonical ID
kapso whatsapp numbers resolve "+1234567890"
```

Most WhatsApp commands accept `--phone-number` or `--phone-number-id` to specify which number to act on. You can also pass the number as a positional argument where supported.

## Messages

### Send a text message

```bash theme={null}
kapso whatsapp messages send \
  --phone-number-id <id> \
  --to "+1234567890" \
  --text "Hello from Kapso CLI"
```

### Send with a JSON payload

For media, interactive, or any advanced message type, pass a JSON payload:

```bash theme={null}
# From a file
kapso whatsapp messages send --phone-number-id <id> --input message.json

# From stdin
cat message.json | kapso whatsapp messages send --phone-number-id <id> --stdin
```

### List and get messages

```bash theme={null}
# List messages for a number
kapso whatsapp messages list --phone-number-id <id>

# Filter by direction, status, or time range
kapso whatsapp messages list \
  --phone-number-id <id> \
  --direction inbound \
  --since "2025-01-01T00:00:00Z" \
  --limit 50

# Get a specific message
kapso whatsapp messages get <message-id>
```

## Conversations

```bash theme={null}
# List conversations (most recent first)
kapso whatsapp conversations list --phone-number-id <id>

# Filter by status or contact phone
kapso whatsapp conversations list --phone-number-id <id> --status active --phone "+1234567890"

# Get a specific conversation
kapso whatsapp conversations get <conversation-id>
```

## Templates

```bash theme={null}
# List templates for a number
kapso whatsapp templates list --phone-number-id <id>

# Filter by status or category
kapso whatsapp templates list --phone-number-id <id> --status APPROVED --category UTILITY

# Get a specific template
kapso whatsapp templates get <template-id> --phone-number-id <id>

# Create a template from JSON
kapso whatsapp templates new --phone-number-id <id> --input template.json
```

## Webhooks

### Create a webhook

```bash theme={null}
kapso whatsapp webhooks new \
  --phone-number-id <id> \
  --url "https://example.com/webhook" \
  --event whatsapp.message.received \
  --event whatsapp.message.delivered \
  --active
```

Available events: `whatsapp.message.received`, `whatsapp.message.sent`, `whatsapp.message.delivered`, `whatsapp.message.read`, `whatsapp.message.failed`, `whatsapp.conversation.created`, `whatsapp.conversation.ended`, `whatsapp.conversation.inactive`, `whatsapp.contact.identity_changed`.

### Manage webhooks

```bash theme={null}
# List webhooks
kapso whatsapp webhooks list --phone-number-id <id>

# Update a webhook
kapso whatsapp webhooks update <webhook-id> --phone-number-id <id> --inactive

# Delete a webhook
kapso whatsapp webhooks delete <webhook-id> --phone-number-id <id>
```

### Message buffering

Buffer multiple `whatsapp.message.received` events into a single delivery:

```bash theme={null}
kapso whatsapp webhooks new \
  --phone-number-id <id> \
  --url "https://example.com/webhook" \
  --event whatsapp.message.received \
  --buffer-enabled \
  --buffer-window-seconds 5 \
  --max-buffer-size 10 \
  --active
```

## Customers

```bash theme={null}
# List customers
kapso customers list

# Get a customer
kapso customers get <customer-id>

# Create a customer
kapso customers new --name "Acme Corp" --external-id "acme-123"
```

## Local workflow development

Use these commands when you want to keep Kapso workflows and functions in a local repository.

```bash theme={null}
# Create a local workspace
mkdir kapso-workflows
cd kapso-workflows
npm init -y

# Optional: install the workflow code library
npm install --save-dev @kapso/workflows

# Link this directory to one Kapso project
kapso login
kapso link --project <project-id>
kapso pull
```

`kapso pull` writes local source files for workflows and functions. If you edit workflows with `@kapso/workflows`, build the generated JSON before pushing:

```bash theme={null}
kapso build
kapso push --dry-run
kapso push workflow <workflow-slug>
```

You can also push one function or everything in the repo:

```bash theme={null}
kapso push function <function-slug>
kapso push
```

If a pull is blocked by local edits, inspect or replace the incoming changes:

```bash theme={null}
kapso pull --diff
kapso pull --overwrite
```

See [Build locally](/docs/workflows/build-locally) for the full workflow source-control guide.

## Output formats

All commands support `--output json` or `--output human`. Most default to `json` — pipe into `jq` for scripting:

```bash theme={null}
kapso whatsapp numbers list --output json | jq '.[0].id'
```

## Help

```bash theme={null}
# General help
kapso help

# Help for a specific command
kapso help whatsapp messages send
```