Bot CLI - PraisonAI

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

praisonai bot is a wrapper-required command. It is only available when the full praisonai package is installed:

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 for the six-package install model.

Quick Start

# 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

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.

Command Reference

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.

Local automation needs the Playwright extra and a Chromium download:

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

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

praisonai bot telegram --token $TELEGRAM_BOT_TOKEN

With Custom Agent

praisonai bot slack --token $SLACK_BOT_TOKEN --app-token $SLACK_APP_TOKEN --agent agents.yaml

agents.yaml:

name: support-bot
instructions: |
  You are a customer support assistant.
  Be helpful and concise.
llm: gpt-4o-mini
tools:
  - search_web

With Full Capabilities

praisonai bot telegram --token $TOKEN \
  --agent agents.yaml \
  --browser \
  --web \
  --memory \
  --model gpt-4o

With Specific Tools

praisonai bot discord --token $TOKEN \
  --tools DuckDuckGoTool WikipediaTool GitHubTool

With Knowledge Base

praisonai bot slack --token $SLACK_BOT_TOKEN --app-token $SLACK_APP_TOKEN \
  --knowledge \
  --memory

With Auto-Approve (Trusted Environment)

# 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

Use --auto-approve only in trusted environments. This skips all confirmation prompts for tool executions.

With Live Streaming Replies

# 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

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)

# 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

# Cloud API mode (requires Meta developer account)
praisonai bot whatsapp --token $WHATSAPP_ACCESS_TOKEN --phone-id $WHATSAPP_PHONE_NUMBER_ID

WhatsApp Web Mode

# 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

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

Email Bot

# 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

# 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

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

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.

macOS / Linux
Windows (PowerShell)

# 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

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

Messaging Bots

Full messaging bots documentation

Audio Tools

TTS and STT tools

Browser CLI

Browser control commands

Bot Browser Automation

Give a bot a local Playwright browser with --browser

Bot Streaming Replies

Progressive live replies with --stream

Bot vs Gateway

Choose the right deployment model

​Quick Start

​Command Reference

​Platforms

​Capability Options

​Model & Agent

​Browser

​Web Search

​Tools & Skills

​Memory & Knowledge

​Execution

​WhatsApp-Specific

​Email-Specific

​Linear-Specific

​AgentMail-Specific

​Audio (TTS/STT)

​Streaming (progressive replies)

​Examples

​Basic Bot

​With Custom Agent

​With Full Capabilities

​With Specific Tools

​With Knowledge Base

​With Auto-Approve (Trusted Environment)

​With Live Streaming Replies

​With TTS/STT (Voice)

​WhatsApp Cloud API

​WhatsApp Web Mode

​Email Bot

​AgentMail Bot

​Environment Variables

​Agent YAML Schema

​Troubleshooting

​409 Conflict — bot stops replying

​Related