CLI — macOS and Linux

Install one binary, sign in once, and bithuman run puts a talking avatar at http://127.0.0.1:8088/ on macOS Apple Silicon or Linux x86_64. Offline MP4 render in one more command.

This is the surface you use without writing code. One binary: type bithuman run and talk to an avatar. If you want to program against the models instead, that is the Python library — a different surface for a different purpose, installed a different way.

Install

curl -fsSL https://raw.githubusercontent.com/bithuman-product/homebrew-bithuman/main/install.sh | sh

bithuman render writes the MP4 through ffmpeg — brew install ffmpeg on macOS, sudo apt install -y ffmpeg on Linux. bithuman run spawns livekit-server from your PATH — brew install livekit on macOS, curl -sSL https://get.livekit.io | bash on Linux.

That one command is the install on both platforms. It puts the CLI and its runtime in ~/.local/bin (set BITHUMAN_INSTALL_DIR to put it elsewhere), checksum-verified against the release. install.bithuman.ai serves the same script, so curl -fsSL https://install.bithuman.ai | sh is the shorter spelling of the line above.

There is no pip install for the CLI. bithuman on PyPI is the Python library — it is the only bitHuman package on PyPI, and it installs no command. The CLI and its MCP server come from the installer above or from Homebrew, whose formula is named bithuman-cli. A bithuman-cli wheel existed on PyPI until 2026-09-15 and was removed. If you find a package on PyPI with a bitHuman-like name that is not bithuman, it is not ours.

On Apple Silicon only, Homebrew is an alternative: brew install bithuman-product/bithuman/bithuman-cli installs the same tarball. The formula declares arch: :arm64 and macos: :sonoma, so it is not an option on Linux or on an Intel Mac — on Linux the installer above is the only route. Use one or the other, not both. Either way bithuman --version tells you what you got:

$ bithuman --version
libessence  2.11.5 ABI 7         # the engine inside, and the ABI it speaks
bithuman    2.6.26               # the CLI itself
build       …                    # commit, target and build time
engine      …                    # the platform engine it loaded

The two numbers move independently and the installer always fetches the newest CLI, so read yours rather than this page’s — the shape is the contract, the digits are a snapshot (taken 2026-09-20 from the installer’s own download).

Published for macOS Apple Silicon and Linux x86_64 only; on an Intel Mac or a Linux ARM box the installer names the platform and stops without downloading anything (exact output).

Authentication and configuration

bithuman login opens a browser and stores a per-device key on this machine; bithuman login --device prints a code instead, for an SSH session. In a script or in CI, set BITHUMAN_API_SECRET — a key is free at your API keys. Which one wins when both are present, and every other variable the binary reads, is on the CLI reference.

A showcase pull is the exception: it never needed an account. run and render do, from 2.6.20.

Get a model

A showcase avatar downloads with no account — the catalogue bithuman list prints — and your own agents come by code; sign in once for run, render and for your own agents:

bithuman login                    # opens your browser; stores a per-device key on this machine
bithuman list                  # the showcase catalogue — slug, code, name, model
bithuman pull wise-pup            # prints ~/.cache/bithuman/showcase/wise-pup.imx

A showcase pull is anonymous — login is for render and for your own agents: bithuman pull <YOUR_AGENT_CODE> --model essence-2 prints ~/.cache/bithuman/agents/<YOUR_AGENT_CODE>/<YOUR_AGENT_CODE>.imx (--model picks a family when the agent has more than one).

A second pull of the same identity re-downloads it when the published file changed since it was cached (the cached file’s length is compared with the published one; when that cannot be asked, the cached file is kept) — for an agent code today, and for a showcase slug from cli-v2.6.26. --force re-downloads regardless; bithuman run <slug> uses the file already pulled, so pull again to pick up a change.

run takes the slug too. bithuman run wise-pup resolves the slug itself — the same resolver, the same cache and the same session as pulling first (measured on the published cli-v2.6.26 Linux x86_64 tarball, fresh $HOME: the embedded livekit-server and the brain come up and the session URL prints) — and the bare bithuman run is bithuman run wise-pup. A path works as well: bithuman run ~/.cache/bithuman/showcase/wise-pup.imx.

Minimal code

Two operations — there is no third:

bithuman run wise-pup                                                  # 1. live avatar in your browser
bithuman render "$(bithuman pull wise-pup)" -a speech.wav -o out.mp4   # 2. offline: audio in, MP4 out

render needs a mono WAV — curl -fsSLo speech.wav https://tmoobjxlwcwvxvjeppzq.supabase.co/storage/v1/object/public/web/showcase/demo_sample.wav is one (24 kHz, 15 s). bithuman open <file> prints what an avatar is before you render it.

Run

Sign in first. bithuman login opens a browser and stores a per-device key; bithuman login --device prints a code for an SSH session.

From 2.6.20, every render path needs a credential, on both platforms. With none, bithuman render and bithuman run each stop before the first frame — exit 77, in a second or two, having written nothing. render says “not signed in, or the credential is not valid — run bithuman login, or set BITHUMAN_API_SECRET”; run refuses on the same terms. Both name the same two remedies, and no environment variable renders for free.

That includes the Linux --offscreen render, which exits 77 METERING_REFUSED before the first frame with no credential and is metered with one (measured on the published Linux tarball, fresh $HOME). Every render is metered, and pricing is the authority; what each release changed is in the changelog.

Then open the printed http://127.0.0.1:8088/<CODE>. An Expression 2 avatar — what the showcase slugs are — is a live session with the brain: run spawns an embedded livekit-server (it must be on your PATH, see the prerequisites above), builds the conversation brain on first run (a one-time ~200 MB pip install, one to two minutes) and prints the session URL. bithuman run with no argument is bithuman run wise-pup and reaches the same session. run serves localhost only; --host takes a LAN or tailnet address to expose it. --host 0.0.0.0 needs --allow-public-bind as well — without it the CLI exits 2 and binds nothing, rather than putting the session on every interface. bithuman login also adds the managed conversation brain, and local mode runs the brain entirely on your own hardware instead — no LLM or TTS vendor. A self-hosted session on your own agent is metered — pricing is the authority.

Performance

Measured frame rates for every platform are on the performance page.

Troubleshooting

You see	It means	Do this
the installer names your platform and stops	no binary for an Intel Mac or Linux ARM	the web, the cloud API, or the Linux x86_64 binary in a container
`bithuman: command not found` after the install	`~/.local/bin` is not on your `PATH`	`export PATH="$HOME/.local/bin:$PATH"` — the installer prints the same line
`render` exits 69: `ffmpeg not found`	`ffmpeg` is not on your `PATH` — a script or CI shell often lacks Homebrew’s `/opt/homebrew/bin`	`brew install ffmpeg` (macOS) or `sudo apt install -y ffmpeg` (Linux); in a script, `export PATH="/opt/homebrew/bin:$PATH"` or set `BITHUMAN_FFMPEG`
`render` refuses with `NOT_SIGNED_IN`, no output file	no credential — `render` is billed	`bithuman login`, or `export BITHUMAN_API_SECRET=…` (credential order)
`run` refuses with `NOT_SIGNED_IN`, exit 77, nothing served	no credential — `run` is billed too, from 2.6.20. A credential the service rejects is a different answer: exit 1, `sign-in failed: auth required (BE_ERR_NO_AUTH)`	`bithuman login`, or `export BITHUMAN_API_SECRET=…`
`run --host 0.0.0.0` exits 2 with `PUBLIC_BIND_REFUSED` and nothing listening	binding every interface has to be deliberate	a LAN or tailnet address in `--host`, or add `--allow-public-bind` if you meant it
`pull <CODE>` refuses without a sign-in	your own agent code needs a credential; a showcase slug never does	`bithuman login`, then pull again
`pull <CODE>` fails with `404 NOT_FOUND`	not an agent on your account, and not a showcase slug	check the code under your agents; `bithuman list` lists the public ones
`pull <CODE>` fails with `409 MODEL_NOT_GENERATED`	the agent has no model of that family yet	add the model, or `--model` the family it was created with
`pull <CODE>` fails with `MODEL_ARTIFACT_NOT_READY`	trained, not yet published to the download store	run the same `pull` again in a minute
`SLUG_NOT_FOUND`	the slug is not in the catalogue	`bithuman list` and copy a slug from it
the first Essence 2 `render` on a machine pauses before the first frame	it fetches one shared audio encoder (~377 MB) into `~/.bithuman/engines/essence-2/`, once	wait; every later render skips it
`Error: No available formula` from `brew`	the tap is not known to Homebrew yet	`brew tap bithuman-product/bithuman`, then install again
`pip install bithuman` stops at `bithuman 2.11.6 has NO WHEEL for this platform.`	an Intel Mac, or macOS older than 14 — pip installed nothing	Apple Silicon, or the web / the cloud API
`bithuman doctor` reports not ready	no credential and no brain configured yet — the check working	`bithuman login`; a showcase `pull` never needed it

With --json, every failure prints one JSON object to stderr with a stable code; without it the same failure is prose, and the exit code is the contract — the reference lists them. Three codes share exit 77: NOT_SIGNED_IN (run, render), NOT_AUTHENTICATED (account commands) and METERING_REFUSED (run --offscreen).

What renders locally, and where

Family	macOS Apple Silicon and Linux x86_64
Expression 2 (`.avatar` or `.imx` — the same container)	`run` and `render`
Essence 2 (`.imx`)	`run` and `render`
Essence 1 (`.imx`)	`run` only — `render` refuses it; use the Python SDK or the Video API for a file
Expression 1	neither — GPU-only by design, served through the cloud API

Examples and source

api/cli — shell scripts that drive a live stream, an offline render and the REST API.
Examples — every runnable project, by language.
Homebrew tap — the installer and the released binaries.