Formatos de salida

Cada comando uip emite un único sobre estructurado en la salida estándar. El sobre tiene el mismo esquema tanto si lo lees en un terminal como si lo introduces en jq o lo consumes desde un proceso. Cuatro formatos representan ese sobre de forma diferente: json (el predeterminado), table, yaml y plain. Cambia entre ellos con --output y filtra con --output-filter.

El sobre

Éxito:

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

Error:

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

Campos:

• Result : la categoría de resultado. Success en caso de éxito; Failure, ConfigError, AuthenticationError, ValidationError o TimeoutError en caso de error. Se asigna directamente al código de salida.
• Code : el identificador de éxito específico del comando. Estable dentro de una versión MAYOR (FolderList, SolutionPack, JobStarted, SkillsInstall, etc.).
• Data : la carga útil del comando. La forma es específica del comando; consulta la página de referencia de cada comando para ver los campos exactos.
• Message, Instructions : presente en caso de fallo. Message es el error legible por humanos; Instructions le dice al usuario u operador qué hacer.
• Context — detalles de fallo opcionales (estado HTTP, ID de solicitud, etc.).
• Log — cuando --log-file está activo, la ruta al archivo de registro, incluido en cada sobre.

El propio sobre es estable en todas las versiones MENOR. La forma de Data es específica del comando y puede evolucionar; consulta Control de versiones y estabilidad.

Los cuatro formatos

json (predeterminado)

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

Predeterminado porque es analizable por cualquier consumidor JSON (jq, --output-filter, scripts, agentes de IA) y determinista en todas las versiones. En un terminal se lee bien; para una tabla bastante impresa, cambia a --output table.

Tabla

uip or folders list --output table

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

Coloreado y bordeado en un terminal real (los colores se suprimen cuando la salida estándar no es un TTY). Cada comando elige las columnas que considera más útiles para la vista de tabla; no se muestran necesariamente todos los campos en Data . Para el conjunto de campos completo, utiliza JSON o YAML.

No analices la salida de la tabla. Los anchos de columna, los bordes e incluso el conjunto de columnas pueden cambiar entre versiones MENOR. Es solo para lectura humana.

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

Una serialización YAML literal del mismo sobre que json. Útil si tus herramientas prefieren YAML (Ansible, los manifiestos de Kubernetes, algunas plataformas de CI) o si comparas dos ejecuciones a simple vista y encuentras que YAML es más fácil de escanear.

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

Uno path=value por línea. La ruta es una clave similar a JMESPath en notación de puntos en el sobre. Práctico para bucles de shell en máquinas que no tienen jq:

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

Filtrar con --output-filter

--output-filter acepta una expresión JMESPath . Se ejecuta en el sobre completo antes de formatear, por lo que la salida del filtro hereda cualquier formato que produzca --output .

Algunos patrones comunes:

# 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

Una expresión mal formada sale con ValidationError (código de salida 3) antes de que se ejecute el comando, por lo que un error tipográfico no desperdicia una llamada a la API. Consulta Opciones globales — --output-filter para ver el marcador completo.

Separación de transmisiones

--output controla solo la salida estándar. Cualquier otra forma de salida va a stderr independientemente del formato:

• Líneas de registro (lo que controla --log-level ).
• Indicadores de progreso (hilanderos, barras de descarga durante la autoinstalación de la herramienta).
• Texto de error representado por el host cuando detecta un marcador no válido.

Esto significa que un proceso puede capturar una salida limpia en un archivo sin perder los diagnósticos:

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

En CI, redirígelos por separado para hacer que los registros sean greppables sin necesidad de eliminar ANSI o los artefactos de progreso del flujo de datos.

Detección de colores y TTY

El formato table emite códigos de color ANSI solo cuando stdout es un terminal interactivo (isTTY). Cuando se conecta a un archivo o a otro proceso, o se ejecuta en un ejecutor de CI que deshabilita TTY, la salida de la tabla es texto sin formato sin códigos de escape. Actualmente no hay ningún marcador para forzar la activación o desactivación de colores: confíe en la detección de TTY.

Otros formatos (json, yaml, plain) nunca emiten colores.

Elegir un formato

Use case	Formato recomendado
Leer en un terminal	--output table
Creación de scripts (jq, procesos de shell)	--output json (Predeterminada)
Integración de Ansible/Kubernetes	--output yaml
grepsalida plana amigable sin jq	--output plain
Agentes de codificación de IA	--output json (predeterminado) con --output-filter para extracción enfocada
Procesos de CI que pasan valores entre pasos	--output json con --output-filter o --output plain para casos simples

Ver también

• Opciones globales : los marcadores --output, --output-filter, --log-level, --log-file .
• Códigos de salida : asignación de Result al código de salida del proceso.
• Patrones de scripting : reintentos, sondeo y extracción segura de JSON en CI.
• Versiones y estabilidad : qué significa "sobre JSON estable" en semver.