botable-dev 0.3.1__tar.gz

botable_dev-0.3.1/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CLI CI
+
+on:
+  push:
+    branches: [main, stage]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src/
+
+      - name: Run tests
+        run: pytest tests/ -v --tb=short

botable_dev-0.3.1/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+# Trusted Publishing (OIDC): PyPI trusts this workflow of Botable-dev/cli for the botable-dev project,
+# so no API token is stored anywhere. A release is a pushed tag v<version> matching pyproject.toml.
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    # GitHub-hosted minutes are exhausted for the org; pc-3060 is the org-level self-hosted runner (private repos only).
+    runs-on: [self-hosted, Linux, pc-3060]
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Check tag matches the package version
+        run: |
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "v${version}" = "${GITHUB_REF_NAME}" || { echo "tag ${GITHUB_REF_NAME} != v${version}"; exit 1; }
+
+      - name: Build package
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Summary
+        run: |
+          echo "### Published botable-dev ${GITHUB_REF_NAME} to PyPI" >> "$GITHUB_STEP_SUMMARY"
+          echo '`pip install "botable-dev[mcp]"`' >> "$GITHUB_STEP_SUMMARY"

botable_dev-0.3.1/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+venv/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.ruff_cache/
+.pytest_cache/
+dev_logs/

botable_dev-0.3.1/AGENTS.md

@@ -0,0 +1,114 @@
+# AGENTS.md -- CLI
+
+## Update Rules
+
+- **Owner**: cli repo (`Botable-dev/cli`)
+- Update when: new CLI command added, status bot changed, config format changed
+- Do NOT duplicate backend API details here -- those live in `backend/AGENTS.md`
+- Max 150 lines. Every line must earn its place.
+
+---
+
+## Purpose
+
+PyPI package **`botable`** (v0.2.0) -- Typer-based CLI for generating Telegram bots via the
+Botable platform API. Also contains the **Telegram status bot** for staging server monitoring.
+Stack: **Typer**, **Rich**, **httpx**, **OpenAI** (for local generation).
+
+---
+
+## Directory Map
+
+```
+cli/
+  pyproject.toml               # Package metadata, version, dependencies (hatchling build)
+  src/
+    botable/
+      __init__.py              # __version__
+      __main__.py              # `python -m botable` entry
+      cli.py                   # Typer app, all commands registered here
+      mcp_install.py           # Claude/Codex MCP config registration
+      config.py                # 3-layer config merge (defaults -> user -> project)
+      api_client.py            # httpx client for backend API
+      generate.py              # Bot generation logic (local + remote)
+      runner.py                # Bot runner (start generated bot locally)
+      scaffold.py              # Project scaffolding / init
+      prompts.py               # Interactive prompts (Rich)
+      ui.py                    # Rich output helpers (banner, success, error, info)
+      errors.py                # APIError from httpx responses
+  botable_status_bot/
+    __init__.py
+    __main__.py                # `python -m botable_status_bot`
+    bot.py                     # aiogram Telegram bot -- /status, /health, /services
+    collectors.py              # SSH + Docker data collectors
+    config.py                  # Bot token, SSH host, chat IDs
+    formatters.py              # Rich-text formatting for Telegram messages
+    scheduler.py               # Periodic health check scheduler
+    Dockerfile                 # Container for running on staging
+    requirements.txt           # Bot-specific dependencies
+    setup.sh                   # Setup script for staging deployment
+  tests/                       # pytest tests
+  botable_mcp/server.py        # MCP tools backed by the CLI
+  dev_logs/                    # Development notes
+```
+
+---
+
+## CLI Commands
+
+Entry point: `botable = "botable.cli:app"` (defined in `pyproject.toml`).
+
+| Command             | Purpose                                      |
+|---------------------|----------------------------------------------|
+| `botable generate`  | Generate a bot from description (API or local)|
+| `botable dev`       | Run generated bot in dev mode                |
+| `botable deploy`    | Deploy bot to server (`--json` for agents)   |
+| `botable logs`      | Show bot status snapshot (`--json` supported) |
+| `botable version`   | Show version and effective API URL           |
+| `botable login`     | Browser device login or `--api-key`          |
+| `botable mcp install` | Register Claude Code and/or Codex MCP     |
+| `botable bots`      | List user's bots                             |
+| `botable templates` | Browse available templates                   |
+| `botable credits`   | Check credit balance                         |
+
+Auth token and optional API URL stored via `config.py` after browser login or `botable login --api-key YOUR_KEY --api-url URL`. `botable-mcp` runs the packaged MCP server.
+
+---
+
+## Status Bot
+
+Standalone Telegram bot for monitoring the staging server. Lives in `botable_status_bot/`.
+
+- **bot.py**: aiogram handlers -- `/status` (full report), `/health` (quick check), `/services` (Docker ps)
+- **collectors.py**: SSH into staging VPS, runs `docker ps`, `docker stats`, disk/memory checks
+- **formatters.py**: Formats collected data into Telegram-friendly HTML
+- **scheduler.py**: Periodic polling (configurable interval), sends alerts on failures
+- **Deployment**: Dockerfile, runs as a container on the staging VPS
+
+Env vars for status bot: `BOT_TOKEN`, `CHAT_ID`, `SSH_HOST`, `SSH_KEY_PATH`.
+
+---
+
+## Configuration (3-Layer Merge)
+
+Defined in `src/botable/config.py`:
+
+1. **Defaults** -- hardcoded in `config.py`
+2. **User config** -- `~/.config/botable/config.toml` (API key, preferred defaults)
+3. **Project config** -- `botable.toml` in project root (overrides per-project)
+
+Later layers override earlier ones. Auth token and API URL are stored in the user config; `BOTABLE_API_URL` overrides the saved URL. Default API URL is `https://api-staging.botable.dev` (staging until the CLI routes reach production; `DEFAULT_API_URL` in `src/botable/config.py`).
+
+---
+
+## Publishing
+
+- Build system: **hatchling**
+- Publish: `python -m build && twine upload dist/*`
+- Version: defined in `pyproject.toml` (`version = "0.2.0"`)
+- PyPI: https://pypi.org/project/botable-dev/ (the name `botable` belongs to an unrelated package)
+- Python: `>=3.10`
+
+---
+
+> **Last reviewed**: October 18, 2026

botable_dev-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HabLab LLP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

botable_dev-0.3.1/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.5
+Name: botable-dev
+Version: 0.3.1
+Summary: Botable CLI: build, deploy and run Telegram bots from your terminal, Claude Code or Codex
+Project-URL: Homepage, https://botable.dev
+Author-email: Botable Team <hello@botable.dev>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,aiogram,bot,chatbot,cli,generator,telegram
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=1.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli-w>=1.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Requires-Dist: typer>=0.15
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Requires-Dist: twine>=6.0; extra == 'dev'
+Requires-Dist: watchfiles>=1.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# ⚡ Botable CLI
+
+> **Generate Telegram bots with AI — from idea to running bot in 3 minutes.**
+
+[![PyPI](https://img.shields.io/pypi/v/botable-dev?color=blue)](https://pypi.org/project/botable-dev/)
+[![Python](https://img.shields.io/pypi/pyversions/botable-dev)](https://pypi.org/project/botable-dev/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## Quick Start
+
+```bash
+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
+
+```bash
+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:
+
+```bash
+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:
+
+```toml
+# In botable.toml (per-project)
+[branding]
+enabled = true
+text = "Built with Botable (botable.dev)"
+style = "comment"  # "comment" | "docstring" | "none"
+```
+
+To disable globally:
+
+```toml
+# 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](https://docs.aiogram.dev/) (MIT license) — async-native, production-ready.
+
+## Development
+
+```bash
+git clone https://github.com/Botable-dev/cli.git
+cd cli
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+---
+
+⚡ Built with [Botable](https://botable.dev)

botable_dev-0.3.1/README.md

@@ -0,0 +1,147 @@
+# ⚡ Botable CLI
+
+> **Generate Telegram bots with AI — from idea to running bot in 3 minutes.**
+
+[![PyPI](https://img.shields.io/pypi/v/botable-dev?color=blue)](https://pypi.org/project/botable-dev/)
+[![Python](https://img.shields.io/pypi/pyversions/botable-dev)](https://pypi.org/project/botable-dev/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+## Quick Start
+
+```bash
+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
+
+```bash
+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:
+
+```bash
+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:
+
+```toml
+# In botable.toml (per-project)
+[branding]
+enabled = true
+text = "Built with Botable (botable.dev)"
+style = "comment"  # "comment" | "docstring" | "none"
+```
+
+To disable globally:
+
+```toml
+# 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](https://docs.aiogram.dev/) (MIT license) — async-native, production-ready.
+
+## Development
+
+```bash
+git clone https://github.com/Botable-dev/cli.git
+cd cli
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.
+
+---
+
+⚡ Built with [Botable](https://botable.dev)

botable_dev-0.3.1/botable_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Botable MCP Server — exposes Botable CLI tools via the Model Context Protocol."""
+
+__version__ = "0.1.0"