Features

Common flags, error handling, pagination, async polling, and CLI behaviors.

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:

heygen video-agent create --prompt "Welcome to our Q4 earnings call." --wait

Without --wait, you get the initial response:

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

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

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:

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

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

heygen video create -d base.json --wait

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

heygen video create --request-schema
heygen lipsync create --request-schema

---

Pagination

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

{
  "data": [...],
  "has_more": true,
  "next_token": "eyJsYXN0X2lkIjoiYXZ0X21hcmN1c18wMiJ9"
}

Manual pagination

Use --token to fetch the next page:

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

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

⚠ Delete video vid_xyz789? This cannot be undone. [y/N]

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

heygen video delete vid_xyz789 --force

---

Error Handling

All errors use a consistent JSON envelope on stderr:

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

heygen config set output human      # default to pretty output
heygen config set analytics false   # disable anonymous usage analytics

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:

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:

heygen config set analytics false

Or via environment variable:

export HEYGEN_NO_ANALYTICS=1

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