Features

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

Common Flags

These flags are supported across commands where applicable.

Flag	Description	Default
--human	Enable rich TUI output (tables, progress bars, colors)	Off (JSON)
--output json|human	Explicit output format	json
--wait	Block until async operation completes, subject to --timeout. Exits with code 1 if timeout is reached.	Off
--timeout <duration>	Max wait time (e.g., 10m, 1h)	10m
--all	Auto-paginate and return all results as a single array. Warns on stderr if count exceeds 1000.	Off
--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 (e.g., video delete)	Off (prompt)
--quiet	Suppress all output except errors	Off
-o, --out <path>	Output file path for downloads	stdout

---

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 create \
  --avatar-id avt_angela_01 \
  --voice-id 1bd001e7e50f421d891986aad5e3e5d2 \
  --script "Welcome to our Q4 earnings call." \
  --wait

Without --wait, you get the initial response:

{
  "video_id": "vid_qr8821",
  "status": "waiting"
}

With --wait, the CLI polls until completion and returns the full detail:

{
  "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 10 minutes. Override with --timeout:

heygen video create --script "Long video..." --wait --timeout 30m

If the timeout is reached, the CLI exits with code 1.

---

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"

Auto-pagination

Use --all to fetch every page automatically and return all results as a single array:

heygen avatar list --all

When --all is used, the output shape is a CLI-aggregated single array — not the raw API response. A warning is printed to stderr if the total exceeds 1000 items.

---

Stdin Support

Flags that accept long text (e.g., --script) support reading from stdin with -:

# Pipe a script file
cat script.txt | heygen video create \
  --avatar-id avt_angela_01 \
  --voice-id 1bd001e7e50f421d891986aad5e3e5d2 \
  --script -

# Here-doc
heygen video create --script - <<EOF
Welcome to our quarterly update.
This quarter we shipped three major features.
EOF

---

Destructive Operations and --force

Commands that delete resources (video delete, webhook delete, translate 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": "auth_expired",
    "message": "API key has expired",
    "hint": "Run heygen auth login --key <key>",
    "request_id": "req_abc123"
  }
}

• code — machine-readable error type
• message — human-readable description
• hint — suggested action to resolve
• request_id — included when the error comes from an API response (from the X-Request-ID header). Omitted for local errors (usage, network).

Exit Codes

Code	Meaning	When
0	Success	Operation completed
1	General error	API 4xx/5xx, network failure, timeout
2	Usage error	Bad flags, missing required args
3	Auth error	401/403, missing or invalid API key

Exit code 3 exists so agents and scripts can distinguish “stop and fix credentials” from “maybe retry.” All other failures collapse to 1 — the error JSON carries the detail.

Rate Limiting

429 responses are retried automatically with exponential backoff (respecting the Retry-After header). The error only surfaces if retries are exhausted.

---

Configuration

Persistent settings are managed with heygen config:

heygen config set output human      # default to pretty output
heygen config set auto_update false  # disable update checks (for CI)
heygen config set analytics false    # disable anonymous usage analytics

heygen config get output             # read a single value
heygen config list                   # show all config values

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

---

Self-Update

The CLI checks for new versions on every invocation (with a 24-hour cooldown) and notifies you if an update is available. To update:

heygen update

Disable auto-update checks for CI reproducibility:

heygen config set auto_update false

---

Analytics

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

On first run, the CLI prompts for opt-in consent. You can 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.