> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trytalkvalue.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Output format

> JSON for pipes, table for humans, CSV for spreadsheets. Auto-detected based on TTY with explicit overrides.

Every TalkValue CLI command emits its result in one of three formats: `json`, `table`, or `csv`. The CLI picks the right one automatically based on where the output is going, and you can override it on any command.

## Auto-detection

| Where output goes  | Default format |
| ------------------ | -------------- |
| A terminal (TTY)   | `table`        |
| A pipe or redirect | `json`         |

The CLI inspects `stdout` at startup. Running interactively gets a human-friendly table. Piping to another tool or redirecting to a file gets parseable JSON. That means `talkvalue path person list | jq` works with no flag required.

## Override the format

Pick a format explicitly with `--format`:

```bash theme={null}
talkvalue path person list --format json
talkvalue path person list --format table
talkvalue path person list --format csv
```

Or use the `--json` shorthand:

```bash theme={null}
talkvalue path person list --json
```

The `--json` flag is equivalent to `--format json` and exists because it's the most common override.

## JSON envelope

Every JSON response wraps the result in a stable envelope so scripts can rely on the shape.

Single-resource response:

```jsonc theme={null}
{
  "data": {
    "id": 42,
    "name": "Ada Lovelace",
    "primaryEmail": "ada@analytical-engine.org",
    "company": { "id": 7, "displayName": "Analytical Engine Co." },
    "jobTitle": "Founder"
  }
}
```

List response (paginated):

```json theme={null}
{
  "data": [
    { "id": 1, "name": "Ada Lovelace", "primaryEmail": "ada@analytical-engine.org" },
    { "id": 2, "name": "Charles Babbage", "primaryEmail": "charles@analytical-engine.org" }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 5,
    "totalElements": 100
  }
}
```

The `pagination` block is present on every list command and lets you compute the next page or total count without a second request.

## Error envelope

Errors go to **stderr**, not stdout, and use a separate envelope:

```json theme={null}
{
  "error": { "message": "Person 999999 not found" }
}
```

Because errors go to stderr, this works as expected:

```bash theme={null}
talkvalue path person get 999999 2>/dev/null | jq
```

Pair the JSON message with the [exit code](/cli/exit-codes) to branch in a shell script.

## CSV

`--format csv` works on any list command and writes RFC-4180 compliant CSV with the first row as headers. Use it for spreadsheets or ad-hoc reports:

```bash theme={null}
talkvalue path person list --format csv > people.csv
```

Export-style commands (`person export`, `event person export`, `channel export`, `import failed-export`) always emit CSV regardless of `--format`. They exist specifically for spreadsheet workflows.

## TTY tips

* **Color.** Table output uses color when stdout is a TTY. Turn it off with `--no-color` or `NO_COLOR=1`, or force it with `FORCE_COLOR=1` in places like CI logs that strip TTY detection but render ANSI.
* **Update banner.** The CLI prints an upgrade banner when a newer version is on npm. It's automatically suppressed when output is JSON or piped, so it never contaminates parsed output.

## Related

* [Exit codes](/cli/exit-codes). Branch on success vs auth error vs not-found in scripts.
* [Global flags](/cli/global-flags). `--format`, `--json`, `--no-color`, and the rest.
* [Scripting with jq](/cli/recipes/scripting-with-jq). Common `jq` patterns for CLI output.
* [Environment variables](/cli/environment-variables). `NO_COLOR`, `FORCE_COLOR`.