AI bots that work for you — right from your terminal.

botworker.dev · npm

A polished terminal chat client for your BotWorker bots. Messages render as a real chat window — not a wall of log output — with full right-to-left support, so Hebrew conversations read exactly as they should.

• 🎨 Designed for the terminal. Rounded chat bubbles, a gradient wordmark, and the BotWorker colour palette.
• 🌍 RTL that actually works. The CLI runs the Unicode Bidirectional Algorithm itself (via bidi-js) and emits text in visual order, so Hebrew renders identically in every terminal — including the many that have no bidi support at all.
• ⚡ Streaming replies with a live progress indicator.
• 🔐 Server-resolved permissions. What a key can do is decided by the server on every call, never by local config.

Install

npm install -g botworker

Or run it without installing:

npx botworker

Quick start

botworker login     # 1. approve in the browser
botworker bots      # 2. see your bots
botworker use <ID>  # 3. pick one
botworker           # 4. start chatting

Signing in

botworker login asks how you want to sign in. The default is a one-time code mailed to you — no password stored anywhere, and nothing to open in a browser.

| Command | Flow | | --- | --- | | botworker login | Browser approval (recommended) | | botworker login --email [email protected] | A 6-digit code sent to your mailbox | | botworker login --email [email protected] --password | Password, entered at a hidden prompt (never as an argument) | | botworker login --CS <code> -BU <bw_user_…> | The pairing printed on a bot's settings page — the page unlocks the moment it succeeds | | botworker login --api-key bw_live_… | An existing key — best for CI |

Commands

| Command | Description | | --- | --- | | botworker | Open the interactive chat window | | botworker chat "message" | Send a single message and exit | | botworker bots | List the bots available to your key | | botworker use <BOT_ID> | Set the active bot | | botworker login | Sign in (see Signing in) | | botworker balance | Show your credit balance | | botworker whoami | Show your account, role and key count | | botworker keys | List your active API keys (prefix only) | | botworker logout | Remove the stored key | | botworker help | Show the help screen |

Options

| Flag | Description | | --- | --- | | --api-key <KEY> | Authenticate (with or without the login verb) | | --bot <ID> | Override the active bot for a single message | | --json | Machine-readable output (great for scripts) | | --verbose | Include the model that answered |

In-chat commands

Inside the interactive window:

| Command | Description | | --- | --- | | /bots | List and switch bots | | /balance | Check your credit balance | | /new | Start a fresh thread (clears context) | | /clear | Clear the window | | /help | Show available commands | | /exit | Leave the chat |

Scripting

Piped or redirected output is automatically plain — no colours, no framing — so the CLI composes cleanly with other tools:

botworker chat "Summarise today's orders" --json | jq -r .reply
botworker chat "What are your opening hours?" > answer.txt

Exit codes: 0 success · 1 error · 2 out of credits · 3 rate limited.

Billing

Usage is pay-per-use, billed by actual usage (input and output together). When your balance runs out the API returns 402 and the CLI tells you how to top up.

Configuration

| Variable | Description | | --- | --- | | BOTWORKER_API_BASE | Point the CLI at a custom API endpoint | | BOTWORKER_CONFIG_DIR | Use a different config directory (handy for multiple accounts or CI) | | BOTWORKER_BIDI | Set to off to emit logical order instead of visual (only needed if your terminal does its own bidi and double-reverses) | | NO_COLOR | Disable colours and chat framing | | FORCE_COLOR | Force colours on (e.g. in CI) |

Settings are stored at ~/.botworker/config.json with 600 permissions.

Requirements

Node.js 18 or newer. For the best rendering use a terminal with truecolor and good Unicode support — Windows Terminal, iTerm2, or the VS Code terminal.

License

MIT