# CLI

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

> Render an MP4 or run a live avatar from the terminal, on macOS (Apple silicon) and Linux (x86_64, arm64), with no code. On Linux it needs no GPU.

One binary, no code: `bithuman render` turns an audio file into a talking-avatar MP4, and `bithuman run` opens a live conversation with an avatar in your browser. It renders 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 66 MB) once |

*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)

## Before you start

| 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 | `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 (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 install bithuman-product/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
```

The installer puts the CLI in `~/.local/bin` (set `BITHUMAN_INSTALL_DIR` to change it) and verifies its checksum. If it asks you to, add `export PATH="$HOME/.local/bin:$PATH"` to your shell profile. On macOS, `curl -fsSL https://install.bithuman.ai | sh` installs the same release (then `brew install ffmpeg livekit` yourself). `bithuman --version` prints the CLI and engine versions.

Check the install:

```text
$ bithuman --version
libessence 2.11.16 ABI 7
bithuman    2.8.3
```

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)). Credits pay for session time, talking or idle, by the exact second ([pricing](https://docs.bithuman.ai/pricing)). Listing, downloading and opening avatars need no account.

## First frame

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 350 MB on disk, in one to two minutes.

## Complete example

From a fresh machine to a talking-avatar MP4 in four commands.

### Requirements

| You need | Notes |
|---|---|
| macOS (Apple silicon) or Linux (x86_64, arm64) | |
| An [API secret](https://docs.bithuman.ai/start/api-secret) | or `bithuman login` |
| `ffmpeg` | `brew install ffmpeg` or `sudo apt install -y ffmpeg` |

### Run it

```bash
curl -fsSL https://install.bithuman.ai | sh
export BITHUMAN_API_SECRET="<your API secret>"
curl -fsSLo speech.wav https://docs.bithuman.ai/samples/speech.wav
bithuman render wise-pup speech.wav
```

### Expected output

`wise-pup.mp4`: 416×720, as long as the audio (15 seconds for the sample). To talk to the avatar instead, run `bithuman run wise-pup` and open the printed URL (this also needs `livekit-server`; see [CLI](https://docs.bithuman.ai/platforms/cli#before-you-start)).

### 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; generate speech with [Text to speech](https://docs.bithuman.ai/api/text-to-speech).
- **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).

## 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. 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 |

The whole setup, and the same conversation in your own Python code: [Talk to an avatar on your machine](https://docs.bithuman.ai/build/voice-agent).

## 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 66 MB) to `~/.bithuman/engines/essence-2/` once.
- Intel Macs and Windows have no binary. Use WSL2 on Windows, or the [web embed](https://docs.bithuman.ai/platforms/web) or [cloud API](https://docs.bithuman.ai/api).

## Performance

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

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

## Troubleshooting

| 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 | `bithuman login` again, or create a new API secret |
| `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 names your platform and stops | no binary for this platform | see Platform notes |

## 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).