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

curl -fsSL https://static.heygen.ai/cli/install.sh | bash
This installs the latest stable release into ~/.local/bin. Verify the installation: 
heygen --version
The CLI ships as a single binary with no runtime prerequisites. macOS (Apple Silicon and Intel) and Linux (x64 and arm64) are supported. Windows support is coming soon — WSL is recommended in the meantime.

​
2. Authenticate

Log in with your API key from API dashboard: 
heygen auth login
Paste your API key when prompted. The key is stored locally at ~/.heygen/credentials. For CI/Docker/agent environments, set the environment variable instead — it takes precedence over stored credentials: 
export HEYGEN_API_KEY=your-api-key
Verify your credentials: 
heygen auth status

​
Free usage: log in with OAuth

To use your subscription’s free monthly quota instead of API credits, log in with OAuth: 
heygen auth login --oauth
This opens your browser to sign in at HeyGen.com. OAuth-authenticated calls to the Text to Speech and Digital Twin endpoints draw from your free usage quota instead of billing API credits.
heygen auth login --oauth uses subscription credits (your free monthly quota); an API key uses API credits (pay-as-you-go). Logging in one way replaces the other stored credential. Non-interactive shells (piped input, CI=true, or HEYGEN_NONINTERACTIVE=1) default to the API-key flow — pass --oauth explicitly in automation. Set BROWSER=none or HEYGEN_NO_BROWSER=1 to print the sign-in URL instead of opening a browser.

​
3. Create a Video

Send a prompt to the Video Agent and let it handle avatar, voice, and layout: 
heygen video-agent create --prompt "A presenter explaining our product launch in 30 seconds"
Output
{
  "data": {
    "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. For full control over every parameter, use video create with a JSON body: 
heygen video create -d '{
  "type": "avatar",
  "avatar_id": "avt_angela_01",
  "script": "Welcome to our Q4 earnings call.",
  "voice_id": "1bd001e7e50f421d891986aad5e3e5d2"
}'
Use --request-schema on any command to discover the expected JSON fields — no auth required: 
heygen video create --request-schema
heygen video-agent create --request-schema

​
4. Check Status

Poll for the result using the video_id returned from step 3: 
heygen video get vid_xyz789
Output
{
  "data": {
    "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 failure_code and failure_message fields.
Tip: Add --wait to the create command to block until the video is ready instead of polling manually. The default timeout is 20 minutes — override with --timeout 30m. On timeout, the CLI exits with code 4 and prints the last known resource state along with a hint to resume polling manually.

​
5. Download the Video

Once complete, download to a local file: 
heygen video download vid_xyz789 --output-path ./launch-video.mp4
Output
{
  "asset": "video",
  "message": "Downloaded video to ./launch-video.mp4",
  "path": "./launch-video.mp4"
}
If the video was created with captions enabled, you can download the captioned version: 
heygen video download vid_xyz789 --asset captioned --output-path ./launch-captioned.mp4