Migração: alterações interruptivas

Alterações interruptivas a serem revisadas antes de migrar do.NET CLI legado para o UiPath CLI, além de renomeações de sinalizadores automáticos.

Alterações semânticas que interrompem pipelines de maneiras que uma porta sinalizador para sinalizador não detectaria. Leia esta página antes de fazer a porta; o Mapa de comando e as renomeações de sinalizador lidam com o trabalho de renomeação automática.

Cada alteração abaixo tem a mesma estrutura: o que mudou, por que mudou, o que fazer. Explore as primeiras linhas em negrito e explore onde seu pipeline é afetado.

Modos de autenticação removidos

O que mudou. Legado uipcli aceitava três modos de autenticação por comando: usuário/senha (-u/-p), token de atualização (-t/-a) e Aplicativo externo (-A/-I/-S/--applicationScope). A nova CLI aceita credenciais de cliente de Aplicativo Externo (para CI), federada/workload-identity por meio de --client-assertion (para plataformas de CI/CD que podem criar seu próprio token OIDC), OAuth2 interativo (para desenvolvedores) e tokens de acesso de variável de ambiente (para contêineres). A autenticação de usuário/senha e token de atualização se foram — as letras de sinalizador -u, -p, -t, -a são não atribuídas (-u, -p, -a) ou reutilizadas (-t) } é agora --tenant).

Por que. O Automation Cloud descontinuou os fluxos de usuário/senha e atualizar-token para novas cargas de trabalho. As credenciais de aplicativos externos são o único fluxo que escala corretamente entre os executores de CI, suportam auditoria no nível da organização e podem ser revogadas sem girar uma conta humana.

O que fazer. Crie um aplicativo externo na UiPath com os mesmos escopos que seu pipeline lista atualmente em --applicationScope e, em seguida, substitua cada bloco de autenticação por comando por uma única chamada uip login :

# Legacy — auth on every command
uipcli job run "MyProcess" "https://cloud.uipath.com/" "Tenant" \
    -u "[e-mail]" -p "$PASSWORD" -o "Shared"

# uip — auth once, use many
uip login \
    --client-id env.UIPATH_CLIENT_ID \
    --client-secret env.UIPATH_CLIENT_SECRET \
    --tenant "$UIPATH_TENANT"
uip or jobs start "$PROCESS_KEY"

Consulte Autenticação para obter o catálogo de fluxos completo. A seção Autenticação de Renomeações de sinalizador lista cada sinalizador removido.

Leitura de autenticação env-var implícita removida

O que mudou. O legado uipcli lia implicitamente UIPATH_CLIENT_ID e UIPATH_CLIENT_SECRET do ambiente quando os sinalizadores correspondentes estavam ausentes. A nova CLI não faz — as variáveis de ambiente são lidas somente quando você faz referência explicitamente a elas por meio do prefixo env.VAR_NAME em --client-id / --client-secret ou por meio do fluxo do token de acesso UIPATH_CLI_ENABLE_ENV_AUTH=true .

Por que. As leituras implícitas tornavam impossível dizer, a partir de uma etapa do pipeline apenas, de quais segredos o comando dependia. A forma de prefixo explícito env. revela a dependência na própria invocação, o que torna a auditoria, a rotação e a verificação de segredo confiáveis.

O que fazer. Substitua qualquer dependência implícita nas variáveis de env por referências env. explícitas:

# Before — relied on implicit reading
UIPATH_CLIENT_ID="..." UIPATH_CLIENT_SECRET="..." uipcli job run ...

# After — explicit reference
uip login \
    --client-id env.UIPATH_CLIENT_ID \
    --client-secret env.UIPATH_CLIENT_SECRET \
    --tenant "$UIPATH_TENANT"

O formulário env. lê a variável no runtime sem expandi-la para a linha de comando, para que o segredo não apareça no histórico do shell ou na saída ps — um padrão mais seguro do que a leitura implícita legada. Consulte Autenticação — o prefixo env.VAR_NAME .

As versões com versão do calendário desapareceram

O que mudou. Legado enviado como versões de calendário (2023.10, 2024.10, 2025.10) no NuGet (UiPath.CLI, UiPath.CLI.Windows), com layouts de pasta como .../UiPath.CLI.25.10.xxxx/tools/uipcli.dll. A nova CLI é distribuída no npm como @uipath/cli com versionamento semântico (1.0.0, 1.0.1, 1.1.0, 2.0.0).

Por que. O controle de versão do calendário comunica a data de lançamento, mas não a compatibilidade. Semver comunica compatibilidade: 1.0.x → 1.1.x é cumulativo, 1.x → 2.x é interrompido e precedido por um ciclo de descontinuação. Host + pacotes de ferramenta também se coordenam em semver — as versões de ferramenta fixadas na linha MAJOR.MINOR da CLI automaticamente.

O que fazer. Remova todas as referências aos pacotes NuGet com versão de calendário, caminhos uipcli.dll e nomes de pastas anuais dos pipelines. Instalar com npm, fixar com @x.y.z:

# Before — Azure DevOps example
curl -L -O https://www.nuget.org/api/v2/package/UiPath.CLI.Windows/25.10.xxxx
unzip UiPath.CLI.Windows.25.10.xxxx -d ./cli
./cli/tools/uipcli.exe ...

# After
npm install -g @uipath/cli@1.0.0
uip tools install or solution tm   # pre-install tools (optional but deterministic)
uip ...

Consulte Instalação do UiPath CLI e Controle de versão e estabilidade para o contrato semver completo.

Alteração de runtime: o Node.js 22+ substitui.NET como o runtime da CLI; O rpa-tool mantém uma dependência do.NET

O que mudou. Legado uipcli executado inteiramente no .NET (UiPath.CLI exigiu o.NET 6 multiplataforma; UiPath.CLI.Windows usou o .NET Framework). O novo host uip é um programa Node.js — cada invocação requer o Node.js 22 ou posterior no executor, independentemente de quais ferramentas são usadas. O host em si não tem dependência do.NET, e a maioria das ferramentas (Orchestrator, Solution, Agent, Flow, Maestro, Test Manager, Integration Service, Data Fabric, Insights, Traces, DocsAI) faz apenas chamadas HTTPS e não adiciona mais nada.

A ferramenta de RPA (@uipath/rpa-tool invocada como uip rpa pack / analyze / restore) é a exceção. Ele encapsula o empacotador do Studio e o compilador de fluxo de trabalho, ambos baseados em.NET. Os pipelines que executam comandos uip rpa … precisam de um runtime.NET além do Node.js, não em lugar dele. Consulte a referência do uip rpa para ver os pré-requisitos atuais.

Por que. A CLI principal movida para o nó para uma pegada de runtime menor e mais portátil, distribuição multiplataforma mais simples e uma histórias de registro único (npm). A superfície específica de RPA mantém seu back-end de .NET porque o empacotador e o analisador do Studio são .NET nativos — reescrevê-los estava fora do escopo para a versão 1.0.

O que fazer.

1. Sempre provisione o Node.js 22+ no executor. Isso é necessário para a própria uip; sem o nó, nenhum comando uip é executado.

   # GitHub Actions example
   - uses: actions/setup-node@v4
     with:
       node-version: '22'
   

2. Se seu pipeline chamar uip rpa pack, uip rpa analyze ou uip rpa restore, mantenha também um runtime.NET disponível no executor. Você não instala mais o legado uipcli por meio de dotnet tool install, mas o próprio runtime.NET ainda deve estar presente para que rpa-tool possa invocar o empacotador do Studio.

3. Se seu pipeline não chamar, remova a etapa de configuração uip rpa … dotnet-sdk . As ferramentas restantes (Orchestrator, Solution, Agent, Flow, Maestro, Test Manager etc.) não precisam dele.

Consulte Instalação do UiPath CLI — CI/CD.

Contrato do código de saída reduzido

O que mudou. O legado uipcli emitiu uma gama mais ampla de códigos de saída, muitas vezes misturando códigos de nível de processo.NET (1 a 3 dígitos, específicos do framework) com códigos de nível de comando. A nova CLI emite exatamente cinco códigos canônicos (0, 1, 2, 3, 4) mais 130 para cancelamento do usuário, e o mapeamento do resultado para o código é estável dentro de uma versão MAJOR .

Código de saída	Significado
0	Sucesso.
1	Falha genérica ou erro de configuração.
2	Erro de autenticação (401/403).
3	Erro de validação (sinalizador incorreto, opção desconhecida, sinalizadores mutuamente exclusivos).
4	Erro de tempo limite. Emitido por uip tm perf-scenario execute --wait quando seu tempo limite passa.
130	Usuário cancelado (Ctrl+C).

Uma reutilização específica do domínio: uip tm wait retorna 2 no tempo limite (para que os scripts possam distinguir o tempo limite do slot de autenticação). Caso contrário, o contrato é uniforme.

Por que. Um conjunto pequeno e estável de códigos torna a lógica de nova tentativa/escalonamento de CI direta: 2 significa "reautenticar e depois tentar novamente". 3 significa "nunca tentar novamente, corrija o comando"; 1 significa "tentar novamente uma vez se transitório". O amplo intervalo legado exigia pipelines para lidar com os códigos de cada comando individualmente.

O que fazer. Substitua ramificações específicas de código pelas novas cinco. Se seu pipeline tiver lógica como "tentar novamente em qualquer código diferente de zero", ajuste-o para tentar novamente 1 em:

# Before — broad retry
if ! uipcli job run ...; then sleep 30; uipcli job run ...; fi

# After — targeted branching
if ! uip or jobs start "$KEY" --wait-for-completion; then
    case $? in
        2)   uip login ...; uip or jobs start "$KEY" --wait-for-completion ;;
        3)   exit 3 ;;   # don't retry bad input
        *)   exit 1 ;;
    esac
fi

Observação: uip tm testsets run sempre sai de 0 quando o Test Manager aceita a solicitação de execução. As falhas vêm por meio de uip tm wait + uip tm report get com Data.Failed, não o código de saída de run. Consulte Códigos de saída. A página uip tm wait documenta sua semântica de código de saída.

stdout é JSON por padrão

O que mudou. Legado uipcli gravou texto de log legível por humanos no stdout; o código de saída e quaisquer arquivos produzidos eram as únicas saídas legíveis pelo computador. A nova CLI grava um envelope JSON no stdout por padrão em cada comando:

{
  "Result": "Success",
  "Code": "JobCompleted",
  "Data": { "Key": "...", "State": "Successful", "...": "..." }
}

Logs, progresso e erros voltados para humanos vão para stderr, independentemente do valor --output . A visualização de tabela legível por humanos é opcional com --output table.

Por que. Primeira saída JSON significa que cada comando é scripts sem truques de análise, e a mesma invocação funciona de forma idêntica em um terminal e um pipeline. Registrar em stderr significa que um pipeline pode command > payload.json 2> log.txt limpar.

O que fazer. Qualquer etapa de shell que assistiu a saída de texto uipcli com grep deve alternar para uma destas opções:

• --output-filter "<JMESPath>" --output plain extraia um único campo como texto simples. Exemplo: --output-filter "Key" --output plain.
• jq analise o envelope completo.
• --output table somente exibição; não analise a saída da tabela.

# Before
JOB_ID=$(uipcli job run ... | grep -oP 'JobId=\K[0-9a-f-]+')

# After
JOB_KEY=$(uip or jobs start "$KEY" \
    --output-filter "Jobs[0].Key" \
    --output plain)

Consulte Formatos de saída. O próprio sinalizador --output-filter está documentado em Opções globais.

As URLs do tenant e do Orchestrator são de estado de sessão, não sinalizadores por comando

O que mudou. O legado uipcli usou <orchestrator_url> e <orchestrator_tenant> como argumentos posicionais em cada verbo (job run "<name>" "<url>" "<tenant>" ...). A nova CLI resolve tanto a partir da sessão autenticada escrita por uip login; nenhum URL posicional é necessário, e o tenant é um padrão de sessão, alternável com uip login tenant set <name> sem nova autenticação.

Por que. Cada comando em um pipeline normalmente tem como alvo o mesmo Orchestrator; passar o URL e o tenant em cada chamada era repetitivo e convidava a erros de copiar-colar. O estado da sessão é o padrão da CLI padrão (consulte az account set, gcloud config set, kubectl config use-context).

O que fazer. Solte o URL posicional e o tenant de cada comando. Defina o tenant no login:

# Before
uipcli package deploy "./pkg.nupkg" \
    "https://cloud.uipath.com/" "ProdTenant" \
    -A "org" -I "..." -S "..." -o "Shared"
uipcli job run "Process" \
    "https://cloud.uipath.com/" "ProdTenant" \
    -A "org" -I "..." -S "..." -o "Shared"

# After
uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET --tenant ProdTenant
uip or packages upload ./pkg.nupkg
uip or processes create --name Process --package-key Process --package-version 1.0.0 --folder-path Shared
uip or jobs start "$PROCESS_KEY"

Para scripts de vários tenants, alterne os tenants entre chamadas com uip login tenant set <name>. Consulte Autenticação — gerenciar tenants no meio da sessão.

Os conceitos de pastas clássicas são descontinuados na superfície da CLI

O que mudou. A CLI legada carregava vários sinalizadores apenas de pastas clássicas: -e, --environments <csv> em package deploy, -r, --robots <csv> em job run e roteamento baseado em ambiente relacionado. A nova CLI tem como alvo o modelo de pasta moderna exclusivamente em seus verbos públicos. As pastas clássicas ainda existem no Orchestrator, mas uip não expõe sinalizadores específicos clássicos.

Por que. As pastas modernas são o padrão desde 2020. Manter sinalizadores apenas clássicos na nova CLI significaria carregar um comportamento obsoleto para uma nova versão.

O que fazer. Se seu pipeline tem como objetivo uma pasta clássica, (a) migre a pasta para a moderna ( superfície de administração do Orchestrator ) ou (b) continue usando uipcli para essas chamadas específicas por meio do wrapper @uipath/rpa-legacy-tool . Consulte uip rpa — wrapper legado somente do Windows.

Sinalizador de idioma/local removido

O que mudou. A saída de log traduzida -l, --language <locale> legada para o local fornecido. A nova CLI emite logs apenas em inglês.

Por que. As mensagens de log destinam-se a ser consumidas por operadores e sistemas de envio de log, ambos padronizados para o inglês. A localização era um custo sem compensação clara para a camada de CLI.

O que fazer. Remover sinalizadores -l / --language do pipeline. Nenhuma substituição é necessária.

Capturar e reproduzir (--captureCommandToJsonFile + uipcli run) removido

O que mudou. O legado tinha um sinalizador --captureCommandToJsonFile <path> oculto que serializava a invocação atual para JSON e um verbo uipcli run <file> que consumia esse JSON para reproduzir o comando. Ambos são removidos.

Por que. O padrão era usado principalmente para depurar como a tarefa da GUI no Azure DevOps mapeava para sinalizadores de CLI, não como um mecanismo de produção. O novo padrão JSON-stdout da CLI e a filtragem JmesPath cobrem o caso de uso de depuração sem um subsistema separado.

O que fazer. Reescreva qualquer etapa do pipeline que usou uipcli run <file> como uma invocação direta uip . Se você dependiu de --captureCommandToJsonFile para depurar, o novo equivalente é uip <command> --log-level debug --log-file ./uip.log — o arquivo de log contém cada chamada HTTP, atualização de autenticação e carga de ferramenta.

Variável de ambiente de recusa de telemetria renomeada

O que mudou. Ambas as geração são fornecidas com desativação da telemetria anônima por padrão — a telemetria está ativada, a menos que você a desabilite explicitamente. O nome da var de env foi alterado:

Geração	Variável	Valor a desabilitar
Herdado uipcli	UIPATH_EXTENSIONS_CLI_TELEMETRY_ENABLED	False
Novo uip	UIPATH_TELEMETRY_DISABLED	1 ou true

Por que. O novo nome é mais curto, segue o padrão <SCOPE>_DISABLED usado em outro lugar na CLI e elimina o prefixo EXTENSIONS_ (a nova CLI não é uma extensão de nada).

O que fazer. Atualize os executores de CI e máquinas de desenvolvimento que já definiram UIPATH_EXTENSIONS_CLI_TELEMETRY_ENABLED=False para definir UIPATH_TELEMETRY_DISABLED=1. A variável legada é ignorada pela nova CLI, portanto, uma máquina que define apenas o nome antigo enviará telemetria novamente até que o novo seja adicionado. Consulte O que há de novo — Outras mudanças significativas.

Veja também

• Mapa de comando — qual verbo chamar.
• Renomeações de sinalizadores — mapeamento sinalizador por sinalizador.
• Exemplos de pipeline — antes/depois de YAML para as plataformas de CI comuns.
• Códigos de saída — o contrato de cinco níveis.
• O que há de novo — resumo positivo de cada destaque de regravação.