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

# Bot CLI

> Deploy AI agents to messaging platforms via CLI

Start messaging bots with a single command. Supports Telegram, Discord, Slack, WhatsApp, Linear, Email, and AgentMail with full capability options.

<Warning>
  `praisonai bot` is a **wrapper-required command**. It is only available when the full `praisonai` package is installed:

  ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  pip install praisonai
  ```

  If you installed only `praisonai-code`, this command will not appear in `--help` and will fail at dispatch time. See [Package Structure](/docs/docs/installation#package-structure) for the six-package install model.
</Warning>

## Quick Start

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Telegram
praisonai bot telegram --token $TELEGRAM_BOT_TOKEN

# Discord
praisonai bot discord --token $DISCORD_BOT_TOKEN

# Slack (requires both tokens)
praisonai bot slack --token $SLACK_BOT_TOKEN --app-token $SLACK_APP_TOKEN

# WhatsApp Cloud API
praisonai bot whatsapp --token $WHATSAPP_ACCESS_TOKEN --phone-id $WHATSAPP_PHONE_NUMBER_ID

# WhatsApp Web Mode (no tokens needed — scan QR code)
praisonai bot whatsapp --mode web

# Linear (AgentSession webhooks)
praisonai bot linear --token $LINEAR_OAUTH_TOKEN --signing-secret $LINEAR_WEBHOOK_SECRET

# Email (IMAP/SMTP)
praisonai bot email --token $EMAIL_APP_PASSWORD --email user@gmail.com

# AgentMail (API-first, zero IMAP/SMTP config)
praisonai bot agentmail --token $AGENTMAIL_API_KEY
```

***

## Command Reference

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai bot <platform> [OPTIONS]
```

### Platforms

| Platform    | Required Tokens                                                      |
| ----------- | -------------------------------------------------------------------- |
| `telegram`  | `--token`                                                            |
| `discord`   | `--token`                                                            |
| `slack`     | `--token` + `--app-token`                                            |
| `whatsapp`  | `--token` + `--phone-id` (Cloud API) **or** `--mode web` (no tokens) |
| `linear`    | `--token` + `--signing-secret`                                       |
| `email`     | `--token` (App Password) + `--email`                                 |
| `agentmail` | `--token` (API key)                                                  |

***

## Capability Options

Enable agent capabilities via CLI flags:

### Model & Agent

| Option                | Description                                                                                                                                                                                                          |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--agent FILE`        | Agent YAML configuration file                                                                                                                                                                                        |
| `--model`, `-m MODEL` | LLM model (e.g., `gpt-4o`, `claude-sonnet-4-20250514`, `gemini/gemini-2.0-flash`). When `--browser` is enabled, this same model drives the browser tool's internal decisions (defaults to `gpt-4o-mini` if omitted). |
| `--thinking MODE`     | Thinking mode: `off`, `minimal`, `low`, `medium`, `high`                                                                                                                                                             |

### Browser

`--browser` prefers a **local Playwright** browser (no cloud API key) and falls back to the cloud `BrowserBaseTool` only when the local browser is unavailable.

| Option                   | Description                                                                                                                      |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `--browser`              | Enable the browser tool. Prefers local Playwright automation; falls back to cloud.                                               |
| `--browser-profile NAME` | Browser profile name (default: `default`). Currently accepted but not applied — the local Playwright agent uses a fresh context. |
| `--browser-headless`     | Run the local Chromium without a visible window.                                                                                 |

<Note>
  Local automation needs the Playwright extra and a Chromium download:

  ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  pip install "praisonai-browser[playwright]"
  playwright install chromium
  ```

  Without those, `--browser` falls back to the cloud `BrowserBaseTool` (which needs BrowserBase credentials), or — if neither is installed — becomes a no-op with a startup warning. See [Bot Browser Automation](/docs/features/bot-browser-automation) for details.
</Note>

### Web Search

| Option                    | Description                                       |
| ------------------------- | ------------------------------------------------- |
| `--web`                   | Enable web search with provider-specific tools    |
| `--web-provider PROVIDER` | Search provider: `duckduckgo`, `tavily`, `serper` |

### Tools & Skills

| Option              | Description                                                            |
| ------------------- | ---------------------------------------------------------------------- |
| `--tools TOOL...`   | Enable additional tools by name (e.g., `DuckDuckGoTool WikipediaTool`) |
| `--skills SKILL...` | Enable specific skills                                                 |
| `--skills-dir DIR`  | Custom skills directory path                                           |

### Memory & Knowledge

| Option                          | Description                            |
| ------------------------------- | -------------------------------------- |
| `--memory`                      | Enable persistent memory               |
| `--memory-provider PROVIDER`    | Memory provider (default: `default`)   |
| `--knowledge`                   | Enable knowledge/RAG                   |
| `--knowledge-sources SOURCE...` | Knowledge sources to load              |
| `--session-id ID`               | Session ID for conversation continuity |
| `--user-id ID`                  | User ID for memory isolation           |

### Execution

| Option           | Description                                                  |
| ---------------- | ------------------------------------------------------------ |
| `--sandbox`      | Enable sandbox execution mode                                |
| `--exec`         | Enable exec tool explicitly                                  |
| `--auto-approve` | Auto-approve all tool executions (skip confirmation prompts) |

### WhatsApp-Specific

| Option                       | Description                                                                |
| ---------------------------- | -------------------------------------------------------------------------- |
| `--mode MODE`                | Connection mode: `cloud` (default) or `web` (QR code, no tokens)           |
| `--phone-id ID`              | WhatsApp Phone Number ID (Cloud API)                                       |
| `--verify-token TOKEN`       | Webhook verify token (Cloud API)                                           |
| `--respond-to NUMBERS`       | Allowlist phone numbers (Web mode, comma-separated)                        |
| `--respond-to-groups GROUPS` | Allowlist group JIDs (Web mode, comma-separated)                           |
| `--respond-to-all`           | Respond to all messages (Web mode, default: self-chat only)                |
| `--creds-dir DIR`            | Custom credentials directory (Web mode, default: `~/.praisonai/whatsapp/`) |

### Email-Specific

| Option               | Description                                            |
| -------------------- | ------------------------------------------------------ |
| `--email ADDRESS`    | Bot email address (or `EMAIL_ADDRESS` env var)         |
| `--imap-server HOST` | IMAP server (default: auto-detected from email domain) |
| `--smtp-server HOST` | SMTP server (default: auto-detected from email domain) |

### Linear-Specific

| Option                    | Description                                                |
| ------------------------- | ---------------------------------------------------------- |
| `--signing-secret SECRET` | Linear webhook signing secret (or `LINEAR_WEBHOOK_SECRET`) |
| `--port PORT`             | Webhook server port (default: `8080`)                      |

### AgentMail-Specific

| Option             | Description                                                 |
| ------------------ | ----------------------------------------------------------- |
| `--mode MODE`      | Reception mode: `poll` (default), `ws`, `webhook`, `hybrid` |
| `--inbox INBOX_ID` | Existing inbox to connect to (or `AGENTMAIL_INBOX_ID`)      |
| `--domain DOMAIN`  | Custom domain for new inboxes (or `AGENTMAIL_DOMAIN`)       |

### Audio (TTS/STT)

| Option              | Description                                                    |
| ------------------- | -------------------------------------------------------------- |
| `--tts`             | Enable TTS tool for text-to-speech                             |
| `--tts-voice VOICE` | TTS voice: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer` |
| `--tts-model MODEL` | TTS model (default: `openai/tts-1`)                            |
| `--auto-tts`        | Auto-convert all responses to speech                           |
| `--stt`             | Enable STT tool for speech-to-text                             |
| `--stt-model MODEL` | STT model (default: `openai/whisper-1`)                        |

### Streaming (progressive replies)

| Option                      | Description                                                                          |
| --------------------------- | ------------------------------------------------------------------------------------ |
| `--stream`                  | Enable progressive streaming responses (bot edits the message live as tokens arrive) |
| `--stream-edit-interval MS` | Minimum interval between edits in milliseconds (default: `700`)                      |

<Note>
  **Default Tools (Always Enabled)**:

  * `execute_command` - Run shell commands
  * `search_web` - Web search with auto-fallback providers

  The `--exec` and `--web` flags add **additional** provider-specific tools on top of defaults.
</Note>

***

## Examples

### Basic Bot

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai bot telegram --token $TELEGRAM_BOT_TOKEN
```

### With Custom Agent

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai bot slack --token $SLACK_BOT_TOKEN --app-token $SLACK_APP_TOKEN --agent agents.yaml
```

**agents.yaml:**

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
name: support-bot
instructions: |
  You are a customer support assistant.
  Be helpful and concise.
llm: gpt-4o-mini
tools:
  - search_web
```

### With Full Capabilities

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai bot telegram --token $TOKEN \
  --agent agents.yaml \
  --browser \
  --web \
  --memory \
  --model gpt-4o
```

### With Specific Tools

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai bot discord --token $TOKEN \
  --tools DuckDuckGoTool WikipediaTool GitHubTool
```

### With Knowledge Base

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai bot slack --token $SLACK_BOT_TOKEN --app-token $SLACK_APP_TOKEN \
  --knowledge \
  --memory
```

### With Auto-Approve (Trusted Environment)

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Auto-approve all tool executions - useful for trusted environments
praisonai bot slack --token $SLACK_BOT_TOKEN --app-token $SLACK_APP_TOKEN \
  --auto-approve \
  --exec \
  --web
```

<Warning>
  Use `--auto-approve` only in trusted environments. This skips all confirmation prompts for tool executions.
</Warning>

### With Live Streaming Replies

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Default streaming (edits every 700ms)
praisonai bot telegram --token $TELEGRAM_BOT_TOKEN --stream

# Slower edits for stricter rate limits
praisonai bot telegram --token $TELEGRAM_BOT_TOKEN \
  --stream \
  --stream-edit-interval 1500
```

<Tip>
  Streaming is currently wired up for Telegram. Other channels fall back to single-message mode until their adapters add streaming support.
</Tip>

### With TTS/STT (Voice)

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Enable TTS tool - agent can convert text to speech
praisonai bot telegram --token $TOKEN --tts

# Auto-convert all responses to speech
praisonai bot telegram --token $TOKEN --auto-tts --tts-voice nova

# Full voice capabilities
praisonai bot telegram --token $TOKEN --tts --stt --memory
```

### WhatsApp Cloud API

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Cloud API mode (requires Meta developer account)
praisonai bot whatsapp --token $WHATSAPP_ACCESS_TOKEN --phone-id $WHATSAPP_PHONE_NUMBER_ID
```

### WhatsApp Web Mode

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Web mode — scan QR code, no tokens needed
praisonai bot whatsapp --mode web

# With specific allowed contacts
praisonai bot whatsapp --mode web --respond-to 1234567890,9876543210

# With memory and web search
praisonai bot whatsapp --mode web --memory --web
```

<Warning>
  WhatsApp Web mode uses a reverse-engineered protocol. Your number may be banned by Meta. Use Cloud API mode for production.
</Warning>

### Email Bot

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# IMAP/SMTP email bot
praisonai bot email --token $EMAIL_APP_PASSWORD --email bot@gmail.com

# With memory and web search
praisonai bot email --token $EMAIL_APP_PASSWORD --email bot@gmail.com --memory --web
```

### AgentMail Bot

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# API-first email (auto-creates inbox)
praisonai bot agentmail --token $AGENTMAIL_API_KEY

# With specific inbox
praisonai bot agentmail --token $AGENTMAIL_API_KEY --inbox you@agentmail.to

# With custom domain
praisonai bot agentmail --token $AGENTMAIL_API_KEY --domain mycompany.com

# WebSocket mode (sub-second latency)
praisonai bot agentmail --token $AGENTMAIL_API_KEY --mode ws

# Hybrid mode (recommended for production)
praisonai bot agentmail --token $AGENTMAIL_API_KEY --mode hybrid
```

***

## Environment Variables

| Variable                   | Description                                    |
| -------------------------- | ---------------------------------------------- |
| `TELEGRAM_BOT_TOKEN`       | Telegram bot token from @BotFather             |
| `DISCORD_BOT_TOKEN`        | Discord bot token                              |
| `SLACK_BOT_TOKEN`          | Slack Bot User OAuth Token (`xoxb-...`)        |
| `SLACK_APP_TOKEN`          | Slack App-Level Token (`xapp-...`)             |
| `WHATSAPP_ACCESS_TOKEN`    | WhatsApp Cloud API access token                |
| `WHATSAPP_PHONE_NUMBER_ID` | WhatsApp Business phone number ID              |
| `WHATSAPP_VERIFY_TOKEN`    | Webhook verification token (any secret string) |
| `WHATSAPP_CREDS_DIR`       | Custom credentials directory for Web mode      |
| `EMAIL_ADDRESS`            | Email bot address                              |
| `EMAIL_APP_PASSWORD`       | Email App Password                             |
| `EMAIL_IMAP_SERVER`        | IMAP server (auto-detected by default)         |
| `EMAIL_SMTP_SERVER`        | SMTP server (auto-detected by default)         |
| `AGENTMAIL_API_KEY`        | AgentMail API key                              |
| `AGENTMAIL_INBOX_ID`       | AgentMail inbox to connect to                  |
| `AGENTMAIL_DOMAIN`         | Custom domain for new AgentMail inboxes        |
| `OPENAI_API_KEY`           | OpenAI API key for LLM                         |

***

## Agent YAML Schema

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
name: my-bot
instructions: |
  You are a helpful assistant.
  Be concise and friendly.
llm: gpt-4o-mini
tools:
  - search_web
  - DuckDuckGoTool
memory: true
knowledge:
  - ./docs/
```

***

## Related

<CardGroup cols={2}>
  <Card title="Messaging Bots" icon="comments" href="/docs/features/messaging-bots">
    Full messaging bots documentation
  </Card>

  <Card title="Audio Tools" icon="microphone" href="/docs/features/audio-tools">
    TTS and STT tools
  </Card>

  <Card title="Browser CLI" icon="globe" href="/docs/cli/browser">
    Browser control commands
  </Card>

  <Card title="Bot Browser Automation" icon="globe" href="/docs/features/bot-browser-automation">
    Give a bot a local Playwright browser with `--browser`
  </Card>

  <Card title="Bot Streaming Replies" icon="message-pen" href="/docs/features/bot-streaming-replies">
    Progressive live replies with `--stream`
  </Card>

  <Card title="Bot vs Gateway" icon="code-compare" href="/docs/concepts/bot-vs-gateway">
    Choose the right deployment model
  </Card>
</CardGroup>