Códigos de saída

Cada invocação uip termina com um código de saída numérico. Scripts e pipelines de CI ramificam-se nesses códigos para distinguir o sucesso, um erro transitório que vale a pena tentar novamente, um problema de credencial que precisa de atenção humana e um uso indevido da linha de comando.

Contrato

O código de saída é determinado pelo Result no envelope de saída do comando. O host mapeia cada valor Result para um único código de saída:

Código de saída	Result valor(es)	Significado
0	Success	O comando foi concluído e sua intenção foi alcançada.
1	Failure, ConfigError	Falha genérica ou um problema de configuração que a CLI pode detectar antes de chegar ao servidor (tenant ausente, arquivo ausente no disco etc.).
2	AuthenticationError	A sessão não está autenticada, o token expirou ou o Orchestrator rejeitou as credenciais (401 / 403).
3	ValidationError	O comando foi invocado com entrada inválida — sinalizador desconhecido, sinalizador com valor errado, sinalizadores mutuamente exclusivos, --output-filter malformado e assim por diante.
4	TimeoutError	Uma operação de execução longa excedeu seu prazo. Reservado para uso futuro — nenhum comando emite isso hoje, mas o contrato é estável, então os scripts escritos nele continuarão funcionando.

Além disso:

Código de saída	Origem	Significado
130	Convenção do Shell (128 + SIGINT)	O usuário cancelou um prompt interativo (Ctrl+C durante uip login, uip skills install, uip completion, etc.).

Nenhum outro código de saída é emitido pelo UiPath CLI. Um valor fora dessa tabela indica um rescisão anormal — falha não detectada, processo filho descontrolado ou o shell relatando um sinal — e deve ser investigar, não corresponder ao padrão.

Estabilidade

• 0, 1, 2, 3 são estáveis dentro de uma versão MAJOR. Um comando que sai com 3 (validação) para uma determinada entrada continuará saindo com 3 entre incidentes MINOR e PATCH.
• 4 está reservado. Uma versão futura do MINOR pode começar a emiti-lo a partir de comandos de longa duração; os scripts que já identificam 4 como "tempo limite" continuarão funcionando.
• Novos códigos podem ser adicionados em uma versão MAJOR, com aviso prévio nas notas de versão. O conjunto atual abrange todos os modos de falha de que o UiPath CLI 1.x precisa.

Consulte Controle de versão e estabilidade para o contrato semver mais amplo.

Leitura do código de saída em scripts

bash / sh / zsh

uip or folders list
case $? in
  0)   echo "ok" ;;
  1)   echo "command failed" ;;
  2)   echo "not authenticated — run uip login" ;;
  3)   echo "bad input — check flags" ;;
  4)   echo "timed out" ;;
  130) echo "cancelled by user" ;;
  *)   echo "unexpected exit: $?" ;;
esac

set -e (ou set -o errexit) anula o script em qualquer saída diferente de zero. Esse é o padrão comum para o CI; combine-o com trap ou com o tratamento por comando quando você precisar distinguir entre códigos:

set -euo pipefail

if ! uip or folders list --output json > folders.json; then
  case $? in
    2)  uip login ; uip or folders list --output json > folders.json ;;
    *)  exit $? ;;
  esac
fi

PowerShell

uip or folders list
switch ($LASTEXITCODE) {
    0   { Write-Host "ok" }
    1   { Write-Host "command failed" }
    2   { Write-Host "not authenticated" }
    3   { Write-Host "bad input" }
    4   { Write-Host "timed out" }
    130 { Write-Host "cancelled" }
    default { Write-Host "unexpected exit: $LASTEXITCODE" }
}

Ações do GitHub

Qualquer saída diferente de zero em uma etapa run: falha o trabalho por padrão. Para ramificar em códigos específicos, capture o código explicitamente:

- name: Query Orchestrator
  id: folders
  run: |
    uip or folders list --output json > folders.json
    echo "exit_code=$?" >> "$GITHUB_OUTPUT"
  continue-on-error: true

- name: Re-authenticate if expired
  if: steps.folders.outputs.exit_code == '2'
  run: uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET --tenant "$TENANT"
  env:
    UIPATH_CLIENT_ID: ${{ secrets.UIPATH_CLIENT_ID }}
    UIPATH_CLIENT_SECRET: ${{ secrets.UIPATH_CLIENT_SECRET }}
    TENANT: ${{ vars.UIPATH_TENANT }}

Correspondência de códigos de saída com o envelope JSON

Quando --output json em vigor (o padrão), o envelope carrega as mesmas informações que o código de saída, mais uma mensagem legível por humanos:

{
  "Result": "ValidationError",
  "Message": "Unknown option '--folder-pth'. Did you mean '--folder-path'?",
  "Instructions": "Run 'uip or folders list --help' to see valid options."
}

Um pipeline pode se ramificar em $? para decisões rápidas (tentar novamente em 2, anular em 3) e analisar o envelope para obter a imagem de erro completa (mostrar o Message em um webhook do Slack, ticketr o Instructions junto à etapa com falha, etc.).

Semântica específica do comando

Os códigos de saída são códigos de status, não códigos de sucesso. Um comando que relata Success com uma carga Data indicando “nenhum resultado encontrado” ainda sai de 0. Por exemplo, uip or folders list --all --name DoesNotExist retorna {"Data": [], …} e sai de 0 — porque a consulta da lista foi bem-sucedida; a ausência de correspondências é um resultado válido, não uma falha.

Quando um comando precisa distinguir "a operação foi bem-sucedida" de "o resultado do domínio é positivo", ele diz isso em sua página de referência:

• uip tm testsets run — sempre sai 0 quando o Orchestrator aceita a solicitação de execução de teste e retorna o ExecutionId. O veredicto de aprovação/falha vem de uma cadeia uip tm wait + uip tm report get separada; ramificar em Data.Failed na saída do relatório. uip tm wait emite código de saída 2 no tempo limite (uma reutilização específica do domínio do slot de erro de autenticação — observado nas execuções uip tm Wait e uip tm).
• uip or jobs start --wait-for-completion — sai diferente de zero quando o trabalho atinge um estado terminal Faulted ou Stopped . Sem --wait-for-completion, o comando sai 0 assim que o Orchestrator aceita a solicitação, independentemente do resultado posterior do trabalho.

Verifique a página de referência para qualquer comando em que a semântica de "sucesso" seja ambígua.

Veja também

• Opções globais — os sinalizadores --output, --output-filter, --log-level, --log-file .
• Padrões de script — novas tentativas, pesquisa, pipelines idempotentes.
• Formatos de saída — o formato do envelope que espelha o código de saída.
• Controle de versão e estabilidade — como o contrato de código de saída evolui entre novos incidentes.