> ## 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](https://praison.ai/docs/docs/installation#package-structure) for the six-package install model.

## 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
```

> [!WARNING]
>
> **One process per Telegram token.** Telegram allows only one active `getUpdates` poller per bot token. If any of these are already running against the same token, start-up fails fast with `RuntimeError: Another process is already polling this Telegram token`:
>
> * `praisonai bot telegram --token $TELEGRAM_BOT_TOKEN`
> * `praisonai gateway start` with a `telegram` channel
> * Claw UI Channels worker with a `telegram` channel
> * An orphaned Python process from a previous crash
>
> Stop the other instance first, or use a different token for each environment (dev / staging / prod). Webhook mode is unaffected — the single-instance rule applies to long polling (the default) only. See [409 Conflict troubleshooting](#409-conflict-bot-stops-replying).

***

## 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
> ```
>
> This `playwright install chromium` step is required — no browsers are downloaded automatically by `pip install` in any tier.
>
> 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](https://praison.ai/docs/features/bot-browser-automation.md) for details.

### 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.

***

## 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.

### 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.

### 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.

### 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/
```

***

## Troubleshooting

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Single-instance rule"
        Token[🔑 Bot Token] --> Poller{One active poller?}
        Poller -->|Yes| OK[✅ Bot replies]
        Poller -->|No — 2+| Fail[❌ 409 Conflict / RuntimeError]
    end

    classDef input fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef check fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef good fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef bad fill:#8B0000,stroke:#7C90A0,color:#fff

    class Token input
    class Poller check
    class OK good
    class Fail bad
```

### 409 Conflict — bot stops replying

**Symptom.** The bot starts, then messages stop being answered, or start-up exits with a non-zero code. Logs show:

```
[telegram] Another process is already polling this token
(only one instance per token is allowed).
Stop the other bot/gateway/UI-channel instance first.
```

**Cause.** A second poller (CLI `bot telegram`, a gateway `telegram` channel, Claw Channels, or an orphaned process) is using the same token. Telegram's `getUpdates` API allows only one active consumer per bot token, so every extra poller receives HTTP `409 Conflict`. The adapter fails fast on a confirmed 409 instead of silently looping.

**Fix.**

> [tab] macOS / Linux
>
> ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> # 1. Find every Python process that mentions praisonai
> ps aux | grep -i praisonai | grep -v grep
>
> # 2. Kill duplicates (replace <PID>)
> kill <PID>
>
> # 3. Confirm webhook is not set (long-polling mode)
> curl "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getWebhookInfo"
>
> # 4. Restart exactly one bot
> praisonai bot telegram --token $TELEGRAM_BOT_TOKEN
> ```

> [tab] Windows (PowerShell)
>
> ```powershell theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> # 1. Find running Python processes
> Get-Process python | Format-Table Id, CPU, StartTime -AutoSize
>
> # 2. Stop all Python processes (careful — kills every python.exe)
> Get-Process python -ErrorAction SilentlyContinue | Stop-Process -Force
> Start-Sleep -Seconds 3
>
> # 3. Restart exactly one bot
> $env:TELEGRAM_BOT_TOKEN = "..."
> praisonai bot telegram --token $env:TELEGRAM_BOT_TOKEN
> ```

**Prevention.**

* Use one token per environment (dev / staging / prod).
* Prefer **webhook mode** in production — multiple processes can share the same webhook target without conflict.
* Don't run `praisonai bot telegram` and Claw Channels against the same token at the same time.

***

## Inspecting the outbound queue

Operator inspection of the durable outbound queue lives under `praisonai gateway outbox …`, not `praisonai bot …`. To list, retry, or purge stuck outbound replies, use the [Outbox Operator CLI](https://praison.ai/docs/features/outbox-operator-cli.md) — `praisonai gateway outbox list|stats|retry|purge`. Inbound failures instead go through `praisonai bot dlq …` (see [Inbound DLQ](https://praison.ai/docs/features/inbound-dlq.md)).

***

## Related

> [card] [Messaging Bots](https://praison.ai/docs/features/messaging-bots.md)
>
> Full messaging bots documentation

> [card] [Audio Tools](https://praison.ai/docs/features/audio-tools.md)
>
> TTS and STT tools

> [card] [Browser CLI](https://praison.ai/docs/cli/browser.md)
>
> Browser control commands

> [card] [Bot Browser Automation](https://praison.ai/docs/features/bot-browser-automation.md)
>
> Give a bot a local Playwright browser with `--browser`

> [card] [Bot Streaming Replies](https://praison.ai/docs/features/bot-streaming-replies.md)
>
> Progressive live replies with `--stream`

> [card] [Bot vs Gateway](https://praison.ai/docs/concepts/bot-vs-gateway.md)
>
> Choose the right deployment model

> [card] [Outbox Operator CLI](https://praison.ai/docs/features/outbox-operator-cli.md)
>
> Inspect, retry, and purge the outbound queue with `praisonai gateway outbox`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.