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

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

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.