CLI Commands
The b3iq fleet CLI and the local host-agent CLI operators use day to day, plus the commands for building B3IQ from source.
This page covers the commands operators and developers actually run: the b3iq
fleet CLI, the local b3iq-host agent CLI, and the monorepo build/test
commands. Internal network-operations tooling — traffic warming and B3 payout
settlement — runs on a secured operator machine and is not part of the public
CLI.
Use ignored .env.local files, protected secret files, stdin, or temporary
curl config files for tokens and private keys. Do not paste API tokens,
customer tokens, gateway keys, or payout account keys into shell history.
b3iq CLI
b3iq is the fleet CLI — it manages your machines remotely from your own
laptop or CI, against your B3IQ account. It's a different tool from the local
b3iq-host agent CLI below: b3iq-host drives the daemon on the machine
itself, b3iq talks to the control plane and can reach every machine on your
account.
Sign in
Run b3iq login to sign in via a browser device-flow pairing, or set
B3IQ_TOKEN to a personal access token minted from Settings → CLI tokens
for CI and headless use.
Check your fleet
b3iq status prints a fleet overview; b3iq machines list and b3iq models list show what's online and what each machine can serve.
Operate
Install or remove a model, restart a runtime, tail gateway logs, or open an SSH session — see the command table below.
| Command | Purpose |
|---|---|
| b3iq login | Sign in via browser device flow (--token <t> for CI, or set B3IQ_TOKEN) |
| b3iq logout --revoke | Forget the saved token; --revoke also kills it server-side |
| b3iq whoami | Show the logged-in account |
| b3iq status | Fleet overview: machines online and servable models |
| b3iq machines list | List your machines (--quiet for node ids) |
| b3iq machines get <machine> | One machine's detail |
| b3iq models list [--machine <id>] | Servable models across the fleet, or one machine's full catalog |
| b3iq models install <model> --machine <id> | Install a model on a machine (--no-wait to not block) |
| b3iq models remove <model> --machine <id> | Uninstall a model from a machine (--no-wait to not block) |
| b3iq runtimes list [--machine <id>] | A machine's runtimes, with status and self-heal coverage |
| b3iq runtimes restart <runtime> --machine <id> | Restart a runtime (--no-wait to not block) |
| b3iq logs [--limit N] [--follow] | Recent gateway request logs; --follow streams new events |
| b3iq ssh <machine> [-- cmd] | Open an SSH session — transport is resolved for you, no ProxyCommand needed |
| b3iq config [default-machine <id>] | View or set local CLI config, including a default machine |
| b3iq doctor | Diagnose auth, API reachability, and cloudflared |
<machine> accepts a node ID, an ID prefix, or a substring of the machine
name.
stdout is data, stderr is logs. Output is JSON automatically when piped to a
non-TTY, --json forces it anywhere, and --quiet prints only ids. Exit
codes are stable: 0 ok · 1 usage · 2 api · 3 auth · 4 rate-limited.
Config lives at ~/.b3iq/config.json. Env overrides the file:
B3IQ_TOKEN (personal access token, skips the login step), B3IQ_API_URL, and
B3IQ_ORG_ID.
Host Agent CLI
On an installed node these are available as b3iq-host <command>. From a source
checkout, run go run ./cmd/b3iq-host <command> inside host-agent/.
| Command | Purpose |
|---|---|
| b3iq-host version | Print build metadata (--short for the version string only) |
| b3iq-host init | Create the local node identity and config |
| b3iq-host scan | Print host/CPU/GPU/NPU inventory as JSON (--recommend for a runtime suggestion) |
| b3iq-host resolve-pins | Resolve the pinned runtime build for this hardware |
| b3iq-host runtimes | Probe configured local runtimes |
| b3iq-host provision-engines | Install/start a model engine (--auto for the recommended one) |
| b3iq-host preflight | Check disk, ports, and permissions before install (--json) |
| b3iq-host enroll --url URL | Enroll the node with a B3IQ control plane |
| b3iq-host setup | Headless onboarding: claim, enroll, managed mode, and tunnel in one non-interactive run |
| b3iq-host status | Print node, auth, state, and API-key status (--pretty or --json) |
| b3iq-host doctor | Health check: service, runtimes, and local operator (--json) |
| b3iq-host serve | Start the local host agent on its configured listener |
| b3iq-host wizard url | Print the local setup wizard URL (add --with-token for a one-time bootstrap token) |
| b3iq-host open | Print and open the local dashboard URL in a browser |
| b3iq-host auth bootstrap | Create the first local owner from env or stdin password |
| b3iq-host auth login | Print a local operator session token |
| b3iq-host api-key create | Create a local `b3iq_local_` API key |
| b3iq-host api-key list | List local API keys |
| b3iq-host api-key revoke --id ID | Revoke a local API key |
| b3iq-host chat --api-key-stdin --prompt TEXT | Send a local OpenAI-compatible chat request |
| b3iq-host support-bundle | Generate a redacted diagnostics bundle |
| b3iq-host logs -f | Tail the service logs (journald on Linux; live file on macOS/Windows) |
| b3iq-host install-service --dry-run | Plan background service/autostart installation |
| b3iq-host uninstall-service | Remove the background service and autostart (counterpart to install-service) |
| b3iq-host startup-service --enable | Enable or disable service startup at boot/login (--enable / --disable) |
| b3iq-host start/stop/restart-service | Control the installed service (--system for system scope) |
| b3iq-host always-on | Enable or disable the B3IQ-managed no-sleep power policy (--enable / --disable) |
| b3iq-host update-service --dry-run | Plan a signature-verified binary update |
| b3iq-host reset | Re-enrollment reset: wipe identity, keep the binary and models |
| b3iq-host uninstall --purge | Remove the node; --purge also deletes the binary, models, and PATH entry |
Build From Source
Run package-scoped pnpm commands from the repo root.
bashpnpm installpnpm typecheckpnpm buildpnpm dev:explorer # Protocol Explorer dev serverpnpm dev:wizard # Setup wizard dev serverpnpm dev:desktop # Desktop companion dev server
Common Env
| Env | Purpose |
|---|---|
| B3IQ_HOME | Override the node config/state directory |
| B3IQ_LISTEN_ADDR | Local HTTP listener (defaults to 127.0.0.1:8831; LAN exposure is opt-in) |
| B3IQ_CONTROL_PLANE_URL | Control-plane base URL, usually `https://control-plane.b3iq.org` |
| B3IQ_GATEWAY_API_KEY | Hosted OpenAI-compatible gateway key (`b3iq_gateway_`) |
| B3IQ_CUSTOMER_ID / B3IQ_CUSTOMER_TOKEN | Customer identity headers for B3IQ-native jobs |