> ## Documentation Index
> Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Output Modes

> Pick the right HeyGen CLI output mode for your workflow. Defaults to agent-friendly JSON; supports streaming, pretty-print, and machine-readable formats.

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:

```bash theme={null}
heygen avatar list
```

```json theme={null}
{
  "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:

```bash theme={null}
heygen video list --human
```

```text theme={null}
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:

```bash theme={null}
heygen video get abc123 --human
```

```text theme={null}
Id:          abc123
Status:      completed
Title:       Demo
```

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

```bash theme={null}
heygen video-agent create --prompt "Product demo" --wait --human
```

```text theme={null}
· Processing... (42s)
```

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

```text theme={null}
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:

```json theme={null}
{
  "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:

```text theme={null}
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:

```bash theme={null}
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`)**

```bash theme={null}
# 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:

```bash theme={null}
# 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
```