Controle de versão e estabilidade

A UiPath CLI 1.0.0 segue o versionamento semântico (MAJOR.MINOR.PATCH). Isso substitui o esquema baseado em calendário (2023.10, 2024.10, 2025.10) usado pelo .NET CLI legado. Esta página é o contrato — no que você pode confiar de uma versão para a próxima, o que pode mudar e como as versões do host e da ferramenta permanecem compatíveis.

O que semver significa na prática

Bucket	Quando isso acontece	O que pode mudar
Maior (1.x.x → 2.0.0)	Alterações interruptivas em nomes de comandos, semântica de sinalizadores ou no envelope JSON.	Os comandos podem ser renomeados ou removidos; os sinalizadores podem ser renomeados ou ter seu significado alterado; os campos de nível superior do envelope podem mudar de forma. Um ciclo de descontinuação completo precede qualquer versão MAJOR — comandos obsoletos continuam funcionando no MINOR final do MAJOR anterior.
Menor (1.0.x → 1.1.0)	Novos comandos, novas ferramentas, novos sinalizadores, novos subcomandos.	Ativo apenas na superfície de comando. No entanto, a forma de Data dentro do envelope JSON é específica do comando e pode mudar : novos campos adicionados, ocasionalmente campos renomeados ou aninhados. Os scripts que analisam nomes de campos específicos devem ser revalidados em um aumento MINOR.
PATCH (1.0.0 → 1.0.1)	Correções de bugs.	Nenhuma alteração de comportamento documentada. Um patch que altera o comportamento é tratado como um relatório de bug no próprio patch.

Não há sinalizador --preview (ao contrário do Azure CLI). Os comandos com status de Visualização são rotulados em sua página de referência e podem mudar dentro de uma versão MINOR sem aviso — consulte Estabilidade por comando abaixo.

O contrato estável

O seguinte não muda entre as versões MINOR e PATCH. Script neles livremente.

Campos do envelope

Cada comando emite um envelope no stdout com estes campos de nível superior:

Campo	Estabilidade	Significado
Result	Estável	Success, Failure, ConfigError, AuthenticationError, ValidationError, TimeoutError.
Code	Estável dentro de MAJOR	Identificador de sucesso específico do comando (FolderList, SolutionPack, etc.). Novos códigos podem aparecer em versões MINOR para novos comandos.
Data	Específico do comando	Formato da carga definido por cada comando. Pode adicionar campos em versões MINOR. Raramente, os campos podem ser renomeados em MINOR — consulte as notas de versão.
Message, Instructions	Estável	Texto de erro legível por humanos. O conteúdo pode ser aprimorado de versão para versão; presença e função não mudam.
Context, Log	Estável	Campos opcionais. As condições de presença são estáveis.

Consulte Formatos de saída para o envelope em detalhes.

Códigos de saída

O contrato do código de saída de cinco níveis (0 / 1 / 2 / 3 / 4 mais 130 para cancelamento do usuário) é estável dentro de uma versão MAJOR. 4 está reservado — nenhum comando o emite no 1.x hoje — mas os scripts que já lidam com ele continuarão funcionando.

Opções globais

--output --output-filter --log-level --log-file Novas opções globais podem ser adicionadas; os existentes não serão renomeados ou removidos sem uma versão MAJOR.

Separação de stdout/stderr

stdout é o envelope; stderr é um texto de logs, progresso e erro voltado para humanos. Essa separação se mantém em todos os comandos, todos os formatos, todas as versões.

Versões do host e da ferramenta

O host (@uipath/cli, o executável uip ) e cada ferramenta (por exemplo, @uipath/orchestrator-tool) são publicados como pacotes npm independentes, cada um com seu próprio semver. Eles são coordenadas para que um host na versão 1.0.x execute ferramentas na 1.0.x.

Resolução da versão padrão

Quando você executa uip tools install <alias> uma versão explícita, o host seleciona a versão mais recente da ferramenta cuja MAJOR.MINOR corresponde à linha MAJOR.MINOR atual da CLI. Atualizar a CLI de 1.0.x para 1.1.0 e, em seguida, executar uip tools update traz todas as ferramentas instaladas para a linha 1.1.x .

npm install -g @uipath/cli@1.1.0
uip tools update          # all tools → latest 1.1.x

Você pode substituir o padrão para uma ferramenta específica:

uip tools install orchestrator-tool@1.0.2
uip tools update --name flow-tool --version 1.1.5

Por que a marcação é importante

As ferramentas comunicam-se com o host por meio de um contrato TypeScript versionado (registro de comando, formatação de saída, telemetria e contexto). Se o contrato for alterado entre versões MINOR, o host e a ferramenta devem mover juntos. O padrão de fixar versão garante que sim, sem que o usuário tenha que pensar sobre isso.

Canais

O host reconhece npm dist-tags em ferramentas:

• latest a linha estável (padrão quando nenhuma tag é passada).
• beta visualizar compilações antes da linha estável.
• alpha acesso antecipado, compilações instáveis.

uip tools install flow-tool@beta
uip tools update --name flow-tool --version alpha

Os canais são no nível da ferramenta, não no nível do host. Você pode misturar um host estável com uma ferramenta beta para um fluxo de trabalho específico — esteja ciente de que a combinação é menos testada.

Estabilidade por comando

Comandos e sinalizadores individuais carregam um dos três rótulos de estabilidade. Procure-os no topo da página de referência de cada comando.

Label	Significado
GA (padrão; sem rótulo)	O comando é coberto pelo contrato semver acima. Ele não será renomeado ou removido em uma versão MAJOR.
Visualizar	O comando está em desenvolvimento ativo. Sinalizadores, padrões e formato de saída podem mudar sem um impacto MAJOR, embora alterações significativas sejam raras e anunciadas nas notas de versão. Use na produção somente quando estiver preparado para revalidar a cada versão.
Obsoleto	O comando está agendado para remoção na próxima versão MAJOR. Ele continua a funcionar na versão 1.x e emite um aviso no stderr. Use o sucessor listado na nota de descontinuação.

Essa é a mesma convenção que o gcloud usa. A UiPath CLI não abre comandos de Visualização por trás de um sinalizador de opção — eles são visíveis em --help e podem ser chamados.

Fixando recomendações

Para pipelines de CI:

# pin host version
npm install -g @uipath/cli@1.0.0

# pin each tool you use
uip tools install @uipath/orchestrator-tool@1.0.2 \
                  @uipath/solution-tool@1.0.1

Isso proporciona a você um ambiente reprodutível que persiste em versões upstream. Revalidar após cada novo clique de CLI usando os testes de integração do seu pipeline; consulte as notas de versão para alterações da forma Dataconhecidas.

Para estações de trabalho de desenvolvedor:

npm install -g @uipath/cli@latest
uip tools update    # after each CLI upgrade

Menos reprodutível, mais conveniente.

Ciclo de descontinuação

Quando um comando ou sinalizador está sendo desativado, o caminho é:

1. Descontinuação anunciada — o comando é Deprecated em sua página de referência e as notas de versão para a versão MINOR que introduziu a descontinuação o listam. Uma substituição está documentada.
2. Aviso de runtime — uip <deprecated-command> ... continua a funcionar, mas emite um aviso sobre stderr. Os scripts que consomem stdout não são afetados.
3. Remoção no próximo MAJOR — o comando é removido no próximo robôs da versão MAJOR. Há pelo menos um ciclo MAJOR completo entre descontinuação e remoção — tempo suficiente para que qualquer pipeline no ciclo de vida compatível migre.

Execute uip <command> --help para ver se um comando está obsoleto; o rótulo aparece na sinopse.

Quando a forma dos dados é alterada

Como Data é específico do comando e pode mudar em versões MINOR, os pipelines que extraem campos específicos (--output-filter "Data.Jobs[0].Key") são os mais expostos à rotação MINOR. Duas migrações:

• Fixe @uipath/cli no CI (veja acima). Você escolhe quando validar novas formas.
• Consultar defensivamente — prefira expressões JmesPath que toleram campos ausentes (Data.Jobs[0].Key || '') quando você puder; verifique as notas de versão antes de atualizar.

Alterações de forma interruptiva Data em MINOR são raras e sinalizadas nas notas de versão como [Data shape] sob o comando alterado.

Onde observar alterações

• Notas de versão — resumo por versão de comandos adicionados, sinalizadores alterados e mudanças de forma.
• uip --version e uip tools list — o que está instalado atualmente em uma máquina. Compare entre ambientes para detectar descompassos.
• O pacote de cada ferramenta no npm — os editores listam dist-tags e histórico de lançamento lá.

Veja também

• Formatos de saída — a forma de envelope que o contrato descreve.
• Códigos de saída — o contrato de cinco níveis.
• Ferramentas ( Não
• Notas de versão — o que mudou e quando.
• Migração do.NET CLI legado — se você estiver vindo de 2025.10 ou anterior.