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 — 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 — 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