b3iq CLI

The b3iq CLI manages your machines, models, runtimes, and SSH access from a terminal or a script: the same account and endpoints as the HTTP APIs, wrapped in commands built for humans and agents alike.

Install

bash
npm i -g @b3dotfun/b3iq-cli

Requires Node ≥ 20. Ships compiled, with zero runtime dependencies.

Sign in

b3iq logout forgets the saved token; b3iq logout --revoke also revokes it server-side. Every token the CLI has minted, whether from login or from Settings, is listed under Settings → CLI tokens, where you can revoke any of them individually.

Command reference

Output contract

• stdout is data, stderr is logs. Parse stdout and ignore (or surface) stderr. Progress lines, spinners, and hints never touch stdout.
• JSON is automatic when piped. If stdout isn't a TTY, every command emits JSON. --json forces it anywhere; --pretty forces the human-readable table even when piped (the two flags can't combine). --quiet (-q) prints only ids, one per line, regardless of JSON mode: built for for id in $(b3iq machines list --quiet) loops.
• Exit codes are stable. Branch on them, not on message text:

Machine selectors

Any <machine> argument accepts a node id, an id prefix, or a case-insensitive substring of the machine's name. An exact id or name match always wins, so a full id is never ambiguous; a substring that matches more than one machine errors (exit 1) and lists the candidates.

Set a default so you can drop the argument entirely:

bash
b3iq config default-machine <id>

Every command that resolves a machine falls back to the default when the <machine> argument (or --machine) is omitted.

SSH access

bash
b3iq ssh <machine> [-- cmd]

Opens a session without you ever writing an SSH config or a ProxyCommand. The CLI resolves the machine's SSH-lane hostname and connects through a cloudflared-brokered tunnel as the b3iq user. Install cloudflared locally first (brew install cloudflared, or check with b3iq doctor).

The SSH lane has to be turned on for the machine first. Enable it from the machine's page in the dashboard. If it's off, b3iq ssh fails with a message pointing you there.

Args after -- run non-interactively and forward straight to ssh:

bash
b3iq ssh my-box -- nvidia-smi

In --json mode or when stdout isn't a TTY, b3iq ssh prints the resolved ssh invocation instead of taking over the terminal. This is useful for an agent that wants to inspect or reuse the command rather than open an interactive shell.

Headless & agent use

The CLI is built to be driven by a script or an agent as easily as by a human. See the output contract above. A few recipes:

bash
export B3IQ_TOKEN=...                     # a personal access token; no login step neededb3iq status --json | jq .machines_onlineb3iq machines list --quiet                # node ids, one per linefor id in $(b3iq machines list --quiet); do  b3iq machines get "$id" --json | jq '{id:.node_id, up:.liveness}'doneb3iq models list --machine <id> --json    # what a machine can serveb3iq ssh <machine> -- nvidia-smi          # run one remote command, capture stdoutb3iq doctor --json                        # preflight: auth, API, cloudflared

No command changes state as a side effect of reading. ssh, login, logout, and config are the only verbs that mutate anything.

Config

Env vars always win over the saved config file (~/.b3iq/config.json, mode 0600), which in turn wins over the built-in defaults.

Related