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.

The envelope

Success:

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

Failure:

{
  "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"
}

Champs :

• Result — the outcome category. Success on success; Failure, ConfigError, AuthenticationError, ValidationError, or TimeoutError on failure. Maps directly to the exit code.
• 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.

The four formats

json (default)

uip or folders list

{
  "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

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

uip or folders list --output 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

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:

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

Filtering with --output-filter

--output-filter accepts a JMESPath expression. It runs on the full envelope before formatting, so the filter output inherits whichever format --output produces.

Some common patterns:

# 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 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:

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 (par défaut)
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

Voir également

• Global options — the --output, --output-filter, --log-level, --log-file flags.
• Exit codes — mapping from Result to process exit code.
• Scripting patterns — retries, polling, and safe JSON extraction in CI.
• Versioning and stability — what "stable JSON envelope" means under semver.