Make AI videos from the command line. Drive HeyGen with code, not clicks.
Full reference and examples: developers.heygen.com/cli.
- Coding agents — Claude Code, Codex, and others
- CI/CD pipelines — weekly recap videos, release-note vlogs
- Bulk operations — translate 100 videos in one shell loop
- Custom integrations — wrap it in your own tool
- JSON on stdout, structured errors on stderr, stable exit codes.
- Self-describing.
--request-schemaand--response-schemareturn JSON Schema without auth or API calls. - Non-interactive by default. Set
HEYGEN_API_KEYand nothing reads a TTY.
curl -fsSL https://static.heygen.ai/cli/install.sh | bashSingle static binary, no runtime required. Installs to ~/.local/bin.
Supported platforms: macOS, Linux, and Windows (via WSL).
You only need a HeyGen API key — see Authenticate below.
heygen update # install the latest versionChoose one of the three options below. The first two are agent- and CI-friendly; the third is for humans.
1. Environment variable — agents, CI; ephemeral, no file on disk:
export HEYGEN_API_KEY=your-key-here2. Pipe to auth login — agents; persists to ~/.heygen/credentials:
echo "$KEY" | heygen auth login3. Interactive auth login — humans; persists to ~/.heygen/credentials:
heygen auth loginVerify any of the above with heygen auth status. Get a key at app.heygen.com/settings/api.
1. Create a finished video from a prompt (returns JSON including video_id):
heygen video-agent create --prompt "30-second product demo" --wait2. Get its metadata and share link:
heygen video get <video-id>Returns JSON with video_url (raw mp4), video_page_url (shareable UI link), thumbnail_url, and duration. Pipe to jq to extract what you need:
heygen video get <video-id> | jq -r '.data.video_page_url'
# → https://app.heygen.com/videos/...3. Download the mp4:
heygen video download <video-id>Add --human to any command for a readable layout. Set HEYGEN_OUTPUT=human to make it the default.
Mirrors the HeyGen v3 API. Pattern: heygen <noun> <verb>.
| Group | What it does |
|---|---|
video-agent |
Create videos from text prompts using AI |
video |
Create, list, get, delete, download videos |
avatar |
List and manage avatars and looks |
voice |
List voices, design voices, generate speech |
video-translate |
Translate videos into other languages |
lipsync |
Dub or replace audio on existing videos |
webhook |
Manage webhook endpoints and events |
asset |
Upload files for use in video creation |
user |
Account info and billing |
Every command supports --help.
| Aspect | Behavior |
|---|---|
| stdout | Always JSON. Even video download — binary writes to disk; stdout emits {"asset", "message", "path"} so you can chain on .path. |
| stderr | Structured envelope on error: {"error": {"code", "message", "hint"}}. Stable code values for programmatic branching. |
| Exit codes | 0 ok · 1 API or network · 2 usage · 3 auth · 4 timeout under --wait (stdout contains partial resource for resume) |
| Request bodies | Flags for simple inputs; -d for nested JSON (inline, file path, or - for stdin). Flags override matching fields. |
| Async jobs | --wait blocks with exponential backoff; --timeout sets max (default 20m). 429s and 5xx retry automatically. |
Example error envelope:
{"error": {"code": "not_found", "message": "Video not found", "hint": "Check ID with: heygen video list"}}| File | Purpose |
|---|---|
~/.heygen/credentials |
API key |
~/.heygen/config.toml |
Output format and other non-secret settings |
HEYGEN_API_KEY and HEYGEN_OUTPUT env vars override the respective files.
heygen config list # show all settings with sourcesSee CONTRIBUTING.md.