# HeyGen CLI Documentation

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

```bash
curl -fsSL https://static.heygen.ai/cli/install.sh | bash
```

This installs the latest stable release into `~/.local/bin`. Verify the installation:

```bash
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](https://app.heygen.com/settings/api?nav=API):

```bash
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:

```bash
export HEYGEN_API_KEY=your-api-key
```

Verify your credentials:

```bash
heygen auth status
```

## 3. Create a Video

Send a prompt to the Video Agent and let it handle avatar, voice, and layout:

```bash
heygen video-agent create --prompt "A presenter explaining our product launch in 30 seconds"
```

Output:

```json
{
  "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:

```bash
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:

```bash
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:

```bash
heygen video get vid_xyz789
```

Output:

```json
{
  "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:

```bash
heygen video download vid_xyz789 --output-path ./launch-video.mp4
```

Output:

```json
{
  "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:

```bash
heygen video download vid_xyz789 --asset captioned --output-path ./launch-captioned.mp4
```