Output Modes

How the CLI formats output for agents, scripts, and humans.

The CLI is agent-first: the default output is structured JSON — no spinners, no color codes, no decorations. Just parseable data on stdout. Progress, warnings, and errors go to stderr so piping always works cleanly.

Humans can opt into a prettier experience with --human.

Default: JSON (Agent-Friendly)

Every command outputs clean JSON by default. The response follows the HeyGen API envelope shape — a top-level data field wraps the payload:

heygen avatar list

{
  "data": [
    {
      "id": "avt_angela_01",
      "name": "Angela",
      "gender": "female",
      "looks_count": 3,
      "preview_image_url": "https://files.heygen.com/avatar/avt_angela_01.jpg",
      "default_voice_id": "1bd001e7e50f421d891986aad5e3e5d2",
      "created_at": 1709856000
    }
  ],
  "has_more": true,
  "next_token": "eyJsYXN0X2lkIjoiYXZ0X21hcmN1c18wMiJ9"
}

--human: Pretty Output for Humans

Add --human when you’re working interactively. You get tables, colorized status values, and human-readable timestamps:

heygen video list --human

ID                                Title                     Status     Created
4621f8ba1a8f4811b32f669c37be53a2  HeyGen in 20 Seconds      completed  2026-03-28 15:48
75c58ba041394ddcb3737d7eff9d514b  Video Agent Weekly Recap  completed  2026-03-25 22:18

Showing 4 of 5 columns. Remove --human for full JSON output.

For get commands (single resource), --human renders a key-value layout:

heygen video get abc123 --human

Id:          abc123
Status:      completed
Title:       Demo

When --wait is used in human mode, the CLI shows a live spinner on stderr while polling:

heygen video-agent create --prompt "Product demo" --wait --human

· Processing... (42s)

On a non-TTY stderr (e.g. in CI with --human), the spinner falls back to plain-text status lines:

Polling: status=processing (elapsed 10s)
Polling: status=processing (elapsed 22s)

Errors

Errors always go to stderr as a structured JSON envelope, regardless of output mode:

{
  "error": {
    "code": "not_found",
    "message": "Video abc123 not found",
    "hint": "Check ID with: heygen video list",
    "request_id": "req_abc123"
  }
}

In --human mode, errors render as readable text instead:

Error: Video abc123 not found
Hint:  Check ID with: heygen video list

The request_id field is included when the error comes from the API (from the X-Request-ID response header). It is omitted for local errors such as bad flags or missing credentials.

Exit Codes

Code	Meaning
0	Success
1	General error (API error, network failure)
2	Usage error (invalid flags, missing arguments)
3	Authentication error (missing or invalid API key)
4	Timeout (resource created but polling timed out)

Exit code 4 is distinct from 1 so agents and scripts can tell “the resource was created but we don’t know the final status” apart from a hard failure. Stdout will contain the last known resource state when exit 4 occurs.

Configuring a Default Output Mode

Set a persistent default so you don’t need --human on every command:

heygen config set output human

Valid values are json (default) and human. The priority order is:

--human flag → HEYGEN_OUTPUT env var → config set output → default (json)

# Always human by default, but get JSON for this one invocation
heygen config set output human
heygen video get vid_xyz789 --output json

Stdout vs Stderr

The CLI strictly separates data from everything else:

• stdout — JSON payload only. This is what gets piped to jq, captured in shell variables, or consumed by agents.
• stderr — progress indicators, warnings, and error messages.

This means piping works cleanly with no extra flags:

# Extract all video IDs from your account
heygen video list | jq -r '.data[].id'

# Create a video and immediately open the URL in your browser
VIDEO_ID=$(heygen video-agent create --prompt "Demo video" | jq -r '.data.video_id')
heygen video get "$VIDEO_ID" --wait | jq -r '.data.video_url' | xargs open