Formats de sortie

Chaque commande uip génère une seule enveloppe structurée au niveau de stdout. L'enveloppe a le même schéma, que ce soit dans un terminal, dans jq ou à partir d'un pipeline. Quatre formats rendent cette enveloppe différemment: json (par défaut), table, yaml et plain. Basculez entre elles avec --output et filtrez avec --output-filter

L'enveloppe

Réussite:

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

Échec:

{
  "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 — la catégorie du résultat. Success en cas de réussite; Failure, ConfigError, AuthenticationError, ValidationError, ou TimeoutError en cas d'échec. Mappe directement au code de sortie.
• Code — l'identifiant de réussite spécifique à la commande. Stable dans une version majeure (FolderList, SolutionPack, JobStarted, SkillsInstall, etc.).
• Data — la charge utile de la commande. La forme est spécifique à la commande; voir la page de référence de chaque commande pour les champs exacts.
• Message, Instructions — présent à l'échec. Message est l'erreur lisible par un humain; Instructions indique à l’utilisateur ou à l’opérateur quoi faire.
• Context — détails facultatifs de l'échec (statut HTTP, ID de requête, etc.).
• Log — lorsque --log-file est actif, le chemin d'accès au fichier journal, inclus dans chaque enveloppe.

L'enveloppe elle-même est stable entre les versions mineures. La forme de Data est spécifique aux commandes et peut évoluer — voir Contrôle des versions et stabilité.

Les quatre formats

json (par défaut)

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

Par défaut, car il est analysable par n’importe quel consommateur JSON (jq, --output-filter, scripts, agents d’IA) et déterministe entre les versions. Dans un terminal, elle se lit correctement; pour une table plutôt imprimée, passez à --output table.

Table

uip or folders list --output table

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

Couleurs et bordures dans un terminal réel (les couleurs sont supprimées lorsque stdout n'est pas un GMT). Chaque commande sélectionne les colonnes qu'elle juge les plus utiles pour la vue de la table - tous les champs de Data ne sont pas nécessairement affichés. Pour l’ensemble de champs complet, utilisez JSON ou YAML.

N’analysez pas la sortie de la table. La largeur des colonnes, les bordures et même l'ensemble des colonnes peuvent changer d'une version mineure à l'autre. Il est destiné à la lecture humaine uniquement.

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

Une sérialisation YAML littérale de la même enveloppe que json. Utile si votre outil préférez YAML (Ansible, manifestes Kubernetes, certaines plates-formes CI) ou si vous comparez deux exécutions à l’œil et que vous trouvez YAML plus facile à analyser.

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

Un path=value par ligne. Le chemin d'accès est une clé de type JMESPath à notation par points dans l'enveloppe. Pratique pour les boucles shell sur les machines qui n'ont pas jq:

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

Filtrer avec --output-filter

--output-filter accepte une expression JMESPath . Il s'exécute sur l'enveloppe complète avant le formatage, de sorte que la sortie du filtre hérite du format que --output produit.

Quelques schémas courants:

# 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

Une expression mal formée se termine avec ValidationError (code de sortie 3) avant l'exécution de la commande, de sorte qu'une faute de frappe ne consomme pas d'appel API. Voir Options globales - --output-filter pour l'indicateur complet.

Séparation des flux

--output contrôle uniquement le stdout. Toutes les autres formes de sortie sont transmises à stderr, quel que soit leur format:

• Lignes de journal (ce que --log-level contrôle).
• Indicateurs de progression (fileurs, barres de téléchargement lors de l'installation automatique de l'outil).
• Texte d'erreur rendu par l'hôte lorsqu'il détecte un indicateur non valide.

Cela signifie qu'un pipeline peut capturer la sortie propre d'un fichier sans perdre les diagnostics:

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

Dans CI, redirigez-les séparément pour rendre les journaux exploitables sans avoir à supprimer les artefacts ANSI ou de progression du flux de données.

Détection des couleurs et des Tty

Le format table génère des codes couleur ANSI uniquement lorsque stdout est un terminal interactif (isTTY). Lorsque vous dirigez un pipeline vers un fichier ou un autre processus, ou lorsque vous l'exécutez dans un runtime CI qui désactive TTY, la sortie de la table est du texte brut sans code d'échappement. Il n'existe actuellement aucun indicateur pour forcer l'activation ou la désactivation des couleurs — baser sur la détection TType.

Les autres formats (json, yaml, plain) n'émettent jamais de couleurs.

Choix d’un format

Use case	Format recommandé
Lire dans un terminal	--output table
Scripts (jq, pipelines shell)	--output json (par défaut)
Intégration Ansible / Kubernetes	--output yaml
grep- sortie plate conviviale sans jq	--output plain
Agents de codage d’IA	--output json (par défaut) avec --output-filter pour l'extraction ciblée
Pipelines CI qui transmettent des valeurs entre les étapes	--output json avec --output-filter, ou --output plain pour les cas simples

Voir également

• Options globales — les indicateurs --output, --output-filter, --log-level et --log-file .
• Codes de sortie — mappage de Result au code de sortie du processus.
• Modèles de script — réessais, interrogation et extraction JSON sécurisée dans CI.
• Contrôle des versions et stabilité — ce que signifie une « enveloppe JSON stable» sous semper.