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