# Output formats

> Every `uip` command emits a single structured envelope on stdout. The envelope has the same schema whether you are reading it in a terminal, feeding it into `jq`, or consuming it from a pipeline. Four formats render that envelope differently: `json` (the default), `table`, `yaml`, and `plain`. Switch between them with `--output` and filter with `--output-filter`.

Every `uip` command emits a single structured envelope on stdout. The envelope has the same schema whether you are reading it in a terminal, feeding it into `jq`, or consuming it from a pipeline. Four formats render that envelope differently: `json` (the default), `table`, `yaml`, and `plain`. Switch between them with `--output` and filter with `--output-filter`.

## The envelope

Success:

```json
{
  "Result": "Success",
  "Code": "FolderList",
  "Data": [
    {
      "Key": "9f2b3c…-…",
      "Name": "Shared",
      "Path": "Shared",
      "Type": "Standard"
    }
  ]
}
```

Failure:

```json
{
  "Result": "ValidationError",
  "Message": "Unknown option '--folder-pth'. Did you mean '--folder-path'?",
  "Instructions": "Run 'uip or folders list --help' to see valid options.",
  "Log": "/var/log/uip/2026-04-24.log"
}
```

Fields:

- `Result` — the outcome category. `Success` on success; `Failure`, `ConfigError`, `AuthenticationError`, `ValidationError`, or `TimeoutError` on failure. Maps directly to the [exit code](./exit-codes.md).
- `Code` — the command-specific success identifier. Stable within a MAJOR version (`FolderList`, `SolutionPack`, `JobStarted`, `SkillsInstall`, etc.).
- `Data` — the command's payload. Shape is command-specific; see each command's reference page for the exact fields.
- `Message`, `Instructions` — present on failure. `Message` is the human-readable error; `Instructions` tells the user or operator what to do.
- `Context` — optional failure details (HTTP status, request ID, etc.).
- `Log` — when `--log-file` is active, the path to the log file, included in every envelope.

The envelope itself is **stable across MINOR versions**. The shape of `Data` is command-specific and can evolve — see [Versioning and stability](./versioning.md).

## The four formats

### json (default)

```bash
uip or folders list
```

```json
{
  "Result": "Success",
  "Code": "FolderList",
  "Data": [
    { "Key": "9f2b3c…", "Name": "Shared", "Path": "Shared", "Type": "Standard" },
    { "Key": "a4b8f1…", "Name": "Finance", "Path": "Finance", "Type": "Standard" }
  ]
}
```

Default because it is parseable by any JSON consumer (`jq`, `--output-filter`, scripts, AI agents) and deterministic across versions. In a terminal it reads fine; for a pretty-printed table, switch to `--output table`.

### table

```bash
uip or folders list --output table
```

```
Key         Name       Path      Type
9f2b3c…     Shared     Shared    Standard
a4b8f1…     Finance    Finance   Standard
```

Colored and bordered in a real terminal (colors are suppressed when stdout is not a TTY). Each command picks the **columns** it considers most useful for the table view — not every field in `Data` is necessarily shown. For the complete field set, use JSON or YAML.

**Do not parse the table output.** Column widths, borders, and even the set of columns can change between MINOR versions. It is for human reading only.

### yaml

```bash
uip or folders list --output yaml
```

```yaml
Result: Success
Code: FolderList
Data:
  - Key: 9f2b3c…
    Name: Shared
    Path: Shared
    Type: Standard
  - Key: a4b8f1…
    Name: Finance
    Path: Finance
    Type: Standard
```

A literal YAML serialization of the same envelope as `json`. Useful if your tooling prefers YAML (Ansible, Kubernetes manifests, some CI platforms) or if you are comparing two runs by eye and find YAML easier to scan.

### plain

```bash
uip or folders list --output plain
```

```
Data[0].Key=9f2b3c…
Data[0].Name=Shared
Data[0].Path=Shared
Data[0].Type=Standard
Data[1].Key=a4b8f1…
Data[1].Name=Finance
Data[1].Path=Finance
Data[1].Type=Standard
```

One `path=value` per line. The path is a dot-notation JMESPath-like key into the envelope. Convenient for shell loops on machines that don't have `jq`:

```bash
uip or folders list --output plain | grep -E '\.Name=' | cut -d= -f2
```

## Filtering with --output-filter

`--output-filter` accepts a [JMESPath](https://jmespath.org/) expression. It runs on the full envelope before formatting, so the filter output inherits whichever format `--output` produces.

Some common patterns:

```bash
# just the Data array
uip or folders list --output-filter "Data"

# project specific fields
uip or folders list --output-filter "Data[*].{name: Name, path: Path}"

# count
uip or folders list --output-filter "length(Data)"

# first match
uip or folders list --all --name Shared --output-filter "Data[0]"

# flat list of names
uip or folders list --output-filter "Data[*].Name" --output plain
```

A malformed expression exits with `ValidationError` (exit code `3`) before the command runs, so a typo does not waste an API call. See [Global options — `--output-filter`](./global-options.md#--output-filter) for the full flag.

## Stream separation

`--output` controls **stdout only**. Every other form of output goes to **stderr** regardless of format:

- Log lines (what `--log-level` controls).
- Progress indicators (spinners, download bars during tool auto-install).
- Error text rendered by the host when it detects an invalid flag.

This means a pipeline can capture clean output to a file without losing diagnostics:

```bash
uip or folders list > folders.json 2> uip.log
```

In CI, redirect them separately to make logs greppable without needing to strip ANSI or progress artifacts from the data stream.

## Colors and TTY detection

The `table` format emits ANSI color codes only when stdout is an interactive terminal (`isTTY`). When you pipe to a file or to another process, or run in a CI runner that disables TTY, table output is plain text without escape codes. There is currently no flag to force colors on or off — rely on TTY detection.

Other formats (`json`, `yaml`, `plain`) never emit colors.

## Choosing a format

| Use case | Recommended format |
|---|---|
| Reading in a terminal | `--output table` |
| Scripting (`jq`, shell pipelines) | `--output json` (default) |
| Ansible / Kubernetes integration | `--output yaml` |
| `grep`-friendly flat output without `jq` | `--output plain` |
| AI coding agents | `--output json` (default) with `--output-filter` for focused extraction |
| CI pipelines that pass values between steps | `--output json` with `--output-filter`, or `--output plain` for simple cases |

## See also

- [Global options](./global-options.md) — the `--output`, `--output-filter`, `--log-level`, `--log-file` flags.
- [Exit codes](./exit-codes.md) — mapping from `Result` to process exit code.
- [Scripting patterns](./scripting-patterns.md) — retries, polling, and safe JSON extraction in CI.
- [Versioning and stability](./versioning.md) — what "stable JSON envelope" means under semver.