botu-cli 0.3.0

Agent-first CLI for botu — embeddable AI agent for any website

botu (Python CLI)

Agent-first CLI for botu — 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

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

Quickstart

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:

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.