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

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

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/

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

​Related