Formatos de saída

Cada comando uip emite um único envelope estruturado no stdout. O envelope tem o mesmo esquema, esteja você lendo-o em um terminal, inserindo-o em jq ou consumindo-o de um pipeline. Quatro formatos renderizam esse envelope de forma diferente: json (o padrão), table, yaml e plain. Alterne entre eles com --output e filtre com --output-filter.

O envelope

Sucesso:

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

Falha:

{
  "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 a categoria de resultado. Success em caso de sucesso; Failure, ConfigError, AuthenticationError, ValidationError, ou TimeoutError em falha. Mapeia diretamente para o código de saída.
• Code o identificador de sucesso específico do comando. Estável dentro de uma versão MAJOR (FolderList, SolutionPack, JobStarted, SkillsInstall, etc.).
• Data a carga útil do comando. A forma é específica do comando; consulte a página de referência de cada comando para obter os campos exatos.
• Message, Instructions — presente na falha. Message é o erro legível por humanos; Instructions informa ao usuário ou operador o que fazer.
• Context detalhes de falha opcionais (status HTTP, ID da solicitação etc.).
• --log-file Log ativo, o caminho para o arquivo de log, incluído em cada envelope.

O envelope em si é estável entre versões MINOR. A forma de Data é específica do comando e pode evoluir — consulte Controle de versão e estabilidade.

Os quatro formatos

json (padrão)

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

Padrão porque é analisável por qualquer consumidor JSON (jq, --output-filter, scripts, agentes de IA) e determinístico entre versões. Em um terminal, a leitura é feita corretamente; para uma tabela personalizada, alterne para --output table.

Tabela

uip or folders list --output table

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

Visualizado com bordas em um terminal real (as cores são suprimidos quando stdout não é um TTY). Cada comando escolhe as colunas que considera mais úteis para a exibição de tabela — nem todos os campos em Data são necessariamente mostrados. Para o conjunto de campos completo, use JSON ou YAML.

Não analise a saída da tabela. As larguras das colunas, as bordas e até o conjunto de colunas podem mudar entre as versões MINOR. É apenas para leitura 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

Uma serialização YAML literal do mesmo envelope que json. Útil se suas ferramentas preferirem YAML (Ansible, manifestos do Kubernetes, algumas plataformas de CI) ou se você estiver comparando duas execuções visualmente e achar YAML mais 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

Um path=value por linha. O caminho é uma chave do tipo JmesPath com notação de pontos no envelope. conveniente para loops de shell em máquinas que não têm jq:

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

Filtrando com --output-filter

--output-filter uma expressão JmesPath . Ele é executado no envelope completo antes da formatação, então a saída do filtro herda o formato que --output produz.

Alguns padrões comuns:

# 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

Uma expressão malformada sai com ValidationError (código de saída 3) antes que o comando seja executado, portanto, um erro de digitação não desperdiça uma chamada de API. Consulte Opções globais — --output-filter para o sinalizador completo.

Separação de stream

--output controles stdout apenas. Todas as outras formas de saída vão para stderr independentemente do formato:

• Linhas de log (o que --log-level controla).
• Indicadores de progresso (controles giratórios, barras de download durante a instalação automática da ferramenta).
• Texto de erro renderizado pelo host ao detectar um sinalizador inválido.

Isso significa que um pipeline pode capturar uma saída limpa para um arquivo sem perder diagnóstico:

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

No CI, redirecione-os separadamente para tornar os logs granulares sem a necessidade de remover ANSI ou artefatos de progresso do fluxo de dados.

Cores e Detecção de TTY

O formato table emite códigos de cores ANSI apenas quando stdout é um terminal interativo (isTTY). Quando você canaliza para um arquivo ou para outro processo ou executa em um executor de CI que desabilita o TTY, a saída da tabela é um texto simples sem códigos de escape. No momento, não há sinalizador para forçar a ativação ou desativação de cores — dependa da detecção do TTY.

Outros formatos (json, yaml, plain) nunca emite cores.

Escolhendo um formato

Use case	Formato recomendado
Leitura em um terminal	--output table
Scripting (jq, pipelines de shell)	--output json (Padrão)
Integração do Ansible e Kubernetes	--output yaml
grepsaída simples amigável sem jq	--output plain
Agentes de codificação de IA	--output json (padrão) com --output-filter para extração focada
Pipelines de CI que passam valores entre etapas	--output json com --output-filter, ou --output plain para casos simples

Veja também

• Opções globais — os sinalizadores --output, --output-filter, --log-level, --log-file .
• Códigos de saída — mapeamento de Result para o código de saída do processo.
• Padrões de script — novas tentativas, pesquisas e extração JSON segura no CI.
• Controle de versão e estabilidade — o que "envelope JSON estável" significa em semver.