CLI — macOS and Linux

Install one binary and type `bithuman run` — a talking avatar at http://127.0.0.1:8088/ on macOS Apple Silicon or Linux x86_64, no account and no key for the first frame. 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.

That one command is the install on both platforms. It puts a single self-contained binary 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  3.1.8 ABI 7          # the engine inside, and the ABI it speaks
bithuman    2.6.20               # the CLI itself
build       …                    # commit, target and build time
engine      …                    # the platform engine it loaded

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 and run are the exception: those never needed an account.

Get a model

A showcase avatar downloads with no account — twenty to pick from — and your own agents come by code; sign in once for render and for your own agents:

bithuman login                    # opens your browser; stores a per-device key on this machine
bithuman avatars                  # 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). bithuman run with no argument fetches the free Wise Pup avatar (A23WJF0199, an Expression 2 identity) itself.

Minimal code

Two operations — there is no third:

bithuman run "$(bithuman pull 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 info <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.

Upgrade if you are on anything older: through 2.6.19 a Linux bithuman run with no credential rendered indefinitely. Every render is metered either way, and pricing is the authority.

Then open the printed http://127.0.0.1:8088/. For an Expression 2 avatar — which is what bithuman run fetches when you give it no argument, and what the showcase slugs are — that page is a local preview: the avatar renders its idle loop at its own frame rate, and the terminal counts frames and viewers beside it. It does not ask for a microphone, and no conversation brain is started on this path. 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 `METERING_REFUSED`, nothing served	no credential, or one the service rejected — `run` is billed too, from 2.6.20	`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 avatars` 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 avatars` 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
`No matching distribution found for bithuman`	an Intel Mac, or macOS older than 14	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` and `run` never needed it

Every failure prints one JSON object to stderr with a stable code — the reference lists them.

What renders locally, and where

Family	macOS Apple Silicon and Linux x86_64
Expression 2 (`<code>.avatar` or `.imx` — the same container)	`run` and `render`
Essence 2 (`<code>.imx`)	`run` and `render`
Essence 1 (`<code>.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.