> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Generate AI avatar videos from your terminal with the HeyGen CLI. Authenticate once, then script video creation, translation, and lipsync into any local.

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 theme={null}
curl -fsSL https://static.heygen.ai/cli/install.sh | bash
```

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

Verify the installation:

```bash theme={null}
heygen --version
```

<Info>
  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.
</Info>

## 2. Authenticate

Log in with your API key from [API dashboard](https://app.heygen.com/settings/api?nav=API):

```bash theme={null}
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 theme={null}
export HEYGEN_API_KEY=your-api-key
```

Verify your credentials:

```bash theme={null}
heygen auth status
```

## 3. Create a Video

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

```bash theme={null}
heygen video-agent create --prompt "A presenter explaining our product launch in 30 seconds"
```

```json Output theme={null}
{
  "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 theme={null}
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 theme={null}
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 theme={null}
heygen video get vid_xyz789
```

```json Output theme={null}
{
  "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.

<Info>
  **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.
</Info>

## 5. Download the Video

Once complete, download to a local file:

```bash theme={null}
heygen video download vid_xyz789 --output-path ./launch-video.mp4
```

```json Output theme={null}
{
  "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 theme={null}
heygen video download vid_xyz789 --asset captioned --output-path ./launch-captioned.mp4
```