Skip to main content

⚡ Botable CLI

Generate Telegram bots with AI — from idea to running bot in 3 minutes.

PyPI Python License: MIT

Quick Start

pip install "botable-dev[mcp]"
botable login
botable mcp install

# Create a project
botable init my-bot
cd my-bot

# Add your keys to .env
echo "BOT_TOKEN=your-telegram-token" >> .env
echo "OPENAI_API_KEY=sk-..." >> .env

# Generate a bot from a description
botable generate "a FAQ bot for my restaurant with menu and hours"

# Run locally
botable dev

That's it. Your bot is running in under 3 minutes.

Commands

Local Development

Command Description
botable init [name] Scaffold a new bot project
botable generate "description" Generate bot from natural language
botable dev Run bot locally with live output
botable dev --watch Run with hot reload on file changes
botable version Show CLI version and effective API URL

Cloud Deployment

Command Description
botable login [--no-browser] Sign in through the browser
botable login --api-key KEY [--api-url URL] Save an existing API key and API URL
botable mcp install [--target claude|codex|all] [--scope user|project] Configure agent MCP clients
botable logout Remove stored authentication
botable deploy Deploy to Botable cloud
botable logs [project_id] Show the current bot status snapshot
botable bots list List all deployed bots
botable bots stop {id} Stop a running bot

Deploy to Cloud

botable login

# Deploy your bot
botable deploy

# Check status
botable bots list
botable logs

Configuration

Botable uses a 3-layer config system:

File Scope Purpose
botable.toml Project Bot name, template, branding (committed to git)
.env Project Secrets: BOT_TOKEN, API keys (NOT committed)
~/.config/botable/config.toml User Global defaults, auth token

botable login --api-url URL saves the API URL. BOTABLE_API_URL overrides it for the current process; otherwise the default is https://api-staging.botable.dev (staging, until the CLI routes reach production). Run botable version to see the effective URL.

Use Botable from Claude Code / Codex

In Botable's Code tab, export your bot project. The export contains botable.toml with the project ID. Edit the files locally, then run botable deploy from that directory to deploy the same project. The CLI deployment routes currently work on staging, which is the default API URL:

botable login
botable mcp install
botable version
cd path/to/exported-bot
botable deploy
botable bots list
botable logs PROJECT_ID

botable deploy uploads the project's .env file, including any secrets in it. Check its contents before deployment. botable logs currently returns a status snapshot; runtime log lines and live streaming are not available through the CLI API yet.

botable mcp install registers the installed botable-mcp executable with Claude Code and Codex. Use --target to select one client. Claude uses its claude mcp add command when installed; without Claude, --scope project writes project .mcp.json (the default user scope requires Claude). Codex configuration goes in ~/.codex/config.toml with a backup of an existing file. Check with claude mcp list or codex mcp list.

The MCP server exposes project creation, generation, templates, local development, deployment, bot listing, status, and the available status snapshot through its logs tool. Its former SSH staging status tool was removed because it requires operator access and is unrelated to customer bots. The MCP server uses the API URL and key saved by botable login (or the BOTABLE_API_URL environment override).

Branding

Every generated bot includes a # Built with Botable comment. Customize or disable it:

# In botable.toml (per-project)
[branding]
enabled = true
text = "Built with Botable (botable.dev)"
style = "comment"  # "comment" | "docstring" | "none"

To disable globally:

# In ~/.config/botable/config.toml
[branding]
enabled = false

How It Works

  1. botable init — creates project structure with botable.toml + .env
  2. botable generate — calls OpenAI to generate aiogram bot code, validates syntax, writes main.py + requirements.txt
  3. botable dev — creates a venv, installs deps, runs your bot with live output
  4. botable deploy — packages project, uploads to Botable cloud, deploys automatically

Generated bots use aiogram (MIT license) — async-native, production-ready.

Development

git clone https://github.com/Botable-dev/cli.git
cd cli
pip install -e ".[dev]"
pytest

License

MIT — see LICENSE for details.


⚡ Built with Botable

Metadata

Release files for botable-dev 0.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for botable-dev 0.3.1
File Size Uploaded Provenance Actions
botable_dev-0.3.1.tar.gz 42.6 kB With provenance Details for botable_dev-0.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for botable-dev 0.3.1
File Interpreter ABI Platform Actions
botable_dev-0.3.1-py3-none-any.whl Python 3 none any Details for botable_dev-0.3.1-py3-none-any.whl

Total release size: 73.5 kB

Release files / botable_dev-0.3.1.tar.gz

Download URL botable_dev-0.3.1.tar.gz
Size 42.6 kB
Tags Source
SHA-256 checksum
How to use checksums
c13344bcf409da8cbed4ec27e4d4a82cb80947e643c00987af44e5934a265e9a
BLAKE2b-256 checksum
How to use checksums
9893e758e1abe20dc66d571b65226cd8ad5b7e8c8d58bb3bf75fe0cbba205167
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.

Transparency log

Release files / botable_dev-0.3.1-py3-none-any.whl

Download URL botable_dev-0.3.1-py3-none-any.whl
Size 30.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d2d9cafd467a095840bffba68f1204792909bdac2e8d2547772f3b29b8a7b2ec
BLAKE2b-256 checksum
How to use checksums
ac5a7e2240ddb88d66e593f6e9e6aeace4aef6dfec11bb9c0b005f1952892717
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.

Transparency log

Security for botable-dev 0.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for botable_dev-0.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.3.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page