Documentation Index
Fetch the complete documentation index at: https://docs.bithuman.ai/llms.txt
Use this file to discover all available pages before exploring further.
A Homebrew-installable command-line app that lets you talk to your
Mac in three modes: text, voice, or video. Useful for:
- Trying bitHuman in 30 seconds without writing any code.
- Testing your hardware before integrating the SDK.
- Demoing the technology to colleagues or stakeholders.
- Learning the SDK — the CLI is itself a working example. See
the annotated reference apps at
bithuman-product/bithuman-apps
for full Mac, iPad, and iPhone consumer code.
Install
brew tap bithuman-product/bithuman
brew install bithuman-cli
bitchat formula:
brew uninstall bitchat
brew untap bithuman-product/bitchat
Three modes
| Mode | Command | What you get | First-run download |
|---|
| Text | bithuman-cli text | Typed REPL in the terminal. Pipe-friendly. | ~2 GB |
| Voice (default) | bithuman-cli | Spoken conversation through your Mac’s mic + speaker. Voice cloning supported. | ~3 GB |
| Video | bithuman-cli video | Voice + a small floating animated face that lip-syncs at 25 FPS. 8 bundled agents. Drag-drop face swap. | ~4 GB |
# Quickest possible test
bithuman-cli text
> hello
Hi there. What's on your mind today?
# Voice mode (the default)
bithuman-cli
🎙 Listening. Talk any time.
# Video mode with the default agent
bithuman-cli video
# Video mode with a custom portrait
bithuman-cli video --image ~/Pictures/me.jpg
# Voice mode with a cloned voice (10–20 s of clean reference audio)
bithuman-cli --voice ~/myvoice.wav
# Custom system prompt
bithuman-cli --prompt "You are a calm tutor explaining ideas in plain words."
Flags
| Flag | What it does | Modes |
|---|
--locale <bcp47> | ASR locale + TTS language hint (default: en-US). | all |
--voice <preset|path> | Voice preset name (case-insensitive) or path to a 10–20 s mono audio file. Path = the voice is cloned. | voice + video |
--image <preset|path> | (video only) Bundled portrait preset (Alice, Marco, Captain, Nia, Riley) or path to a JPG/PNG/HEIC. Face is auto-cropped via Vision. | video |
--prompt <text|@path> | Override the LLM system prompt. Inline text or @/path/to/file.txt. | all |
-h, --help | Show full help. | all |
Bundled agents (video mode)
Each agent is a face + voice + system prompt bundled together.
The CLI uses Diego by default; right-click the floating window
to swap.
| Agent | Category | Voice |
|---|
| Diego (default) | Coach | am_michael |
| Nova | Entertainment | af_alloy |
| Einstein | Mentor | am_adam |
| Riya | Coach | af_heart |
| Lena | Coach | af_kore |
| Rae | Entertainment | am_echo |
| Dr. Maya | Business | bf_emma |
| Mason | Business | bm_george |
Voice cloning (voice mode)
Bring your own reference clip:
bithuman-cli --voice ~/myvoice.wav
- 10–20 seconds of clean mono speech, any sample rate.
- A transcript: either supply it as a sibling
.txt file
(~/myvoice.txt) or let the CLI auto-transcribe via Apple’s
on-device Speech framework (cached after first run).
Cloning is voice-mode only. Video mode uses preset voices
(Kokoro) for performance reasons — the GPU is busy driving the
avatar’s lip-sync.
What it looks like
In video mode you’ll see a small floating circular window in
the top-right of your screen. Right-click for the menu:
- Choose agent… — gallery of the 8 bundled agents
- Customize → Change image… — swap the portrait
- Customize → Change voice… — voice gallery (Kokoro presets)
- Customize → Change prompt… — system prompt editor with
6 starter templates
- Quit bitHuman
Drag any image file from Finder onto the window for an instant
face swap.
Press the spacebar in the terminal to interrupt the bot
mid-sentence.
Why ship a CLI?
The CLI exists for three reasons:
- The fastest possible “see what this is”. No SDK
integration, no Xcode, no signing. Just a
brew install.
- A working reference for the SDK. Every bitHumanKit feature
(voice cloning, agents, drag-drop face swap, video mode)
is exercised by the CLI. The source is the canonical
integration example.
- A diagnostic tool for hardware compatibility. If
bithuman-cli video runs cleanly on a developer’s machine,
their app will too.
Distribution
Distributed via the public Homebrew tap at
bithuman-product/homebrew-bithuman.
Releases are notarised by Apple and stapled before tap upload.
Manual DMG download (when you don’t want Homebrew): each release
on the tap repo also includes a notarised zip artifact.
Troubleshooting
The CLI inherits all the SDK’s behaviour, so the
SDK Troubleshooting page covers most issues.
The CLI-specific gotchas:
brew install 404 after the bitchat → bithuman rename:
brew untap bithuman-product/bitchat first, then re-tap.- First-launch hang for ~2 minutes downloading models.
Add
BITHUMAN_VERBOSE=1 to see progress.
- Audio device refusal on external USB / Bluetooth mics.
Test with the built-in mic first; some peripherals report
unusual channel layouts the SDK’s voice-processing IO
doesn’t accept.
Next
