# CLI

URL: https://docs.bithuman.ai/platforms/cli

> Render an MP4 or run a live avatar from the terminal, with no code.

One binary, no code: `bithuman run` opens a live conversation with an avatar in your browser.

## Before you start

`bithuman render` turns an audio file into a talking-avatar MP4. Both render on your own machine. To program against the models instead, use [Python](https://docs.bithuman.ai/platforms/python).

> **Note:** On Linux, both models run live on the CPU alone, no GPU. See [CPU only (no GPU)](https://docs.bithuman.ai/deploy/cpu).

| Detail | Expression 2 | Essence 2 |
|---|---|---|
| **Renders** | [any character from one portrait](https://docs.bithuman.ai/models/expression-2) | [a photoreal person from one portrait](https://docs.bithuman.ai/models/essence-2) |
| **`render` and `run`** | both | both |
| **Download per avatar** | about 190 MB | 140–160 MB, plus a shared audio encoder (about 440 MB on Linux) once |

| You need | For | Check |
|---|---|---|
| macOS 14+ on Apple silicon, or Linux on x86_64 or arm64 | the binary | `uname -sm` |
| A bitHuman sign-in or API secret, on the Creator plan or higher (usage bills per second; [pricing](https://docs.bithuman.ai/pricing)) | `run` and `render` (browsing and downloading need none) | `bithuman account` exits 0 |
| `ffmpeg` on `PATH` | `render`, and `run` with an Essence 2 avatar | `ffmpeg -version` |
| `livekit-server` 1.13 or newer for `bithuman run` (the Linux download includes it) | `run` | `livekit-server --version`; update with `brew upgrade livekit` |
| Python 3.11 or newer with `venv` (`python3-venv` on Debian/Ubuntu) | `run` (its voice agent) | `python3 --version` |

## Install

```bash
# macOS (Apple silicon): also installs ffmpeg, livekit-server and Python
brew tap bithuman/bithuman https://gitlab.com/bithuman/sdk/homebrew-bithuman && brew install bithuman/bithuman/bithuman-cli
```

```bash
# Linux, x86_64 or arm64 (Debian/Ubuntu); the download includes livekit-server
sudo apt install -y ffmpeg python3-venv
curl -fsSL https://install.bithuman.ai | sh
```

```powershell
# Windows 10/11 x86_64 (PowerShell): cloud sessions and MCP
irm https://install.bithuman.ai/windows | iex
```

The Linux installer downloads about 190 MB and puts the CLI, its render engines and `livekit-server` (about 350 MB) in `~/.local/bin` (set `BITHUMAN_INSTALL_DIR` to change it). It verifies the checksum. If it asks you to, add `export PATH="$HOME/.local/bin:$PATH"` to your shell profile. On macOS `curl` works too (then `brew install ffmpeg livekit`). `bithuman --version` prints the CLI and engine versions.

Check the install:

```text
$ bithuman --version
libessence 2.11.20 ABI 7
bithuman    2.8.9
build       … x86_64-unknown-linux-gnu/release …
engine      linux 1.0.2 …
```

The CLI is not on PyPI. `pip install bithuman` installs the Python library, which has no command.

## Authenticate

```bash
bithuman login            # opens a browser and stores a credential for this device
bithuman login --device   # over SSH: prints a code to enter in any browser
bithuman account          # exit 0 when signed in
```

Sign in first, because every render path needs a credential: without one, `run` and `render` stop before the first frame with exit 77 and write nothing. In scripts and CI, set `BITHUMAN_API_SECRET` instead of signing in ([Your API secret](https://docs.bithuman.ai/start/api-secret)). Listing, downloading and opening avatars need no account.

## Run your first avatar

Render the sample speech through the `wise-pup` sample avatar:

```bash
bithuman login
curl -fsSLo speech.wav https://docs.bithuman.ai/samples/speech.wav
bithuman render wise-pup speech.wav -o out.mp4
# → out.mp4: 416×720, 300 frames, 15.0 s
```

Then talk to it live:

```bash
bithuman run wise-pup
# → open the printed http://127.0.0.1:8088/<CODE> and allow the microphone
```

`render` accepts any audio format `ffmpeg` reads. `bithuman run` needs two more things from [Before you start](#before-you-start): `livekit-server` and Python. It starts a local `livekit-server` and the voice agent; the first run installs the agent, about 380 MB on disk, in one to two minutes.

`wise-pup` and `A23WJF0199` are the same avatar, named two ways, and the name decides where it renders: a name (`wise-pup`) or a file renders on this machine, at the lower self-hosted rate; an agent code (`A23WJF0199`) renders in the bitHuman cloud, at the cloud rate ([pricing](https://docs.bithuman.ai/pricing)).

<div class="fig-end">

*Capture: The pip-the-red-panda-barista avatar speaking a line, rendered by bithuman render on a Linux PC with no GPU. Captured on a Linux PC, Intel Core i7-13700F (Ubuntu 24.04) · CLI 2.8.2 (bithuman render) · pip-the-red-panda-barista (Expression 2) · 2026-09-27. Rendered on the CPU alone: the PC's graphics card was hidden from the process.* (https://docs.bithuman.ai/examples/cli-linux/clip.mp4)

### Make it your own

- **Your own avatar:** create one with the [Agents API](https://docs.bithuman.ai/api/agents) (or on bitHuman), then `bithuman pull <AGENT_CODE>` and render it the same way.
- **Your own words:** any audio file `ffmpeg` reads works as the second argument: a recording, or a WAV or MP3 from any text-to-speech tool you use.
- **A photoreal person:** `bithuman render sofia-ramirez speech.wav` renders Essence 2 (this avatar is 1080×1920 portrait).
- **Scripts and CI:** add `--json` and branch on exit codes ([reference](https://docs.bithuman.ai/platforms/cli/reference#json-output)).
- **A conversation instead of a clip:** `bithuman run wise-pup` — [Talk to an avatar on your machine](https://docs.bithuman.ai/build/voice-agent).

## Performance

| Configuration | Hardware | Essence 2 | Expression 2 |
|---|---|---|---|
| Linux · CLI · CPU only (no GPU) | Intel Core i7-13700F (x86_64) | 2.0× real time | 2.2× real time |
| macOS · CLI | Apple M4 | 4.2× real time | 8.4× real time |

× real time: seconds of video rendered per second; 1.0× or more holds a live conversation ([method](https://docs.bithuman.ai/performance#desktop)).

## Continue

The rest of this platform, inlined so one fetch covers it: [Serve and script the CLI](https://docs.bithuman.ai/platforms/cli/voice.md) · [CLI troubleshooting](https://docs.bithuman.ai/platforms/cli/troubleshooting.md).

---

# Serve and script the CLI

URL: https://docs.bithuman.ai/platforms/cli/voice

> Serve live sessions, set the voice and script the CLI.

## Integrate into your app

| Job | Command |
|---|---|
| List the sample avatars | `bithuman list` (the same list as `https://api.bithuman.ai/v1/models/showcase`) |
| Download one | `bithuman pull <slug>` prints the cached path; `--force` downloads again |
| Download your own agent | `bithuman pull <AGENT_CODE> --model essence-2` (needs sign-in) |
| Inspect an avatar | `bithuman open <avatar>` |
| Render | `bithuman render <avatar> in.wav -o out.mp4` (a code or name is downloaded on first use) |
| Serve a live session | `bithuman run <avatar>`; `--host <LAN address>` to expose it (`0.0.0.0` also needs `BITHUMAN_ALLOW_PUBLIC_BIND=1`) |
| Talk with your own OpenAI key | `export OPENAI_API_KEY=…` before `bithuman run` ([voice settings](#voice-settings)) |
| Run the brain on your own hardware | [local conversation brain](https://docs.bithuman.ai/platforms/cli/local-brain) |
| Drive it from an AI agent | `bithuman mcp` ([MCP server](https://docs.bithuman.ai/build/mcp)) |
| Script it | add `--json`: every failure prints one JSON object with a stable code, and the exit code is the contract ([reference](https://docs.bithuman.ai/platforms/cli/reference#exit-codes)) |

### Voice settings

`bithuman run` starts a voice agent on OpenAI Realtime ([the whole setup, and the same conversation in Python](https://docs.bithuman.ai/build/voice-agent)). Both settings are read from the environment:

| Variable | Default | What it does |
|---|---|---|
| `OPENAI_API_KEY` | — | Your OpenAI key. Without it, the voice runs on your bitHuman account at the managed voice-chat rate, 10 credits per minute ([pricing](https://docs.bithuman.ai/pricing)). |
| `BITHUMAN_INSTRUCTIONS` | a short assistant prompt | The agent's system prompt |

## Platform notes

- Essence 1 avatars work with `run` only; for a file use [Python](https://docs.bithuman.ai/platforms/python) or the [video API](https://docs.bithuman.ai/api/video). Expression 1 runs on the [cloud API](https://docs.bithuman.ai/api).
- The first Essence 2 render on a machine downloads a shared audio encoder (about 440 MB on Linux) to `~/.bithuman/engines/essence-2/` once.
- Intel Macs have no binary. On Windows (not code-signed; [Downloads](https://docs.bithuman.ai/downloads)) the CLI renders in the cloud; to render on the PC, use [Python on Windows](https://docs.bithuman.ai/platforms/windows).

## Reference

- [CLI reference](https://docs.bithuman.ai/platforms/cli/reference): every command, flag, exit code and environment variable.
- [Local conversation brain](https://docs.bithuman.ai/platforms/cli/local-brain): run the conversation fully on your hardware.
- [CLI example scripts](https://github.com/bithuman-product/bithuman-examples/tree/main/api/cli): live stream, offline render, REST.
- [Changelog](https://docs.bithuman.ai/changelog) and [Downloads & versions](https://docs.bithuman.ai/downloads).

---

# CLI troubleshooting

URL: https://docs.bithuman.ai/platforms/cli/troubleshooting

> Fix CLI install, sign-in and render errors by symptom.

| Symptom | Cause | Fix |
|---|---|---|
| `bithuman: command not found` | `~/.local/bin` is not on `PATH` | `export PATH="$HOME/.local/bin:$PATH"` |
| `not signed in`, exit 77, nothing written | no credential | `bithuman login`, or set `BITHUMAN_API_SECRET` |
| `your credential is invalid or expired` or `the API secret was rejected`, exit 77 | the secret was revoked or mistyped; from 2026-10-12, a Free account | `bithuman login` again, or create a new API secret; on Free, [choose a plan](https://www.bithuman.ai/pricing?from=docs) |
| `bithuman login` prints `token exchange failed` or times out, exit 1 | the browser or device approval did not complete | run `bithuman login` (or `--device`) again |
| `render` exits 69: `ffmpeg not found` | `ffmpeg` is not on `PATH` (common in scripts) | install it, or set `BITHUMAN_FFMPEG` to its path |
| `run` with an Essence 2 avatar: no avatar in the page, and the terminal shows `essence-2: ffmpeg not found` | `ffmpeg` is not on `PATH` | `sudo apt install -y ffmpeg`, or set `BITHUMAN_FFMPEG` |
| `run` says the `livekit-server` binary was not found | `livekit-server` is not installed | `brew install livekit` (macOS), or rerun the installer (Linux) |
| `run` exits 69: `livekit-server 1.8.0 at …/livekit-server is too old for `bithuman run` (it needs 1.13 or newer)` | an old `livekit-server` found on `PATH` | `brew upgrade livekit` (macOS), or reinstall with `curl -fsSL https://install.bithuman.ai \| sh` (Linux) |
| `SLUG_NOT_FOUND`, exit 66 | the slug is not in the sample list | `bithuman list` and copy a slug |
| `pull <CODE>` fails with `404 NOT_FOUND` | not your agent and not a sample avatar | check the code under [your agents](https://docs.bithuman.ai/api/agents) |
| `pull <CODE>` fails with `409 MODEL_NOT_GENERATED` | the agent has no model of that kind | [add the model](https://docs.bithuman.ai/api/agents#add-a-model-to-an-existing-agent), or pass the `--model` it has |
| `PUBLIC_BIND_REFUSED`, exit 2 | `--host 0.0.0.0` without consent | use a LAN address, or set `BITHUMAN_ALLOW_PUBLIC_BIND=1` |
| the installer says `The tarball for … may not be published` | GitHub is rate-limiting your network (HTTP 429) | wait five minutes and run it again |
| `bithuman doctor` exits 1 on a fresh install: `Agent worker ✗ not found` | the first `bithuman run` sets up the worker | run `bithuman run` once |
| many `Removing initializer` warnings and short bracketed diagnostic lines during an Essence 2 render | runtime diagnostics | expected |
| the installer names your platform and stops | no binary for this platform | see Platform notes |