bitHuman bitHuman docs
Status Get API key
API PlatformCLIApps SDKShowcase
ExamplesChangelogDownloadsCommunity Status
Get API key →
Docs / CLI

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 SDKs

bithuman is a single command-line binary that runs the entire avatar stack without writing any code. It is built on libessence — the same Rust engine that powers the Python, Swift, and Kotlin SDKs 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).

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 <path.imx>Print .imx metadata
bithuman pull <slug>Download a showcase avatar
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