Metadata-Version: 2.4
Name: botu-cli
Version: 0.2.0
Summary: Agent-first CLI for botu — embeddable AI agent for any website
Project-URL: Homepage, https://botu.io
Project-URL: Repository, https://github.com/jiangjin11/botu-web
Author: Paradigx Pte Ltd
License: MIT
Keywords: agent,ai,botu,cli,embed,widget
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.28
Requires-Dist: paradigx-cli-core<0.2,>=0.1
Requires-Dist: typer<1.0,>=0.15
Provides-Extra: dev
Requires-Dist: pytest-mock>=3.14; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Description-Content-Type: text/markdown

# botu (Python CLI)

Agent-first CLI for [botu](https://botu.io) — the embeddable AI agent for any website.

Register a site, get an embed key, verify your domain, and inject the
`<script>` snippet — all from the command line, no web console needed.

## Install

```bash
pip install botu-cli
# or, run once without installing:
uvx botu --help
pipx run botu --help
```

## Quickstart

```bash
botu login                                          # OAuth device-flow, opens browser
botu sites create --name acme --domain acme.com     # create a site + first embed key
botu embed --site <site-id> --new-key --write index.html   # inject the <script>
botu sites verify <site-id> --domain acme.com       # start domain verification
botu test --site <site-id>                          # check the embed key works
```

All commands accept `--json` (or env `BOTU_JSON=1`) for machine-parseable
output that's friendly to agents and CI.

## Commands

| Command | Purpose |
|---|---|
| `botu login` / `logout` / `whoami` | OAuth device-flow session |
| `botu sites create\|list\|get\|delete` | Manage sites |
| `botu sites verify <id> --domain <d> [--check]` | Domain ownership (DNS TXT) |
| `botu keys create\|list\|revoke --site <id>` | Manage site embed API keys |
| `botu tokens create\|list\|revoke` | Account access tokens (PATs) for CI |
| `botu embed --site <id>` | Print / write the `<script>` embed snippet |
| `botu usage [--site <id>]` | Per-site quota and usage |
| `botu test --site <id>` | Verify an embed key via the loader auth exchange |

## Non-interactive use (CI / headless agents)

`botu login` needs a browser. For CI or headless agents, create an account
**access token** once and pass it via the `BOTU_TOKEN` env var — no login,
no browser:

```bash
botu tokens create --name ci --json     # → {"token": "bpat_...", ...}  shown ONCE
export BOTU_TOKEN=bpat_...
botu sites list                         # uses BOTU_TOKEN, no ~/.paradigx needed
```

Interactive sessions don't need this — the device-flow JWT is cached and
**auto-refreshed**, so `botu login` is a one-time step per machine.

### About embed keys vs account tokens

- `pk_live_*` / `pk_test_*` — **site embed keys**, go in the `<script>` tag.
- `bpat_*` — **account access tokens**, authenticate the CLI itself.

Both plaintexts are shown **once**, at creation. `botu embed` can't retrieve
an existing site's key — pass `--key` or use `--new-key` to mint a fresh one.

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `BOTU_API_URL` | `https://botu.io` | Target deployment (`https://qa.botu.io` for QA) |
| `BOTU_TOKEN` | — | Account access token — skips login (CI / agents) |
| `BOTU_JSON` | — | `1` forces JSON output globally |

Credentials are stored in `~/.paradigx/auth.json`, **shared** with other
Paradigx product CLIs (e.g. `tokenroute`) — log in once, reuse everywhere.

## Exit codes

`0` ok · `1` user error (4xx) · `2` network error · `3` server error (5xx)

---

© 2026 Paradigx. All Rights Reserved.
