Ausgabeformate

Jeder uip -Befehl gibt einen einzelnen strukturierten Umschlag in der Standardausgabe aus. Der Umschlag hat das gleiche Schema, unabhängig davon, ob Sie ihn in einem Terminal lesen, in jq übergeben oder aus einer Pipeline verbrauchen. Vier Formate machen diesen Umschlag unterschiedlich: json (Standard), table, yaml und plain. Wechseln Sie zwischen ihnen mit --output und filtern Sie mit --output-filter.

Der Umschlag

Erfolg:

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

Fehler:

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

Felder:

• Result – Die Ergebniskategorie. Success bei Erfolg; Failure, ConfigError, AuthenticationError, ValidationError oder TimeoutError bei Fehler. Wird direkt dem Exitcode zugeordnet.
• Code – der befehlsspezifische Erfolgsbezeichner. Stabil innerhalb einer MaJOR-Version (FolderList, SolutionPack, JobStarted, SkillsInstall usw.).
• Data – die Nutzlast des Befehls. Die Form ist befehlsspezifisch. Die genauen Felder finden Sie auf der Referenzseite jedes Befehls.
• Message, Instructions – bei Fehler vorhanden. Message ist der visuell lesbare Fehler; Instructions teilt dem Benutzer oder Operator mit, was zu tun ist.
• Context – optionale Fehlerdetails (HTTP-Status, Anforderungs-ID usw.).
• Log – wenn --log-file aktiv ist, der Pfad zur Protokolldatei, der in jedem Umschlag enthalten ist.

Die Umschlag selbst ist über mehrere Machine-Versionen hinweg stabil. Die Form von Data ist befehlsspezifisch und kann sich weiterentwickeln – siehe Versionierung und Stabilität.

Die vier Formate

JSON (Standard)

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

Standard, da er von jedem JSON-Verbraucher (jq, --output-filter, Skripte, KI-Agenten) analysiert werden kann und deterministisch über Versionen hinweg ist. In einem Terminal ist es gut; für eine gut gedruckte Tabelle wechseln Sie zu --output table.

Tabelle

uip or folders list --output table

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

farblich und mit Rahmen in einem echten Terminal (Farben werden unterdrückt, wenn Standardausgabe kein Tty ist). Jeder Befehl wählt die Spalten aus, die er für die Tabellenansicht am nützlichsten erachtet – nicht jedes Feld in Data wird unbedingt angezeigt. Verwenden Sie für den vollständigen Feldsatz JSON oder YAML.

Analysieren Sie die Tabellenausgabe nicht. Spaltenbreiten, Rahmen und sogar der Satz von Spalten können sich zwischen MINOR-Versionen ändern. Er ist nur für das menschliche Lesen bestimmt.

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

Eine literale YAML-Serialisierung desselben Umschlags wie json. Nützlich, wenn Ihr Tool YAML bevorzugt (Ansible, Kubernetes-Manifest, einige CI-Plattformen) oder wenn Sie zwei Ausführungen nach Augenvergleich vergleichen und YAML einfacher zu scannen finden.

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

Ein path=value pro Zeile. Der Pfad ist ein JMESPath-ähnlicher Schlüssel mit Punktnotation im Umschlag. Bequem für Shell-Schleifen auf Maschinen, die nicht jq haben:

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

Filtern mit --output-filter

--output-filter akzeptiert einen JMESPath- Ausdruck. Er wird auf dem vollständigen Umschlag vor der Formatierung ausgeführt, sodass die Filterausgabe das Format erbt, das --output erzeugt.

Einige gängige Muster:

# 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

Ein falsch formatierter Ausdruck wird mit ValidationError (Exitcode 3) beendet, bevor der Befehl ausgeführt wird, sodass ein Tippfehler keinen API-Aufruf verschwendet. Das vollständige Flag finden Sie unter Globale Optionen – --output-filter .

Stream-Trennung

--output steuert nur Standard. Jede andere Form der Ausgabe wird unabhängig vom Format an standard :

• Protokollzeilen (was --log-level steuert).
• Fortschrittsindikatoren (Drehfeld, Downloadleisten während der automatischen Installation des Tools).
• Fehlertext, der vom Host gerendert wird, wenn er ein ungültiges Flag erkennt.

Das bedeutet, dass eine Pipeline eine saubere Ausgabe in einer Datei erfassen kann, ohne die Diagnose zu verlieren:

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

Leiten Sie sie in CI separat um, ohne dass ANSI- oder Fortschrittsartefakte aus dem Datenstream entfernt werden müssen.

Erkennung von Farben und Tty

Das table -Format gibt nur ANSI-Farbcodes aus, wenn „stdout“ ein interaktives Terminal ist (isTTY). Wenn Sie eine Pipeline zu einer Datei oder einem anderen Prozess verwenden oder in einem CI-Ausführungsprogramm ausführen, das Tty deaktiviert, ist die Tabellenausgabe in Klartext ohne Escape-Codes. Derzeit gibt es kein Flag, um Farben ein- oder auszuschalten – verlassen Sie sich auf die Tty-Erkennung.

Andere Formate (json, yaml, plain) geben nie Farben aus.

Auswählen eines Formats

Use case	Empfohlenes Format
Lesen in einem Terminal	--output table
Skripting (jq, Shell-Pipelines)	--output json (Standard)
Ansible/Kubernetes-Integration	--output yaml
grepEinfache Ausgabe ohne jq	--output plain
KI-Codierungsagents	--output json (Standard) mit --output-filter für fokussierte Extraktion
CI-Pipelines, die Werte zwischen Schritten übergeben	--output json mit --output-filter oder --output plain für einfache Fälle

Siehe auch

• Globale Optionen – die Flags --output, --output-filter, --log-level, --log-file .
• Austrittscodes – Zuordnung von Result zu Prozessaustrittscode.
• Skriptingmuster – Wiederholungen, Abfragen und sichere JSON-Extraktion in CI.
• Versionierung und Stabilität – was „stabiler JSON-Umschlag“ unter Server bedeutet.