Controle de versão e estabilidade

Contrato de versionamento semântico para o UiPath CLI, cobrindo quais mudanças em MAJOR, MINOR e PATCH e a matriz de compatibilidade host/ferramenta.

A UiPath CLI segue o versionamento semântico (MAJOR.MINOR.PATCH), alcançando a disponibilidade geral na versão 1.197.0. 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 é emitido hoje apenas por uip tm perf-scenario execute --wait no tempo limite; mais comandos de longa duração podem adotá-la; portanto, trate-a como "tempo limite".

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 maestro-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.

Atualizar canais

A compilação do host e suas ferramentas resolvem é regida por um canal — uma configuração no nível do host de CLI, não uma tag npm por ferramenta passada no comando de instalação. Existem três canais: stable (padrão), preview e um dev oculto. Defina-o com uip config:

uip config set updateChannel preview   # persistent, affects every uip invocation
uip update --channel preview           # one invocation only
uip config set updateChannel stable    # back to stable

Cada canal mapeia para uma dist-tag npm real:

Canal	Publicado de	Registro	Dist-tag
stable	Execução de versão manual em release/*	Npmjs	latest (ou previous para um backport abaixo de latest)
preview	Enviar para release/*	npmjs, espelhados para Pacotes do GitHub	preview
dev	Enviar para main	Apenas pacotes do GitHub	dev

dev é aceito (uip config set updateChannel dev), mas deliberadamente deixado de fora de --help e os "valores válidos" listas — existe para que uma CLI -dev.* resolve ferramentas em sua própria linha, não como um canal para optar.

Fixar uma versão de pré-lançamento exata diretamente ainda funciona para uma versão única (uip tools install maestro-tool@1.0.0-preview.1), mas updateChannel é o que rege a resolução contínua — um uip tools update não fixado ou uma instalação automática sempre resolve novamente o canal, não uma tag que você aprovado uma vez. Consulte uip config para obter a referência de chave completa updateChannel/version .

Atualizações automáticas

Deixado sozinho, uip se mantém atual — isso acontece por padrão, sem opção de inclusão.

A sincronização diária da CLI

Uma vez por dia, o primeiro comando elegível verifica uma versão mais recente da CLI no canal resolvido, instala-a, atualiza as habilidades e executa novamente seu comando original na nova versão — de forma transparente, no meio da invocação. Ele grava apenas no stderr (um controle giratório em terminais interativos) e nunca altera o código de saída do seu comando. Um uip update manual nunca é limitado por essa porta diária.

Ela nunca cruza uma versão MAJOR unattended. Sem PIN de versão, a sincronização diária limita-se ao MAJOR que já está sendo executada — publicar 2.0.0 em latest não atualiza silenciosamente uma instalação 1.x durante a noite. Ele anuncia a nova versão que recusou para que você possa optar deliberadamente:

uip update                          # explicit, unrestricted — crosses the major
uip config set version 2.0          # or pin the new line instead

A sincronização updateloginlogoutmcpcompletionconfigskillshelp igno / verbos, --version/,--help um core.version pino exato) e pode ser desativado inteiramente com:

export UIPATH_CLI_DISABLE_VERSION_SYNC=true

O estado é rastreado em ~/.uipath/version-sync.json; uip login nunca o toca.

A verificação diária por ferramenta

Separadamente, a primeira vez que um verbo de ferramenta é executado a cada dia, a CLI faz uma pesquisa de registro para essa ferramenta na linha major.minor da CLI em execução e instala a mais nova compilação correspondente antes que a ferramenta carregue — sem reexecutar, pois as ferramentas são carregadas lentamente em o mesmo processo. Essa verificação falha fechada: se a pesquisa ou a instalação falhar, o comando não é executado (um resultado Failure solicita que você verifique a conectividade e tente novamente), em vez de arriscar executar uma ferramenta obsoleta. UIPATH_CLI_DISABLE_VERSION_SYNC e UIPATH_CLI_DISABLE_AUTOINSTALL ignoram essa verificação; o mesmo acontece com um pino core.version exato.

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.