Formatos de saída

Formatos de saída no UiPath CLI, cobrindo o envelope estruturado emitido por cada comando em JSON, tabela, YAML e renderizações simples.

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. Cinco formatos renderizam esse envelope de forma diferente: json (o padrão), table, yaml, plain e markdown. 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.",
  "ErrorCode": "invalid_argument",
  "Retry": "RetryWillNotFix",
  "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.
• ErrorCode — presente em cada falha. Uma taxonomia estável e independente de comando para scripts que precisam de ramificação mais refinada do que o código de saída sozinho: invalid_argument, authentication_required, permission_denied, local_permission_denied, not_found, rate_limited, network_error, timeout, server_error, method_not_allowed, configuration_error, unknown_error.
• Retry — presente em cada falha. Se deve tentar novamente e em quanto tempo: RetryWillNotFix, RetryLater, RetryAfter1Second, RetryAfter10Seconds, RetryAfter30Seconds, RetryAfter60Seconds.
• 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.

ErrorCode e Retry são preenchidos automaticamente em cada falha, mesmo quando um comando não os define explicitamente — consulte Padrões de script — tentando novamente em Retry para saber como ramificar neles em vez de analisar o texto Message .

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 cinco 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

Markdown

uip or folders list --output markdown

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

Renderiza o envelope como markdown com sabor GitHub — uma tabela para uma lista de registros ou linhas **key:** value e seções com cabeçalho aninhada para um único registro. Destinado a um agente ou superfície de chat que lê a saída uip por meio de um shell, não para uma sessão de terminal humano: um comando que já retorna proso (por exemplo, uip rpa validate) passa-o por meio textual em vez de como uma string JSON escapada. Em falha, o formato renderiza **Failed:** <Message> seguido por qualquer Data e Instructions.

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 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 é de texto simples sem códigos de escape por padrão.

Duas variáveis de ambiente substituem a detecção automática do TTY:

Variável	Efeito
NO_COLOR	Qualquer valor força a desativação da cor, mesmo em um TTY.
FORCE_COLOR	Força a cor, mesmo quando stdout não é um TTY — útil quando um visualizador de log CI renderiza códigos ANSI e você quer a tabela personalizada de qualquer maneira.

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

Substituição do formato padrão

O padrão de --output é json quando omitido. Defina UIP_DEFAULT_OUTPUT para alterar o padrão para o shell atual sem passar --output em cada comando:

export UIP_DEFAULT_OUTPUT=table
uip tools list                  # → table

uip tools list --output yaml   # --output still wins → yaml

Aceita table, json, yaml, plain ou markdown; um valor inválido será ignorado e o padrão integrado json será mantido.

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 ou --output markdown para uma renderização legível por chat
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.