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

# CLI

> Drive Wassist from your terminal — send and receive WhatsApp messages, manage numbers, and stream live events while you build.

The Wassist CLI is the fastest way to test agents and webhooks without leaving your terminal. It uses your existing Wassist account and the same `/api/v1` endpoints as the dashboard.

<Note>
  The CLI requires **Node.js 22+** (it uses the built-in `WebSocket` global). See the [GitHub source](https://github.com/wassist/cli) or `@wassist/cli` on npm.
</Note>

## Install

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

## Authenticate

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

You'll be prompted for your phone number, then a 6-digit code arrives on WhatsApp from the **Wassist sandbox number** — the same number you'll send test messages to in a moment.

Confirm you're signed in:

```bash theme={null}
wassist whoami
```

After login the CLI is automatically scoped to your **sandbox conversation** — a one-on-one chat between your personal WhatsApp and the Wassist sandbox number. Sandbox mode means most commands don't need a `[to-number]` argument.

<Tip>
  Switch between sandbox and a real WhatsApp number any time with `wassist use sandbox` or `wassist use <your-number>`.
</Tip>

## Sending messages

<Note>
  WhatsApp only lets you send free-form messages inside an active 24-hour customer-care window. Before your first `messages send`, either **message the Wassist sandbox number from your phone** to open the window, or send a pre-approved **template message** (see [Outside the 24-hour window](#outside-the-24-hour-window) below).
</Note>

The `messages send` command supports the full WhatsApp message envelope — text, media, buttons, and footers — composed via flags.

<Tabs>
  <Tab title="Text">
    ```bash theme={null}
    wassist messages send "Hello from the CLI"
    ```
  </Tab>

  <Tab title="With media">
    ```bash theme={null}
    wassist messages send "Check this out" \
      --media https://picsum.photos/200/300
    ```

    Supported types: JPEG, PNG, MP4, 3GPP, AAC, MP4 audio, MPEG, AMR, OGG, PDF, DOCX, XLSX, PPTX.
  </Tab>

  <Tab title="Quick replies">
    ```bash theme={null}
    wassist messages send "Choose one" \
      --reply "Yes|confirm" \
      --reply "No|deny"
    ```

    Max 3 quick replies. The pipe separates label from the value sent back when tapped.
  </Tab>

  <Tab title="URL button">
    ```bash theme={null}
    wassist messages send "Visit us" \
      --url-button "Shop Now|https://shop.com"
    ```

    Max 1 URL button. URL and quick-reply buttons cannot be mixed in the same message.
  </Tab>
</Tabs>

### Validation rules

* **Text body** — max 1024 characters.
* **Buttons** — max 3 total, all the same type.
* **Media** — must be a publicly reachable HTTPS URL.
* **Button labels** — max 20 characters, formatted `"Label|value"`.

### Outside the 24-hour window

If the conversation's customer-care 24-hour window has lapsed (no inbound user message in the last 24 hours), the CLI prompts you to pick a pre-approved template instead — the same constraint as the WhatsApp Business API enforces directly.

## Streaming inbound messages

`messages listen` opens a WebSocket session, so every inbound WhatsApp message lands in your terminal in real time. Behind the scenes Wassist creates a **managed webhook** for this session and tunnels it through a WebSocket relay — you don't need to expose a public URL.

```bash theme={null}
wassist messages listen --interactive
```

```text theme={null}
─── wassist messages listen ──────────────────────────────
[10:24] customer +447700900200
        Hey, can I add another item to my order?
> Sure! What would you like to add?
```

In interactive mode you can reply inline. The `> ` prompt accepts the same `--media`, `--url-button`, and `--reply` flags as `messages send`:

```text theme={null}
> Here's a photo --media https://picsum.photos/300 --reply "Looks good|yes" --reply "Try another|no"
```

<Tip>
  `messages listen` is ideal when you're iterating on an agent or a webhook handler and want to see events the instant they arrive. It runs alongside your own webhooks — both fire on every inbound message.
</Tip>

## Combining the CLI with webhooks

A common dev loop:

1. Configure your own webhook in the dashboard pointing at your local dev server (via your tunneling tool of choice — ngrok, Cloudflare Tunnel, Tailscale Funnel, etc.).
2. In another terminal, run `wassist messages listen` so you can watch inbound messages while your webhook is processing them.
3. Send a test event from the dashboard ([wassist.app/developers/webhooks](https://wassist.app/developers/webhooks) → your webhook → **Send test event**) or send a real message from your phone.
4. Inspect the delivery in **Developers → Webhooks → Deliveries** for the full request/response timeline, or click **Replay** to re-send it without retyping anything on WhatsApp.

See the [developer quickstart](/quickstart-developers) for an end-to-end walkthrough.

## Moving to your own number

The sandbox is great for development. To message real contacts, connect a WhatsApp Business number:

<Steps>
  <Step title="Upgrade your plan">
    ```bash theme={null}
    wassist upgrade
    ```

    A Wassist subscription is required to connect your own number.
  </Step>

  <Step title="Link your WhatsApp Business Account">
    ```bash theme={null}
    wassist numbers add
    ```

    Opens Meta's embedded signup in your browser so you can pick (or claim) a phone number.
  </Step>

  <Step title="Switch to your number">
    ```bash theme={null}
    wassist numbers list           # see numbers you can use
    wassist use 441234567890       # set the active number
    ```
  </Step>

  <Step title="Send messages to real contacts">
    With your own number active, include the recipient's E.164 number:

    ```bash theme={null}
    wassist messages send 441234567890 "Hey, this is from my own number!"
    wassist messages read 441234567890
    ```
  </Step>
</Steps>

To switch back to the sandbox: `wassist use sandbox`.

## Command reference

### Authentication

| Command          | Description                                   |
| ---------------- | --------------------------------------------- |
| `wassist login`  | Authenticate via WhatsApp OTP.                |
| `wassist whoami` | Show the authenticated user and current plan. |

### Number management

| Command                | Description                                                                |
| ---------------------- | -------------------------------------------------------------------------- |
| `wassist use <number>` | Set the active number. Use `sandbox` to switch back to the shared sandbox. |
| `wassist numbers list` | List all WhatsApp numbers, marking the active one.                         |
| `wassist numbers add`  | Add a new WhatsApp number (Starter plan or above).                         |

### Messaging

In sandbox mode the phone-number argument is optional — the CLI resolves your single sandbox conversation automatically.

| Command                                       | Description                                                                              |
| --------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `wassist messages list`                       | List conversations for the active number.                                                |
| `wassist messages read [phone-number]`        | View messages for a contact. Flags: `--limit <n>`, `--page <n>`.                         |
| `wassist messages send [to-number] [message]` | Send a message. Flags: `--footer`, `--media`, `--url-button`, `--reply` (repeatable).    |
| `wassist messages listen [phone-number]`      | Stream inbound messages over WebSocket. Flag: `-i` / `--interactive` for inline replies. |

### Billing

| Command           | Description                     |
| ----------------- | ------------------------------- |
| `wassist upgrade` | Upgrade your subscription plan. |

## Configuration

The CLI stores its auth token and active number locally via [conf](https://github.com/sindresorhus/conf). The default backend is `https://backend.wassist.app`; this can be overridden in the config file for development.

## Policies

By sending messages through the Wassist CLI you agree to:

* [WhatsApp Business Policy](https://business.whatsapp.com/policy) — opt-in, prohibited content, frequency, and platform rules.
* [Meta AI Provider pricing policy](https://developers.facebook.com/documentation/business-messaging/whatsapp/pricing/ai-providers/) — per-message pricing for AI-driven non-template messages in certain markets.

Violations may restrict your WhatsApp Business Account or Wassist account.