Metadata-Version: 2.4
Name: botu-cli
Version: 0.1.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: rich>=13.0
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 sites verify <site-id> --domain acme.com --check   # confirm it
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 embed API keys |
| `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 |

### About embed keys

The plaintext of an API key is shown **once** — at creation. `botu embed`
therefore can't retrieve the key of an existing site. Either pass
`--key pk_live_...`, or use `--new-key` to mint a fresh one and drop it
straight into the snippet.

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `BOTU_API_URL` | `https://botu.io` | Target deployment (set to `https://qa.botu.io` for QA) |
| `BOTU_JSON` | — | `1` forces JSON output globally |

Credentials are stored in `~/.paradigx/auth.json`, **shared** with other
Paradigx product CLIs (e.g. `tokenroute`) — they authenticate against the
same Logto, so logging in once is reused across them.

## Exit codes

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

---

© 2026 Paradigx. All Rights Reserved.
