Skip to main content
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 works cleanly. Humans can opt into a prettier experience with --human.

​
Default: JSON (Agent-Friendly)

Every command outputs clean JSON by default. API-backed commands return API-shaped JSON. CLI-native commands (config, update) return stable CLI-defined JSON: 
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
    },
    {
      "id": "avt_marcus_02",
      "name": "Marcus",
      "gender": "male",
      "looks_count": 2,
      "preview_image_url": "https://files.heygen.com/avatar/avt_marcus_02.jpg",
      "default_voice_id": "a2568ee2fa5c4c5db49a3a0ca8b746d1",
      "created_at": 1709942400
    }
  ],
  "has_more": true,
  "next_token": "eyJsYXN0X2lkIjoiYXZ0X21hcmN1c18wMiJ9"
}

​
--human: Pretty Output for Humans

Add --human when you’re working interactively. You get tables, progress bars, and colors: 
heygen avatar list --human

  ID                  Name              Gender    Looks
  avt_angela_01       Angela            female    3
  avt_marcus_02       Marcus            male      2
  avt_sofia_03        Sofia             female    4
  (12 more — use --limit to show all)

heygen video-agent create "A presenter explaining our product launch" --human

✓ Session  sess_abc123 created
✓ Video    vid_xyz789 queued
● Status   generating

heygen video download vid_xyz789 -o ./launch-video.mp4 --human

Downloading ████████████████████████████████ 100% (4.2 MB)
✓ Saved to ./launch-video.mp4

​
Configuring a Default Output Mode

If you prefer the human-friendly output as your personal default, set it once: 
heygen config set output human
Now every command defaults to the pretty TUI. You can still get JSON for a single command: 
# Config says human, but this one time give me JSON
heygen video get vid_xyz789 --output json
The priority order is: command flag → config file → default (json).

​
Stdout vs Stderr

The CLI separates data from everything else:
  • stdout — JSON output only. This is what gets piped to jq, captured in variables, or parsed by agents.
  • stderr — progress indicators, warnings, and error messages.
This means piping always works cleanly: 
# stdout has pure JSON, stderr progress doesn't interfere
heygen video list | jq '.data[].id'