Skip to main content

​
Common Flags

These flags are supported across commands where applicable.
FlagDescriptionDefault
--humanEnable rich TUI output (tables, progress bars, colors)Off (JSON)
--output json|humanExplicit output formatjson
--waitBlock 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
--allAuto-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_tokenNone
--forceSkip confirmation prompts for destructive operations (e.g., video delete)Off (prompt)
--quietSuppress all output except errorsOff
-o, --out <path>Output file path for downloadsstdout

​
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

CodeMeaningWhen
0SuccessOperation completed
1General errorAPI 4xx/5xx, network failure, timeout
2Usage errorBad flags, missing required args
3Auth error401/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.