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 plugin or 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 machines qualify <machine> | Re-run the machine's hardware qualification (--no-wait to not block) |
| b3iq machines guests <machine> | A KVM host's guests and cards (--quiet for guest ids) |
| b3iq plugins list [--machine <id>] | Plugins a machine can install, or the ones a machine has |
| b3iq plugins install <plugin> --machine <id> | Install a plugin on a machine (--no-wait to not block) |
| b3iq plugins remove <plugin> --machine <id> | Remove a plugin with everything it installed (--no-wait to not block) |
| 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 commands list --machine <id> [--limit N] | A machine's recent commands, newest first |
| b3iq commands get <command-id> --machine <id> | One command's status, progress and result |
| 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. Prints the ssh invocation when piped |
| 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/.
The inference plugin's own commands (runtimes, chat, provision-engines,
swarm, model-release) ship in its binary, /usr/local/lib/b3iq/plugins/b3iq-inference,
which is not on PATH. For example, with the plugin installed:
/usr/local/lib/b3iq/plugins/b3iq-inference chat --api-key-stdin --prompt TEXT.
| 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 |
| b3iq-host resolve-pins | Print the pinned cloudflared connector build as B3IQ_* env lines |
| b3iq-host preflight | Check disk, ports, and permissions before install (--json) |
| b3iq-host enroll --url URL | Enroll the node with a B3IQ control plane |
| sudo b3iq-host plugin install inference | Install the inference plugin, which adds the local inference API. It installs no engine or model: add those from the dashboard afterwards |
| sudo b3iq-host plugin list | List installed plugins with their version and state (plugin status NAME for one) |
| sudo b3iq-host plugin uninstall inference | Remove the inference plugin with its engines, models and the packages it added |
| 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: the local service, each installed plugin's state, and any second node identity (--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 support-bundle | Generate a redacted diagnostics bundle |
| b3iq-host logs -f | Tail the service logs (journald) |
| 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 # Frontend site and customer dashboard dev server (retained script name)pnpm dev:wizard # Setup wizard 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 |