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

# CLI

> @keebai/cli — the official command-line tool to authenticate, connect WhatsApp Business channels, manage Personal Access Tokens (PATs), and send messages straight from your terminal.

The official Keebai CLI. The fastest way to mint your first PAT (`kbai_pk_...`), connect a WhatsApp Business channel, and send a test message without touching the portal or writing code.

```bash theme={null}
npm install -g @keebai/cli
keebai login
keebai whatsapp connect
keebai whatsapp messages send --from <channel> --to +15551234567 --text "hello"
```

## Why use it

<CardGroup cols={2}>
  <Card title="Auth in one command" icon="key">
    `keebai login` runs the OAuth Device Authorization flow (RFC 8628), opens your browser, and saves your PAT to `~/.keebai/credentials.json` with `0600` permissions.
  </Card>

  <Card title="Connect WhatsApp without the portal" icon="plug">
    `keebai whatsapp connect` launches Meta Embedded Signup, or pass `--qr` for multi-device QR pairing. No UI needed.
  </Card>

  <Card title="Send messages from your shell" icon="terminal">
    Free-form text, templates with variables, custom metadata — all from `keebai whatsapp messages send`.
  </Card>

  <Card title="Same token everywhere" icon="link">
    The PAT issued by the CLI works in the SDK, in `curl`, and in any HTTP client against `api.keebai.com/v1`.
  </Card>
</CardGroup>

## Installation

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

Requires Node.js **20+**. After install, the `keebai` binary lives in your `PATH`.

Without a global install:

```bash theme={null}
npx @keebai/cli@latest login
```

## Authentication

`keebai login` runs the [OAuth 2.0 Device Authorization Grant flow (RFC 8628)](https://datatracker.ietf.org/doc/html/rfc8628):

1. The CLI requests a `device_code` and `user_code` from the public API.
2. Your browser opens at `https://developers.keebai.com/cli?code=ABCD-1234`.
3. You sign in to the developer portal (if you aren't already) and confirm the request.
4. The CLI finishes polling and saves the PAT (`kbai_pk_...`) to `~/.keebai/credentials.json` with mode `0600`.

```bash theme={null}
keebai login                            # interactive — opens the browser
keebai login --no-browser               # headless — prints the URL to open manually
keebai login --scope "messages:write webhooks:read"
```

For CI or non-interactive contexts, you can skip `login` and inject a long-lived PAT via env var. It takes precedence over credentials saved on disk:

```bash theme={null}
export KEEBAI_API_TOKEN=kbai_pk_xxxxxxxxxxxx
keebai whoami
```

## Commands

### Auth

| Command         | Description                                                                                 |
| --------------- | ------------------------------------------------------------------------------------------- |
| `keebai login`  | Device flow; saves the PAT to `~/.keebai/credentials.json`.                                 |
| `keebai whoami` | Shows the user, company, and scopes of the active token.                                    |
| `keebai logout` | Revokes the PAT server-side and deletes local credentials. `--local-only` skips the revoke. |

### WhatsApp

| Command                         | Description                                                              |
| ------------------------------- | ------------------------------------------------------------------------ |
| `keebai whatsapp connect`       | Connects a WhatsApp Business channel via Meta Embedded Signup (browser). |
| `keebai whatsapp connect --qr`  | Pairs a channel via QR in the terminal (multi-device). No browser.       |
| `keebai whatsapp numbers list`  | Lists the WhatsApp numbers connected to your company.                    |
| `keebai whatsapp messages send` | Sends free-form text or an approved template.                            |

#### Connect a channel (Embedded Signup)

```bash theme={null}
keebai whatsapp connect
keebai whatsapp connect --coexistence            # the number already runs the WhatsApp Business app
keebai whatsapp connect --pipeline-id <id>       # attach to an existing pipeline
```

#### Connect a channel (multi-device QR)

```bash theme={null}
keebai whatsapp connect --qr
keebai whatsapp connect --qr --name "Sales line"
```

#### Send messages

`--from` accepts a `channel_id` (24-hex), a `phone_number_id`, or the number in E.164.

Free-form text (only inside the 24h window):

```bash theme={null}
keebai whatsapp messages send \
  --from +15551234567 \
  --to +15557654321 \
  --text "hi, we'll get back to you shortly"
```

Approved template:

```bash theme={null}
keebai whatsapp messages send \
  --from <channel_id> \
  --to +15557654321 \
  --template welcome_v2 \
  --language en_US \
  --var name=Alex --var amount=1500
```

Free-form metadata for downstream automations:

```bash theme={null}
keebai whatsapp messages send \
  --from <channel_id> --to +15557654321 --text "ping" \
  --meta '{"source":"crm","ticket":"T-123"}'
```

## Using your token directly

After `keebai login`, the PAT lives in `~/.keebai/credentials.json` under the `access_token` field. Use it as a Bearer token against `https://api.keebai.com/v1/...`:

```bash theme={null}
TOKEN=$(jq -r .access_token ~/.keebai/credentials.json)

curl https://api.keebai.com/v1/me \
  -H "Authorization: Bearer $TOKEN"

curl https://api.keebai.com/v1/webhooks \
  -H "Authorization: Bearer $TOKEN"

curl https://api.keebai.com/v1/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"channel":"whatsapp","to":"+15551234567","message":{"type":"template","name":"welcome","language":"en_US"}}'
```

## Global flags

| Flag                      | Description                                                            |
| ------------------------- | ---------------------------------------------------------------------- |
| `--output <pretty\|json>` | Output format. Default: `pretty`. Use `json` for programmatic parsing. |
| `--no-browser`            | Don't open the browser automatically on login or connect.              |
| `--verbose`               | Verbose logs to stderr for diagnostics.                                |

## Environment variables

| Variable           | What it does                                                                                   |
| ------------------ | ---------------------------------------------------------------------------------------------- |
| `KEEBAI_API_TOKEN` | Inject a PAT for non-interactive use (CI). Takes precedence over `~/.keebai/credentials.json`. |

## Endpoints the CLI hits

The CLI talks exclusively to `https://api.keebai.com/v1/...`. Browser flows (login approval, channel connect) happen at `https://developers.keebai.com/cli` and `https://connect.keebai.com/connect/whatsapp` respectively.

## Resources

<CardGroup cols={2}>
  <Card title="npm: @keebai/cli" icon="npm" href="https://www.npmjs.com/package/@keebai/cli">
    Latest version, changelog, install stats.
  </Card>

  <Card title="TypeScript SDK" icon="code" href="/dev/sdks/typescript">
    The same PAT works in the SDK for code integrations.
  </Card>

  <Card title="Agent Skills" icon="robot" href="/dev/sdks/agent-skills">
    The `integrate-keebai-whatsapp` skill for AI agents that use this SDK.
  </Card>

  <Card title="API Keys" icon="key" href="/dev/api-keys">
    How to create, list, and revoke tokens from the portal (alternative to `keebai login`).
  </Card>
</CardGroup>