Skip to content

CLI

Manage inboxes, send and read mail, stream events, and wait for verification codes from a terminal or CI with the botinbox CLI.

01

Install on macOS with Homebrew#

The botinbox CLI is a single binary with no dependencies. On macOS (Apple silicon or Intel), install and update it with Homebrew. Shell completions for bash, zsh, and fish are installed too.

Shell
brew install botinbox-dev/tap/botinbox
brew upgrade botinbox        # later, to update

02

Install on macOS or Linux with the script#

The installer detects your OS and CPU (x86_64 or arm64), downloads the matching release from botinbox.dev, verifies its SHA-256 checksum, and installs botinbox to /usr/local/bin, or ~/.local/bin if that isn't writable. Set BOTINBOX_INSTALL_DIR to choose the directory or BOTINBOX_VERSION to pin a version. Run it again to update.

Shell
curl -fsSL https://botinbox.dev/install.sh | sh

# pin a version and a directory
curl -fsSL https://botinbox.dev/install.sh | BOTINBOX_VERSION=0.2.0 BOTINBOX_INSTALL_DIR="$HOME/bin" sh

03

Install on Windows#

In PowerShell, the installer downloads the zip for your CPU (x64 or ARM64), verifies its checksum, extracts botinbox.exe to %LOCALAPPDATA%\botinbox\bin, and adds that folder to your user PATH. Open a new terminal afterwards.

Shell
# PowerShell
irm https://botinbox.dev/install.ps1 | iex

04

Direct downloads#

Prefer to install by hand? The download page at https://botinbox.dev/app/cli links the .tar.gz (macOS, Linux) and .zip (Windows) archives for every platform, plus a SHA256SUMS file. Extract the archive and put botinbox on your PATH. In CI, the curl installer is the simplest option.

Shell
curl -fsSL -o botinbox.tar.gz https://botinbox.dev/download/cli/linux-amd64
curl -fsSL https://botinbox.dev/download/cli/checksums    # compare with: shasum -a 256 botinbox.tar.gz
tar -xzf botinbox.tar.gz botinbox && sudo mv botinbox /usr/local/bin/
botinbox version

05

Log in#

login validates the key with GET /v0/me and stores it with 0600 permissions in the OS config directory. Use --profile for several keys. The BOTINBOX_API_KEY and BOTINBOX_URL environment variables override stored values, which suits CI.

Shell
botinbox login                 # hidden prompt
echo "$BOTINBOX_API_KEY" | botinbox login --profile ci
botinbox whoami

06

Everyday commands#

Any inbox argument accepts an inbox ID or an email address. Every command supports --json for raw API output. Errors print the API error code, such as insufficient_scope or plan_required, with a hint.

Shell
botinbox inboxes create --username scout --display-name "Scout Agent"
botinbox send --from scout@example.com --to human@example.com --subject "Hello" --text "Sent by my agent"
botinbox messages ls scout@example.com --unread
botinbox messages get scout@example.com MESSAGE_ID
botinbox domains add agents.example.com   # prints the DNS records table
botinbox keys create --scope inbox --inbox scout@example.com --name ci
botinbox conversations handoff scout@example.com THREAD_ID --reason "Customer asked for a manager" --priority high
botinbox conversations insights --from 2026-09-01

07

Wait for a verification code in CI#

wait blocks until a new message matches the filters, then prints it. It exits 1 on timeout. --code prints only the first 4 to 8 digit code. --extract-code accepts any regex and prints capture group 1 if the regex has one. --since also accepts mail that arrived shortly before wait started.

Shell
CODE=$(botinbox wait --inbox signup-bot@example.com \
  --from noreply@yourapp.com --subject-contains verify \
  --since 2m --timeout 90s --code)

08

Live events and MCP#

tail streams /v0/events over SSE, prints one line per event, and reconnects with backoff. mcp prints setup snippets for Claude Code, Claude Desktop, and Cursor that point at the remote MCP server with the stored key. The key is redacted unless you pass --show-key.

Shell
botinbox tail --inbox scout@example.com
botinbox mcp --client claude-code --show-key