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

Commands

Full reference for the bithuman subcommands — run, render, info, pull, list, engine, doctor, init, the auth commands (login/logout), and mcp — with flags and examples.

Subcommand overview

Every subcommand accepts --help for the full flag listing.

CommandWhat it does
bithuman loginSign in via the browser; mint + store a per-device key
bithuman logoutRevoke this device’s key and clear the local store
bithuman auth statusShow the signed-in account and credential source
bithuman initCredential wizard: save BITHUMAN_API_SECRET, pick a brain, pull a showcase avatar (e.g. modern-court-jester)
bithuman run [avatar]Live avatar. No argument fetches + renders the free Wise Pup avatar out of the box; pass an avatar file to run your own — recognizes the model family first
bithuman render <path.imx>Offline render: model + WAV → MP4 (Linux-only)
bithuman info <model-file>Print model metadata — engine + family for any recognized bitHuman 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 engine list | install | updateInspect, install, or update the per-platform local render engine (shipped in the CLI, auto-managed)
bithuman doctorHost + auth + cache sanity check
bithuman mcpRun the built-in MCP server for AI agents (stdio); bithuman mcp tools lists the tools. See driving from an AI agent.
bithuman --versionPrint libessence + ABI + CLI versions

Signing in

bithuman login is the first step after installing. It signs you in to your bitHuman account through the browser and stores the credential locally, so run, pull, doctor, and the rest authenticate without any export.

bithuman login
# → opens your browser; approve the request, then return to the terminal
# ✓ Logged in as you@example.com

What happens: the CLI opens your browser to sign in, you approve the request, and bitHuman mints a per-device API key scoped to your account — aliased cli@<hostname> so you can recognize it later. The key is saved to your OS keychain (macOS Keychain / Linux Secret Service) so it survives across sessions and never sits in a plaintext env file. If no keychain is available, the CLI falls back to ~/.bithuman/config (a dotenv file, mode 0600).

SSH / headless (no browser):

bithuman login --device
# → prints a short code and a URL; open the URL on any device, enter the code

--device switches to a code-entry flow: the CLI prints a short user code and a verification URL. Open that URL in a browser anywhere (your laptop, your phone), sign in, enter the code, and the CLI completes the login. Use this whenever the browser can’t reach the machine running the CLI — the default loopback flow needs a browser on the same host.

Check who you are:

bithuman auth status
# Signed in as you@example.com
# Key:    cli@my-macbook
# Source: OS keychain

auth status reports the signed-in account, the per-device key alias, and where the credential is being read from (env var, keychain, or ~/.bithuman/config).

Sign out:

bithuman logout

logout revokes this device’s key on the server and clears the local store. The key is gone immediately — any other machine’s key (and your dashboard keys) are untouched.

Tip — Each device gets its own key, so you can revoke one laptop without disrupting another. You can also revoke any device’s key from Developer → API Keys on the dashboard.

Credential resolution order

Every command looks for the credential in this order — first match wins:

  1. BITHUMAN_API_SECRET in the environment (explicit; CI / automation)
  2. OS keychain (what bithuman login writes)
  3. ~/.bithuman/config (the dotenv fallback, also written by bithuman init)

So a key you export always overrides a logged-in one — handy for testing a specific secret without logging out. See Configuration for the manual path in full.

bithuman init — credential wizard

bithuman init is an interactive setup wizard, not a project scaffolder. It walks you through first-time credentials and a starter avatar:

bithuman init

It prompts for your BITHUMAN_API_SECRET and writes it to ~/.bithuman/config (a dotenv file, mode 0600), lets you pick a conversation brain, and pulls a showcase avatar (e.g. modern-court-jester) so you have something to run immediately. ~/.bithuman/config is loaded at every CLI startup, so the secret persists across sessions without re-exporting it. See Configuration for the full set of variables it manages.

bithuman run — live avatar

The headline command. With no argument it is the zero-config quickstart: the CLI fetches the free Wise Pup avatar (a showcase expression-2 identity) and renders it live on your own hardware — no sign-in, no API key, no file to point at.

bithuman run
# → the Wise Pup avatar downloads once, then renders in real time

Local rendering runs on macOS (Apple Silicon, CoreML) and Linux x86_64 (LiteRT); see Local rendering by platform.

Pass an avatar file (or agent code) to run your own. From one invocation the CLI stands up an embedded livekit-server, a libessence runtime, the conversation brain (cloud OpenAI Realtime or the on-device stack per BITHUMAN_LOCAL), and a browser landing page:

bithuman run ~/.cache/bithuman/showcase/modern-court-jester.imx
# → open the printed http://127.0.0.1:8088/<CODE> URL, grant mic, talk

Precondition — the conversation brain needs the Python agent bundle. The native brew binary serves the avatar on its own, but the conversational brain runs as a Python agent that the binary launches. Install it before bithuman run can talk back:

  • Cloud brain (OpenAI Realtime): pip install bithuman-cli
  • On-device brain: pip install 'bithuman-cli[local]' (then BITHUMAN_LOCAL=1)

Without one of these the avatar renders but has no brain. See Configuration and Local mode.

Common flags:

FlagDefaultWhat
--host127.0.0.1Bind address. Pass a Tailnet / LAN IP to expose. 0.0.0.0 needs --allow-public-bind.
--port8088Launcher HTTP port.
--max-sessions(CPU count)Pool cap; new launches are rejected (not degraded) when full.
--embedded-livekiton with model argSpawn a self-contained livekit-server child. Off when omitting the model and using an external SFU.
--mock-runtimeoffRun with black frames instead of libessence — for protocol tests.

Which model files run locally?

bithuman run recognizes the model family before launching — it sniffs the file (the IMX container’s engine header, or the artifact’s format), so every bitHuman model file gets a correct, honest answer instead of a deep engine error:

FamilyFileWhat run does
essence-1<code>.imx (also legacy exports)Runs locally — launches exactly as always.
expression-2<code>.imx (also legacy .avatar zip)Runs locally on macOS (Apple Silicon) and Linux x86_64; Windows coming. The free Wise Pup avatar renders out of the box. Also serves live on bitHuman cloud. See Local rendering by platform.
essence-2<code>.lebundle.imxThe standard Essence 2 artifact. Recognized; exits with UNSUPPORTED_MODEL_FAMILY (code 69) and points you to the cloud surfaces. The bundle contains licensed weights — local playback is pending the runtime license wiring, so keep the file.
essence-2-max<code>.pklThe Essence 2 Max artifact (essence-2-quality is its pre-rename internal alias). Recognized; same honest handoff — this family renders on bitHuman’s GPU cloud and is not a local-playback artifact.
expression-1—No downloadable artifact exists (it renders server-side from the agent’s image), and the model is not supported on Mac locally — it’s a heavy GPU engine. Serve it through the cloud surfaces.

Recognition never breaks what already worked: a file the sniffer can’t positively identify goes to the engine exactly as before (the engine stays the final arbiter), and only a positive cloud-only match (Essence 2 or Expression 1) diverts to the cloud surfaces. Get the files themselves with bithuman pull <AGENT_CODE> or the download endpoint.

bithuman render — offline MP4

For batch jobs or pipelines with TTS upstream — no browser, no brain, just lipsync a WAV you already have:

bithuman render avatar.imx --audio speech.wav --output demo.mp4

Warning — broken in cli-v2.4.0 (verified 2026-07-28). On Linux x86_64, the current release fails at the muxing step and writes no output file:

encoding via libessence (h264+aac → mp4)…
error: record_mp4 failed: file corrupt: audio_decode: avformat_open_input failed

This is not an input problem — it reproduces identically with a WAV from /v1/tts, with the speech.wav that ships in this project’s own Examples/python/local-essence/, and with a plain 16 kHz mono PCM WAV written by Python’s stdlib wave. Since the command is Linux-only (see below), bithuman render has no working platform right now. To produce an mp4 today, use the Video API (POST /v1/video/generate), which renders server-side and returns a URL.

Flags:

FlagDefaultWhat
-a, --audio <PATH>(required)16 kHz mono PCM WAV input.
-o, --output <PATH>output.mp4Output MP4 path.
--quality <PRESET>MEDIUMEncoder preset: LOW, MEDIUM, HIGH.
--target-size <SIZE>1280A single number N (longest side binds to N, aspect preserved) or WxH (explicit canvas).
--limit <N>noneIntended to cap output frame count for testing, but currently a no-op — it is accepted and ignored; the full input is always rendered.

Warning bithuman render is currently Linux-only. On macOS the command prints a not implemented: be_video_encoder_* error and exits. Workarounds:

  1. Run inside a Linux Docker container — install the CLI with the universal installer (curl -fsSL https://raw.githubusercontent.com/bithuman-product/homebrew-bithuman/main/install.sh | sh; the PyPI wheel is macOS-only, so don’t pip install bithuman-cli on Linux) and render there, mounting your .imx and WAV in and the MP4 out.
  2. Use bithuman run instead — the live-avatar path does not need the offline encoder; it publishes frames into LiveKit via the webrtc-rs encoder, and you can record from the browser if you need a file.
  3. Render on a Linux host — a small Linux box or CI runner with the CLI installed via the universal installer renders any .imx + WAV pair to MP4 identically. (On Linux, install with the universal installer, not pip install bithuman-cli — the PyPI wheel is macOS-only.)

An AVFoundation-based native macOS encoder is on the roadmap.

bithuman info — inspect a model

Print model metadata. For an .imx that’s the model type, fixture name, frame size, sample rate, duration, and hash — plus the engine and family resolved from the unified IMX container header (also in --json as engine / family). Handy for verifying a model file before deploy:

bithuman info avatar.imx

As of CLI 2.4.1, info also prints the full container table of contents — every member in the .imx with its byte size (members in --json) — so you can see at a glance what an artifact carries (tested against CLI 2.4.2 on a showcase model):

  Members (9):
    manifest.json  (1030 bytes)
    audio/feature_centers.npz  (624727 bytes)
    audio_encoder.onnx  (2840632 bytes)
    …

(inspect is an alias — bithuman inspect avatar.imx prints the same report.)

info recognizes the non-.imx artifacts too: an expression-2 .avatar (CoreML zip), an essence-2-max (Essence 2 Max) pickle, and legacy essence-1 tar exports get a format/family report instead of a “not an IMX file” error; a legacy BIMX v1 container gets a precise unsupported-version message.

bithuman pull + list — your models and showcase avatars

Browse the showcase manifest and download one:

bithuman list
bithuman pull modern-court-jester
bithuman run ~/.cache/bithuman/showcase/modern-court-jester.imx

Pulled showcase avatars land in ~/.cache/bithuman/showcase/. See Configuration for the full cache layout.

Pull your own agent’s model by code

Pass an agent code (A + 9 characters, e.g. A17ZTB0222) instead of a showcase slug and pull downloads your agent’s generated model through the authenticated GET /v1/agent/{code}/model/download endpoint, then sniffs the file and prints its family and the next step:

bithuman login                      # once — pull-by-code needs your account
bithuman pull A17ZTB0222
# → ~/.cache/bithuman/agents/A17ZTB0222/A17ZTB0222.avatar
#   expression-2 — runs locally on macOS (Apple Silicon) / Linux x86_64, or live on bitHuman cloud

When the agent’s model is essence-1, the pulled .imx is immediately runnable:

bithuman pull A66GYD8664
bithuman run ~/.cache/bithuman/agents/A66GYD8664/A66GYD8664.imx

Files land in ~/.cache/bithuman/agents/<code>/. What each family’s file is — and which ones run locally — is in the launch matrix. Failure modes: not signed in → exit 77 (bithuman login first); the server refusing the download → exit 66 carrying the API’s error, including the poll-able MODEL_ARTIFACT_NOT_READY when a supported artifact simply hasn’t been published yet. Showcase-slug pulls are unchanged.

bithuman engine — local render engine

The engine that renders expression-2 avatars locally ships inside the CLI, so a fresh install runs its first avatar with no extra download. bithuman engine is the manual channel for that runtime — you rarely need it, but it lets you inspect what’s installed, install the engine for a different platform when you package a cross-platform build, or update it when a newer avatar needs a newer engine.

bithuman engine list                 # every known engine and whether it's installed
bithuman engine install              # fetch this platform's engine into the cache
bithuman engine install linux-x86_64 # fetch another platform's engine (cross-build)
bithuman engine update               # install the newest pinned engine (idempotent)

Each avatar is one self-contained .imx file; when the CLI fetches one it pulls only the slice your platform needs (about 26 MB on macOS, 63 MB on Linux). Which runtime renders on each platform is in Local rendering by platform.

bithuman doctor — install sanity check

When something does not work, run this first. It checks versions, host RAM, avatar auth, brain selection and availability, and cache sizes, and exits 0 only if both avatar auth and a brain path are configured:

bithuman doctor && bithuman run avatar.imx

See Install for the full breakdown of what doctor reports.