CLI reference

Covers the CLI at the version on Downloads & versions. The binary describes itself too: bithuman <command> --help, and bithuman __schema prints the full command, flag and exit-code tree as JSON. The quickstart is on CLI.

Commands

A command outside this list exits 2 with unrecognized subcommand. Everywhere, <avatar> is an agent code (A24EKJ8433), a sample avatar’s name (wise-pup), or a file (wise-pup.imx); run, render and open download a code or name on first use. --json, -h and -V (root only) work on every command.

Sign in

bithuman login                 # browser sign-in; stores a per-device API secret
bithuman login --device        # over SSH: prints a code to enter elsewhere
printf %s "$BITHUMAN_API_SECRET" | bithuman login --with-token   # CI: checks the secret, then stores it
bithuman logout                # revokes the secret login stored on this device

The secret is stored in ~/.bithuman/config (mode 0600) and named cli@<hostname> under API Secrets, so each device can be revoked alone. --with-token exits 77 (TOKEN_REJECTED) for a secret the service refuses and 69 (TOKEN_UNVERIFIED) when the service cannot be reached; neither stores anything.

Credential resolution order

1. BITHUMAN_API_SECRET in the environment
2. BITHUMAN_API_KEY in the environment (a deprecated alias; read until CLI 3.0, no earlier than 2026-12-26)
3. A .env file in the working directory: its BITHUMAN_API_SECRET line, else its BITHUMAN_API_KEY line (the deprecated alias). No other line of the file is read. Deprecated: the CLI prints a notice when it uses this file, and CLI 2.9 (no earlier than 2026-12-26) stops reading it; export BITHUMAN_API_SECRET or run bithuman login once.
4. ~/.bithuman/config, written by bithuman login

bithuman account --json reports which of these supplied the secret.

bithuman logout revokes only the secret in ~/.bithuman/config, then deletes it. A secret from the environment or a .env file is never revoked; logout names where it comes from instead.

bithuman run

run starts everything a session needs: a local livekit-server (it must be on PATH) and the conversation brain. A sample name or a file renders on this machine, billed at the self-hosted rate: Expression 2 (.avatar or .imx), Essence 2 and Essence 1 (.imx). An Essence 2 or Expression 2 agent code opens a session in the bitHuman cloud, billed at the cloud rate (pricing). Expression 1 is cloud-only.

The conversation brain: signed in, run uses the managed brain and installs it into ~/.cache/bithuman/brain-venv on first use (about 380 MB on disk). OPENAI_API_KEY selects OpenAI Realtime instead, and BITHUMAN_LOCAL=1 runs it on your hardware (local conversation brain).

bithuman render

render needs ffmpeg on PATH (or BITHUMAN_FFMPEG). A refused render writes no file.

bithuman pull

bithuman pull wise-pup                          # a sample avatar: no account → ~/.cache/bithuman/showcase/
bithuman pull "$AGENT_CODE"                     # your agent: needs sign-in → ~/.cache/bithuman/agents/<code>/
bithuman pull "$AGENT_CODE" --model essence-2   # when the agent has more than one model

pull prints only the cached path on stdout, so MODEL=$(bithuman pull wise-pup) captures it. A second pull downloads again when the published file changed; --force always does. An agent with several models returns the one it was created with unless you pass --model; --json lists the others in other_models. A slug not in bithuman list exits 66 (SLUG_NOT_FOUND). --model essence-1 | essence-2 | expression-2 picks which of the agent’s models to download.

bithuman open

Succeeds, or refuses with one of four kinds: InvalidAvatar, NotSupported, NotAuthorised, Failed. On success it prints the engine, the model and every member with its size. The engine value is a legacy identifier (the engine value), not a model value.

bithuman engine

The Expression 2 engine ships with the CLI. bithuman engine install fetches it again (idempotent); bithuman engine install linux fetches the other platform’s for a cross-build. The argument is mac or linux.

bithuman pack

Offline packs (Business and Enterprise) let a machine render with no network. Buy the pack online, then run this on the machine that will render:

bithuman pack redeem            # the account's unredeemed pack
bithuman pack redeem ent_...    # a named purchase
bithuman pack redeem ./PACK.bhl # a saved pack, with no network
bithuman pack status            # render-seconds left, one line per model

redeem binds the pack to this machine and installs it. The signed pack is kept at ~/.bithuman/packs/<pack_id>.bhl (mode 0600) first, so a failed install is retried by passing that file. Afterwards bithuman render of an avatar the pack covers needs no network and no API secret until the pack is spent. From CLI 2.8.4 a pack covers Essence 2 and Expression 2 as well as Essence 1.

bithuman pull <CODE> also fetches the engine files the avatar’s model needs, so pull each avatar and redeem once while online; after that rendering needs no network.

A spent pack, or one that is not for this machine, stops the render with exit 77 and says which; it never falls back to billing your account. A refusal names what to do (the plan, the platform, a pack already installed) and nothing is spent.

Where the CLI’s offline support has not opened yet, it says to use python -m bithuman pack redeem on the same machine. Plans and rates: offline licensing.

bithuman doctor

Checks versions, host, memory, credential, brain and cache sizes. Exits 0 only when a credential, a brain, the audio encoder and ffmpeg are all available. The agent worker row is information only: the first bithuman run sets the worker up, so a fresh install is not reported as not ready because of it.

Environment variables

Cache

bithuman doctor prints each size. Deleting ~/.cache/bithuman is safe.

Platforms

Binaries: aarch64-apple-darwin, x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-pc-windows-msvc. On any other platform the installer names the platform, says what is supported, and exits 1 without downloading. There is no Intel Mac binary; use a Linux container or the cloud API.

JSON output

With --json, a command prints exactly one JSON object on stdout and nothing else. Success objects carry "schema_version": 1. A failure prints one object to stderr, with a hint when there is a next step:

{"error": {"code": "USAGE", "kind": "Failed", "command": "renders", "message": "unrecognized subcommand 'renders'", "hint": "run `bithuman --help`"}}

Colour appears only on an interactive terminal.

Shapes

bithuman version --json:

{"abi":7,"cli":"2.8.9","libessence":"2.11.20","build":{"target":"x86_64-unknown-linux-gnu","profile":"release"},"engine":{"platform":"linux","runtime":"litert","version":"1.0.2"},"schema_version":1}

bithuman account --json (exit 77 with no credential; --limit <N>, default 10, sets how many recent charges to show):

{"logged_in": true, "source": "env BITHUMAN_API_SECRET", "email": "you@example.com", "plan": "creator", "credit_balance": 1000, "account_status": "active", "out_of_credits": false, "usage": {"data": [], "pagination": {"total": 0}}}

bithuman list --json:

{"schema_version": 1, "version": 2, "models": [{"slug": "wise-pup", "agent_code": "A23WJF0199", "name": "Wise Pup", "model": "expression-2", "size": 198632867}]}

bithuman pull <slug or code> --json:

{"schema_version": 1, "code": "A23WJF0199", "path": "/home/you/.cache/bithuman/showcase/wise-pup.imx", "cached": false, "family": "expression-2", "model": "expression-2", "other_models": [], "runnable_locally": true}

bithuman render … --json also carries render_seconds and render_fps, how long the engine took and how fast it produced frames (fps is the file’s playback rate). seconds is the clip length (frames / fps); wall_seconds is the wall time of the whole command (CLI 2.8.3 and earlier reported that wall time as seconds):

{"schema_version": 1, "output": "out.mp4", "bytes": 1234567, "seconds": 15.0, "wall_seconds": 21.4, "width": 416, "height": 720, "frames": 300, "fps": 20, "render_seconds": 6.2, "render_fps": 48.4}

bithuman login --json (both routes; the code box goes to stderr):

{"schema_version": 1, "logged_in": true, "email": "you@example.com", "alias": "cli@your-host", "stored": "~/.bithuman/config"}

alias is null with --with-token.

bithuman run … --json prints one event when the session is live:

{"schema_version": 1, "event": "session_started", "url": "http://127.0.0.1:8088/WISEPUP", "code": "WISEPUP", "host": "127.0.0.1", "port": 8088, "cost_per_min": 10, "credit_balance": 99}

bithuman doctor --json exits 0 when "ready": true. The values above are examples; the shapes are stable, and schema_version changes when they are not.

Exit codes

Introspection

bithuman __schema    # command, flag and exit-code tree as JSON
bithuman __agents    # this contract, offline
bithuman token       # the resolved secret on stdout (exit 77 if none)

MCP server

{"mcpServers": {"bithuman": {"command": "bithuman", "args": ["mcp"]}}}

bithuman mcp speaks the Model Context Protocol over stdio. bithuman mcp tools --json lists the tools: local ones (version, doctor, inspect_model, list_showcase, pull, render, pack_redeem) and ones that call the bitHuman API. Tools that create agents, speech or gestures spend credits. The full list is on MCP server.

Recipes

# First render on a new machine: check the credential first, then render.
set -e
bithuman account --json >/dev/null          # exit 77: run `bithuman login`
curl -fsSLo speech.wav https://docs.bithuman.ai/samples/speech.wav
bithuman render wise-pup speech.wav -o out.mp4 --json | jq -r .output

# Is this install ready to serve? (exit 0 = yes)
bithuman doctor --json | jq -e .ready >/dev/null