bitHuman bitHuman docs
Status Get API key
Get startedAPISDKGuidesShowcase
ExamplesConceptsChangelogDownloadsCommunity Status
Get API key →
Docs / SDK /Command line

bitHuman CLI

One Rust binary that runs the whole avatar stack — live browser avatar, offline render, model introspection — from a single command.

One binary, the same engine as the libraries

bithuman is the command-line member of the SDK family — a single binary that runs the entire avatar stack without writing any code. It is built on libessence — the same engine that powers the Python and Swift libraries and the cloud REST API. They all read the same .imx avatar file and produce identical frames, so anything you prove out with the CLI ports straight into your application.

The CLI runs on macOS arm64 and Linux (x86_64 and aarch64).

Which models? The CLI recognizes every bitHuman model artifact — it sniffs the file and tells you what it is — and its local runtime (run / render) plays essence-1 .imx avatars. The second-generation artifacts (the standard Essence 2’s essence-2-light .lebundle.imx, Essence 2 Max’s essence-2-quality .pkl, expression-2 .avatar — the artifact families keep their internal names) are recognized by run / info / pull with honest guidance on where each runs — today they serve through the cloud surfaces (the REST API, the embed widget, and the dashboard), not the CLI’s local runtime. See the launch matrix.

What it does

The fastest path from a fresh install to a talking avatar is three steps — install → bithuman login → run:

bithuman login            # opens your browser, signs you in — done
export OPENAI_API_KEY=sk-...
bithuman run avatar.imx
# → open the printed http://127.0.0.1:8088/<CODE> URL, grant mic, talk

bithuman login opens your browser, you approve, and the CLI stores a per-device credential in your OS keychain so every other command authenticates automatically — no export BITHUMAN_API_SECRET. (That manual path still works for CI and automation; see Configuration.)

Under the hood bithuman run stands up an embedded livekit-server, a libessence avatar runtime, a conversation brain (cloud or on-device), and a browser landing page. That single command is the fastest way to get a talking, listening avatar in your browser. Beyond live chat, the CLI can render an MP4 offline, inspect an .imx file, browse and download showcase avatars, and run a full host sanity check.

The subcommands

CommandWhat it does
bithuman loginSign in via the browser; store a per-device key in the OS keychain
bithuman logoutRevoke this device’s key and clear the local store
bithuman auth statusShow who you’re signed in as and where the credential lives
bithuman initScaffold a new project / starter config
bithuman run <path.imx>Start the live avatar (mic in, browser viewer out)
bithuman render <path.imx>Offline lipsync: model + WAV → MP4 (Linux-only)
bithuman info <model-file>Print model metadata — engine + family for any recognized artifact
bithuman pull <slug | AGENT_CODE>Download a showcase avatar, or your own agent’s generated model by code
bithuman listBrowse the showcase avatar catalog
bithuman doctorHost + auth + cache sanity check

bithuman --version prints the libessence engine, ABI tag, and CLI versions. Every subcommand accepts --help. See Commands for the full flag reference.

Two ways to talk to the avatar

The conversation brain is pluggable. Both paths go through the same bithuman run command — one environment variable is the only difference.

Precondition. The native brew binary serves the avatar on its own, but the conversational brain runs as a Python agent the binary launches. Install that bundle first: pip install bithuman-cli for the cloud brain, or pip install 'bithuman-cli[local]' for the on-device brain. Without it the avatar renders but cannot talk back.

BrainRequiresUse when
Cloud (OpenAI Realtime)OPENAI_API_KEYFast warm-up, lowest first-token latency, hosted reliability
On-device (whisper.cpp + llama.cpp + Supertonic + Silero)pip install 'bithuman-cli[local]' + BITHUMAN_LOCAL=1Zero outbound network, private audio, kiosks / offline / mobile

Note The bithuman package on PyPI is the Python SDK / library (from bithuman import AsyncBithuman). The CLI ships separately as bithuman-cli — which bundles the Rust CLI binary, the conversation brain, and the [local] on-device brain extra (pip install 'bithuman-cli[local]'). Install the CLI via Homebrew or the universal installer on macOS (Apple Silicon) and Linux; pip install bithuman-cli is macOS Apple Silicon only. See Install.

Next steps