Skip to main content
The HeyGen CLI gives developers and AI agents command-line access to HeyGen’s video platform. It wraps the v3 API, outputs structured JSON by default, and works out of the box in scripts, CI pipelines, and agent workflows.

​
1. Install the CLI

Install script (recommended): 
curl -fsSL https://heygen.com/install.sh | sh
Homebrew: 
brew install heygen/tap/heygen
Verify the installation: 
heygen --version
# heygen/1.0.0 darwin-arm64
The CLI ships as a single binary with no runtime prerequisites. macOS (Apple Silicon and Intel) and Linux (x64 and arm64) are supported. Windows binaries are available but not actively tested — WSL is recommended.

​
2. Authenticate

Log in with your API key from Settings → API in the HeyGen dashboard: 
heygen auth login --key YOUR_API_KEY
Output
{
  "status": "ok",
  "message": "API key saved"
}
For CI/Docker environments, set the environment variable instead: 
export HEYGEN_API_KEY=your-api-key
The env var takes precedence over stored credentials.
Your credentials are stored locally at ~/.heygen/credentials and never sent anywhere except the HeyGen API.

​
3. Create a Video

Send a prompt to the Video Agent and let it handle the rest: 
heygen video-agent create "A presenter explaining our product launch in 30 seconds"
Output
{
  "session_id": "sess_abc123",
  "status": "generating",
  "video_id": "vid_xyz789",
  "created_at": 1711288320
}
The CLI returns immediately with structured JSON. Your video is generating in the background. You can also pin specific choices: 
heygen video-agent create "Product demo walkthrough" \
  --avatar-id avt_angela_01 \
  --voice-id 1bd001e7e50f421d891986aad5e3e5d2 \
  --orientation landscape \
  --duration 30

​
4. Check the Status

Poll for the result using the video ID returned from step 3: 
heygen video get vid_xyz789
Output
{
  "id": "vid_xyz789",
  "title": "Product launch explainer",
  "status": "completed",
  "video_url": "https://files.heygen.com/video/vid_xyz789.mp4",
  "thumbnail_url": "https://files.heygen.com/thumb/vid_xyz789.jpg",
  "duration": 32.5,
  "created_at": 1711288320,
  "completed_at": 1711288452
}
Status moves through pending → processing → completed or failed. If the video fails, the response includes an error envelope with code and message.
Tip: Add --wait to the create command to block until the video is ready instead of polling manually. The default timeout is 10 minutes — override with --timeout 30m.

​
5. Download the Video

Once complete, download to a local file: 
heygen video download vid_xyz789 -o ./launch-video.mp4
Output
{
  "id": "vid_xyz789",
  "path": "./launch-video.mp4",
  "size_bytes": 4404019
}