> ## 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.

# Features

> Configure the HeyGen CLI with shared flags for output mode, model selection, agent style, and verbose debugging. Use these flags across any CLI command.

## Common Flags

These flags are supported across commands where applicable.

| Flag                         | Description                                                                                               | Default           |
| ---------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------- |
| `--human`                    | Enable rich TUI output (tables, colorized values, readable timestamps)                                    | Off (JSON)        |
| `--wait`                     | Block until async operation completes, subject to `--timeout`. Exits with code `4` if timeout is reached. | Off               |
| `--timeout <duration>`       | Max wait time when using `--wait` (e.g. `10m`, `1h`)                                                      | `20m`             |
| `--limit <n>`                | Maximum items per page (1–100)                                                                            | Endpoint-specific |
| `--token <cursor>`           | Pagination cursor from a previous response's `next_token`                                                 | None              |
| `--force`                    | Skip confirmation prompts for destructive operations                                                      | Off (prompt)      |
| `-d, --data <json\|path\|->` | JSON request body (inline, file path, or `-` for stdin)                                                   | None              |
| `--request-schema`           | Print the API request body JSON schema and exit (no auth required)                                        | Off               |
| `--response-schema`          | Print the API response JSON schema and exit (no auth required)                                            | Off               |

***

## Async Operations and `--wait`

Commands that create videos or translations return immediately by default with an ID and status. The operation continues in the background.

Add `--wait` to block until the operation completes:

```bash theme={null}
heygen video-agent create --prompt "Welcome to our Q4 earnings call." --wait
```

Without `--wait`, you get the initial response:

```json theme={null}
{
  "data": {
    "session_id": "sess_abc123",
    "status": "generating",
    "video_id": "vid_qr8821"
  }
}
```

With `--wait`, the CLI polls the status endpoint until completion and returns the full resource:

```json theme={null}
{
  "data": {
    "id": "vid_qr8821",
    "status": "completed",
    "video_url": "https://files.heygen.com/video/vid_qr8821.mp4",
    "duration": 12.4,
    "created_at": 1711288320,
    "completed_at": 1711288422
  }
}
```

The default timeout is 20 minutes. Override with `--timeout`:

```bash theme={null}
heygen video create -d '...' --wait --timeout 30m
```

If the timeout is reached, the CLI exits with code `4`. Stdout contains the last known resource state, and stderr contains a hint with the manual polling command:

```json theme={null}
{"error": {"code": "timeout", "message": "polling timed out after 20m0s", "hint": "heygen video get vid_qr8821"}}
```

If the operation reaches a terminal failure state, the CLI exits with code `1`. Stdout contains the failure response (which often includes error details) and stderr contains the error envelope.

`--wait` is supported on:

* `heygen video create`
* `heygen video-agent create`
* `heygen video-translate create`
* `heygen lipsync create`

***

## Complex Request Bodies (`-d` / `--data`)

Endpoints with nested inputs — discriminated unions, arrays of objects, nested configs — use `-d` for raw JSON instead of individual flags:

```bash theme={null}
# Inline JSON
heygen video create -d '{
  "type": "avatar",
  "avatar_id": "avt_angela_01",
  "script": "Hello world",
  "voice_id": "1bd001e7e50f421d891986aad5e3e5d2"
}'

# From a file
heygen video create -d request.json

# From stdin
cat request.json | heygen video create -d -
```

Flags and `-d` can be combined — **flags override matching fields in the JSON body**. This lets you keep a reusable JSON template and tweak individual fields per invocation:

```bash theme={null}
heygen video create -d base.json --wait
```

Use `--request-schema` to discover the expected JSON shape for any command — no auth required:

```bash theme={null}
heygen video create --request-schema
heygen lipsync create --request-schema
```

***

## Pagination

List commands return paginated results. Each response includes `has_more` and `next_token`:

```json theme={null}
{
  "data": [...],
  "has_more": true,
  "next_token": "eyJsYXN0X2lkIjoiYXZ0X21hcmN1c18wMiJ9"
}
```

### Manual pagination

Use `--token` to fetch the next page:

```bash theme={null}
heygen avatar list --limit 10
heygen avatar list --limit 10 --token "eyJsYXN0X2lkIjoiYXZ0X21hcmN1c18wMiJ9"
```

If an agent needs multiple pages, it should read `next_token` from the JSON response and pass it to the next call explicitly. The CLI does not auto-paginate — each page is a separate request.

***

## Stdin Support

Flags that accept long text support reading from stdin with `-`:

```bash theme={null}
# Pipe a script file into video create
cat script.json | heygen video create -d -

# Here-doc
heygen video create -d - <<EOF
{
  "type": "avatar",
  "avatar_id": "avt_angela_01",
  "script": "Welcome to our quarterly update.",
  "voice_id": "1bd001e7e50f421d891986aad5e3e5d2"
}
EOF
```

***

## Destructive Operations and `--force`

Commands that delete resources (`video delete`, `webhook endpoints delete`, `video-translate delete`, `lipsync delete`) prompt for confirmation interactively:

```text theme={null}
⚠ Delete video vid_xyz789? This cannot be undone. [y/N]
```

Use `--force` to skip the prompt — useful in scripts and CI:

```bash theme={null}
heygen video delete vid_xyz789 --force
```

***

## Error Handling

All errors use a consistent JSON envelope on stderr:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Video not found",
    "hint": "Check ID with: heygen video list",
    "request_id": "req_abc123"
  }
}
```

* `code` — machine-readable error type
* `message` — human-readable description
* `hint` — suggested action to resolve the error
* `request_id` — included when the error comes from the API (from the `X-Request-ID` header). Omitted for local errors (bad flags, missing credentials, network failures).

### Exit Codes

| Code | Meaning       | When                                                         |
| ---- | ------------- | ------------------------------------------------------------ |
| `0`  | Success       | Operation completed                                          |
| `1`  | General error | API 4xx/5xx, network failure, terminal job failure           |
| `2`  | Usage error   | Bad flags, missing required args                             |
| `3`  | Auth error    | 401/403, missing or invalid API key                          |
| `4`  | Timeout       | Resource was created but polling timed out before completion |

Exit code `4` is distinct from `1` so agents can tell "the job exists but we don't know the final state" apart from a hard failure. Stdout will contain the last known resource state when exit `4` occurs.

### Rate Limiting

`429` responses are retried automatically with exponential backoff, respecting the `Retry-After` header. The error only surfaces if retries are exhausted. The default retry count is 2; override with the `HEYGEN_MAX_RETRIES` environment variable.

***

## Configuration

Persistent settings are managed with `heygen config`:

```bash theme={null}
heygen config set output human      # default to pretty output
heygen config set analytics false   # disable anonymous usage analytics
```

```bash theme={null}
heygen config get output            # read a single value
heygen config list                  # show all config values and their sources
```

Config values are stored locally at `~/.heygen/config.toml`.

### Config keys

| Key         | Values          | Description                                 |
| ----------- | --------------- | ------------------------------------------- |
| `output`    | `json`, `human` | Default output format (default: `json`)     |
| `analytics` | `true`, `false` | Enable or disable anonymous usage analytics |

### Environment variable overrides

| Variable              | Description                                           |
| --------------------- | ----------------------------------------------------- |
| `HEYGEN_API_KEY`      | API key (takes precedence over stored credentials)    |
| `HEYGEN_OUTPUT`       | Output format: `json` or `human`                      |
| `HEYGEN_NO_ANALYTICS` | Set to any non-empty value to disable analytics       |
| `HEYGEN_MAX_RETRIES`  | Max retry count for transient failures (default: `2`) |
| `HEYGEN_API_BASE`     | Override the API base URL (internal/test use)         |

***

## Self-Update

The CLI can update itself:

```bash theme={null}
heygen update                        # install the latest version
heygen update --version v0.1.0       # install a specific version
```

The version flag requires the `v` prefix. Dev builds track dev prereleases; stable builds track stable releases only.

***

## Analytics

The CLI collects anonymous usage analytics to inform product decisions. This includes command usage, error rates, CLI version, and platform. No API keys, scripts, prompts, or personally identifiable information are ever tracked.

Disable analytics at any time:

```bash theme={null}
heygen config set analytics false
```

Or via environment variable:

```bash theme={null}
export HEYGEN_NO_ANALYTICS=1
```

Analytics calls are non-blocking and never slow down the CLI.