Instalando o UiPath CLI

Requisitos de instalação e etapas para o UiPath CLI no Windows, macOS e Linux, incluindo pré-requisitos do Node.js e instalação global do npm.

A UiPath CLI é distribuída no npm como @uipath/cli e instala o comando uip globalmente. Ele é executado em qualquer plataforma compatível com o Node.js 22 ou posterior — Windows, macOS e Linux, em x64 e ARM64.

Pré-requisitos

• Node.js 22 ou posterior. O Node.js é enviado com npm, que é suficiente para instalar e executar uip.
• Qualquer plataforma — Windows (x64, ARM64), macOS (x64, ARM64), Linux (x64, ARM64).

Verifique a versão do seu nó:

node --version

Se o Node.js for mais antigo que 22 ou não estiver instalado, baixe-o em nodejs.org ou use um gerenciador de versões, como nvm (macOS/Linux) ou nvm-windows — ou deixe que o instalador de uma linha abaixo provisione o nó para você .

Instalar

Instalação rápida (uma linha)

A maneira mais rápida de obter um uip em funcionamento. Ele garante o Node.js, instala a CLI, executa uip skills install (detecta automaticamente quaisquer agentes de codificação — Claude Code, Cursor, Copilot e assim por diante — estão presentes na máquina) e instala o.NET SDK 8.0 e Python. Cada etapa é idempotente, então o script é seguro para ser executado novamente — ele ignora o que já está em vigor.

# macOS / Linux
curl -fsSL https://download.uipath.com/uipath-cli/install.sh | bash

# Windows (PowerShell)
irm https://download.uipath.com/uipath-cli/install.ps1 | iex

Pule partes que não quiser. Cada opção tem uma variável de ambiente correspondente, o que é útil para o formulário tabulado (nembash -s -- --flag sempre funciona bem com todos os shell):

sinalizador do macOS/Linux	Interruptor do Windows PowerShell	Variável de ambiente	Efeito
--dry-run	-DryRun	UIP_DRY_RUN	Imprime o que seria executado; não muda nada.
--skip-runtimes	-SkipRuntimes	UIP_SKIP_RUNTIMES	Ignora a instalação do.NET SDK e do Python.
--skip-node	-SkipNode	UIP_SKIP_NODE	Deixa o Node.js intacto.
--skip-skills	-SkipSkills	UIP_SKIP_SKILLS	Ignora uip skills install.
--skip-dotnet	-SkipDotnet	UIP_SKIP_DOTNET	Ignora a instalação do.NET SDK.
--skip-python	-SkipPython	UIP_SKIP_PYTHON	Ignora a instalação do Python.

# Preview first — prints what it would do, changes nothing
curl -fsSL https://download.uipath.com/uipath-cli/install.sh | bash -s -- --dry-run

# CLI + skills only, no .NET / Python
curl -fsSL https://download.uipath.com/uipath-cli/install.sh | bash -s -- --skip-runtimes

Instalação manual

Se você já gerencia o nó ou quiser apenas a CLI sem o provisionamento de habilidades/.NET/Python do One-liner:

npm install -g @uipath/cli

Ou com outro gerenciador de pacotes:

pnpm add -g @uipath/cli

bun add -g @uipath/cli

Observação:

Todos os três gerenciadores de pacotes instalam o mesmo pacote @uipath/cli do registro público npm. Use o que sua equipe já tiver em vigor. Se seu .npmrc delimitar o namespace do pacote @uipath para um feed privado (pacotes do GitHub, um proxy do Artefatory, …), esse escopo prevalecerá sobre o registro padrão, e você obterá a compilação desse feed em vez da estável pública. Force o registro público para esta instalação com:

npm install -g @uipath/cli --@uipath:registry=https://registry.npmjs.org/

Homebrew (macOS / Linux)

A UiPath mantém um toque de Homebrew. Este é um caminho de instalação totalmente independente do One-liner e npm/pnpm/bun acima — o Homebrew gerencia o binário uip e sua própria dependência do Node.js.

brew install uipath/tap/uip

Ou toque nele explicitamente primeiro:

brew tap uipath/tap
brew install uip

A atualização e a desinstalação seguem convenções normais do Homebrew:

brew upgrade uip
brew uninstall uip

Observação:

As ferramentas instaladas por meio de uip tools install <tool> são gravadas no prefixo global do npm (npm root -g), não na célula do Homebrew — elas persistem em brew upgrade uip. Para remover totalmente tudo: brew uninstall uip && rm -rf "$(npm root -g)/@uipath".

A instalação coloca o executável uip em seu PATH. No Windows, o inicializador uip.cmd / uip.ps1 reside em %APPDATA%\npm\; no macOS e no Linux, o inicializador uip (um pequeno ajuste em torno de node ./dist/index.js) reside sob o prefixo relatado por npm config get prefix (comumente /usr/local/bin ou ~/.npm-global/bin).

Verifique a Instalação

uip --version

Você deve ver o número da versão instalada (por exemplo, 1.0.0).

uip --help

Você deve ver uma lista de comandos principais — login (com os subcomandos status, tenant list e tenant set ), logout, tools, skills, mcp, completion — seguidos pelas ferramentas que foram instaladas ou registradas em sua máquina.

Para confirmar onde o inicializador uip e suas ferramentas estão:

npm root -g              # directory holding @uipath/cli and installed tools
npm config get prefix    # parent directory whose bin/ folder holds the uip launcher

Primeiro comando

A UiPath CLI é enviada apenas com o host e um pequeno conjunto de comandos principais. Nenhuma ferramenta vem pré-instalada. A primeira vez que você invocar um comando cujo prefixo corresponde a uma ferramenta na lista de permissões de instalação automática, o host baixa e instala essa ferramenta a partir do npm automaticamente.

Por exemplo, a primeira vez que você executa um comando do Orchestrator, uip instala @uipath/orchestrator-tool:

uip or folders list

Installing @uipath/orchestrator-tool...
✓ Installed @uipath/orchestrator-tool
...

As invocações uip or ... subsequentes usam a ferramenta instalada diretamente. Você também pode instalar ferramentas explicitamente — úteis em executores de CI e redes restritas — com uip tools install:

uip tools install @uipath/orchestrator-tool
uip tools install @uipath/solution-tool

Consulte Ferramentas ( plugins ) para a lista de permissões completa e Gerenciamento de ferramentas e habilidades para o gerenciamento de ferramentas do dia a dia.

Controle da instalação automática da ferramenta

A instalação automática é executada sempre que o verbo invocado está na lista de permissões e a ferramenta ainda não está instalada. CI=true tem efeito sobre ela — essa variável não é consultada em nenhum lugar no caminho de instalação automática. A opção de exclusão real é UIPATH_CLI_DISABLE_AUTOINSTALL=true, que desativa totalmente as instalações de ferramentas implícitas, incluindo a verificação diária de atualização por ferramenta descrita em Controle de versão e estabilidade. Em executores de CI sem estado, sem pré-instalar ou definir essa variável, o primeiro comando em uma compilação baixa sua ferramenta e comandos posteriores no mesmo trabalho reutilizam a cópia já instalada, tornando o primeiro comando mais lento que os subsequentes.

Para manter os tempos de compilação de CI determinísticos, pré-instale as ferramentas que você usa como uma etapa separada, para que cada chamada uip posterior as encontre já presentes:

uip tools install @uipath/orchestrator-tool @uipath/solution-tool

A instalação automática é um no-op quando a ferramenta já está instalada, portanto, a etapa de pré-instalação é a única mudança de comportamento de que você precisa. Em um executor isolado onde você deseja uma garantia inflexível de que nada tenta alcançar o npm no meio da compilação, defina UIPATH_CLI_DISABLE_AUTOINSTALL=true também — um comando para uma ferramenta que ainda não está presente falha imediatamente em vez de tentar um download.

Habilitar conclusão do shell

A UiPath CLI envia a conclusão de guia para bash, zsh, object e pwsh. A conclusão é instalada de dentro da própria CLI:

uip completion

Em um terminal, uip completion detecta seu shell de $SHELL / $PSModulePath / plataforma, imprime o arquivo rc de destino que ele modificará e solicita confirmação. Aceite o prompt e reabra seu shell — uip <TAB> agora conclui subcomandos e opções.

Para a configuração com script, canalize o script de conclusão diretamente no seu arquivo rc:

# zsh
uip completion zsh >> ~/.zshrc

# bash
uip completion bash >> ~/.bashrc

# fish
uip completion fish > ~/.config/fish/completions/uip.fish

# PowerShell
uip completion pwsh >> $PROFILE

Outras opções:

• uip completion --print visualize o caminho do destino e o bloco que seria escrito, sem modificar o sistema de arquivos.
• uip completion --uninstall remova o bloco de conclusão gerenciada.

Observação:

A conclusão de valor de sinalizador dinâmico (por exemplo, uip or packages upload --package-name <TAB>) é apenas zsh e requer o utilitário jq em seu PATH. Sem jq, os candidatos dinâmicos são suprimidos; o subcomando estático e a conclusão do nome da opção ainda funcionam em todos os quatro shells.

AVISO:

Executar novamente a conclusão após cada CLI ou atualização de ferramenta

O script de conclusão é um instantâneo estático dos subcomandos e nomes de opções conhecidos no momento em que uip completion foi executado. Após npm install -g @uipath/cli@<new-version>, uip tools install <new-tool> ou uip tools update, execute novamente uip completion para que comandos e sinalizadores recém-adicionados sejam indexados:

uip completion              # interactive — refreshes the existing block
uip completion zsh >> ~/.zshrc   # or pipe into the rc file directly

Sem uma atualização, novos verbos (por exemplo, um verbo adicionado em uma versão da ferramenta MINOR) não serão preenchidos automaticamente, mesmo que funcionem na linha de comando.

Notas da plataforma

Windows

Execute comandos do PowerShell, Terminal do Windows ou cmd. Se uip não for reconhecido após a instalação, abra uma nova janela de terminal para que o PATH atualizado entre em vigor ou execute:

npm config get prefix

e confirme se o diretório retornado está em seu PATH.

macOS e Linux

A maioria dos gerentes de pacotes coloca o executável uip no padrão PATH. Se você instalar globais npm em um diretório local do usuário (conforme recomendado — evita sudo), certifique-se de que esse diretório esteja em seu PATH. Por exemplo, com um prefixo ~/.npm-global :

export PATH="$HOME/.npm-global/bin:$PATH"

Adicione a linha ao seu perfil de shell (~/.zshrc, ~/.bashrc, etc.) para persisti-la.

Por trás de um proxy corporativo

A UiPath CLI respeita as variáveis de ambiente de proxy HTTP padrão para a própria CLI e a instalação automática da ferramenta:

Variável	Finalidade
HTTP_PROXY / http_proxy	Proxy para solicitações HTTP
HTTPS_PROXY / https_proxy	Proxy para solicitações de HTTPS
NO_PROXY / no_proxy	Lista separada por vírgulas de hosts que ignoram o proxy

Exemplos:

# macOS / Linux
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal.corp
uip login

# Windows PowerShell
$env:HTTPS_PROXY = "http://proxy.example.com:8080"
$env:NO_PROXY = "localhost,127.0.0.1,.internal.corp"
uip login

:: Windows cmd
set HTTPS_PROXY=http://proxy.example.com:8080
set NO_PROXY=localhost,127.0.0.1,.internal.corp
uip login

Os proxies com autenticação básica são compatíveis incluindo credenciais no URL: http://user:[e-mail]:8080.

Dica:

A CLI inclui uma implementação fetch com reconhecimento de proxy, para que HTTPS_PROXY / HTTP_PROXY sejam honradas sem configuração extra em Node.js.

Telemetria

A UiPath CLI envia a telemetria de uso anônimo para a UiPath para ajudar a melhorar o produto. Nenhum argumento de comando, conteúdo de arquivo ou credencial é transmitido.

Variável	Comportamento
UIPATH_TELEMETRY_DISABLED	Defina como 1 ou true para recusar.
UIPATH_AI_CONNECTION_STRING	Substitua a string de conexão do Application Insights — por exemplo, para rotear a telemetria para sua própria instância.

# Opt out for the current shell
export UIPATH_TELEMETRY_DISABLED=1

# Or just for one command
UIPATH_TELEMETRY_DISABLED=1 uip login

Instalação no CI/CD

Instale a CLI como uma etapa em seu pipeline. Como uip não tem ferramentas pré-instaladas, deixe as ferramentas se instalarem automaticamente no primeiro uso ou as pré-instale explicitamente — o último é mais rápido em executores sem estado porque o download da ferramenta acontece uma vez por etapa em vez de em cada comando.

Ações do GitHub

steps:
  - uses: actions/setup-node@v4
    with:
      node-version: '22'

  - name: Install UiPath CLI
    run: npm install -g @uipath/cli

  - name: Pre-install tools
    run: uip tools install @uipath/orchestrator-tool @uipath/solution-tool

  - name: Authenticate
    run: uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET
    env:
      UIPATH_CLIENT_ID: ${{ secrets.UIPATH_CLIENT_ID }}
      UIPATH_CLIENT_SECRET: ${{ secrets.UIPATH_CLIENT_SECRET }}

  - name: Run CLI commands
    run: uip or folders list --output json

Azure DevOps

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '22.x'
    displayName: 'Use Node.js 22'

  - script: npm install -g @uipath/cli
    displayName: 'Install UiPath CLI'

  - script: uip tools install @uipath/orchestrator-tool @uipath/solution-tool
    displayName: 'Pre-install UiPath CLI tools'

  - script: uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET
    displayName: 'Authenticate'
    env:
      UIPATH_CLIENT_ID: $(UIPATH_CLIENT_ID)
      UIPATH_CLIENT_SECRET: $(UIPATH_CLIENT_SECRET)

Jenkins (pipeline declarativo)

stage('Install UiPath CLI') {
  steps {
    sh 'npm install -g @uipath/cli'
    sh 'uip tools install @uipath/orchestrator-tool @uipath/solution-tool'
  }
}

stage('Authenticate') {
  steps {
    withCredentials([
      string(credentialsId: 'UIPATH_CLIENT_ID', variable: 'UIPATH_CLIENT_ID'),
      string(credentialsId: 'UIPATH_CLIENT_SECRET', variable: 'UIPATH_CLIENT_SECRET')
    ]) {
      sh 'uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET'
    }
  }
}

Consulte fórmulas de CI/CD para obter exemplos de pipeline completos, incluindo os estágios de empacotamento, publicação e teste.

Dica:

Armazene em cache o diretório global npm entre compilações para evitar a reinstalação @uipath/cli e suas ferramentas em cada execução. No GitHub Actions, use actions/cache chaveado na versão da CLI que você fixar.

Instalação a partir do registro npm do GitHub

A maioria dos usuários não precisa dessa seção — as instalações únicas e manuais acima do pull @uipath/cli e todas as ferramentas incluídas na lista de permissões do registro público npm. Existe para dois casos mais restritos, ambos servidos pelo mesmo registro npm do GitHub (https://npm.pkg.github.com):

• Compilações alfa/internas de @uipath/skills (versões como @uipath/skills@<version>-alpha.*), instaladas transitivamente quando uip skills install precisa de uma compilação mais recente do que a que está no npm público.
• Visualização/compilações internas de alguns pacotes principais — cli, solution-tool, codedagent-tool, orchestrator-tool — publicados para Pacotes do GitHub antes de seu lançamento público npm.

Antes que uip tools install (ou uip skills install) possa resolver um desses, configure o npm para rotear o escopo @uipath por meio do registro do GitHub.

Crie (ou atualize) ~/.npmrc (nível de usuário) ou ./.npmrc (nível de projeto) com:

@uipath:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GH_NPM_REGISTRY_TOKEN}

GH_NPM_REGISTRY_TOKEN é um token de acesso pessoal do GitHub (clássico) com pelo menos o read:packages escopo, autorizado para SSO na organização UiPath.

export GH_NPM_REGISTRY_TOKEN=<your-pat>
npm install -g @uipath/cli

Após configurados, uip tools install e uip tools update coletam pacotes registrados no GitHub da mesma forma que coletam pacotes públicos.

Observação:

Isso não está relacionado a @uipath/rpa-tool, cuja origem e distribuição reais estão em um repositório separado (UiPath/Studio) — o registro npm do GitHub descrito aqui carrega apenas as compilações alfa/prévia listadas acima.

Em execução sem uma instalação global

Para uso ad-hoc ou pipelines que preferem não instalar globalmente, você pode executar a CLI por meio npx:

npx -y @uipath/cli <command>

Por exemplo:

npx -y @uipath/cli login
npx -y @uipath/cli or folders list

A primeira invocação baixa o pacote; as invocações subsequentes reutilizam o cache do npm.

Atualização

Observação:

A CLI atualiza-se automaticamente uma vez por dia. O primeiro comando uip qualificado a cada dia verifica uma versão mais recente em seu canal configurado (stable por padrão — consulte core.updateChannel na configuração do uip), instala-o se existir e executa novamente seu comando original no novo versão. Ele detecta como você instalou o uip ( Homebrew Keg, npm, pnpm, ou anterior anterior) e envia o comando de atualização correspondente automaticamente — brew upgrade uip para uma instalação Homebrew, caso contrário, o comando equivalente add/install. Essa autoatualização nunca passará para uma nova versão MAJOR por conta própria — que sempre requer um uip update explícito ou uma marcação de versão. Uma verificação separada executa por ferramenta, no primeiro uso dessa ferramenta a cada dia, atualizando-a para a versão mais recente na própria linha da CLI. Ambas as verificações são desabilitadas totalmente definindo UIPATH_CLI_DISABLE_VERSION_SYNC=true — útil para executores ou pipelines isolados que exigem uma invocação de uip totalmente determinística e sem rede.

Os comandos manuais abaixo ainda funcionam a qualquer momento — para saltar para uma versão específica imediatamente, para fixar ou com a sincronização diária desabilitada. Use o que corresponde à forma como você instalou uip:

# npm
npm install -g @uipath/cli@latest    # latest release
npm install -g @uipath/cli@1.0.0     # pinned version

# pnpm
pnpm add -g @uipath/cli@latest

# bun
bun add -g @uipath/cli@latest

# Homebrew
brew upgrade uip

O Homebrew sempre é atualizado para qualquer versão que a Tap publicar atualmente — fixar uma versão exata não é um conceito do Homebrew; portanto, use um dos outros métodos se precisar fixar.

Dica:

Fixe uma versão exata no CI. @uipath/cli o versionamento semântico, mas a forma de Data na saída JSON é específica do comando e pode mudar entre versões MINOR (consulte Controle de versão e estabilidade). Fixar evita surpresas no tempo de compilação em pipelines que analisam JSON. Quando você encontrar, valide novamente os scripts que dependem de nomes de campos específicos.

Consulte as notas de versão para saber o que mudou entre as versões.

A atualização do host não atualiza automaticamente as ferramentas instaladas. Para atualizar ferramentas:

uip tools update                        # update all installed tools
uip tools update --name <package>       # update a single tool
uip tools update --name <package> --version <version>   # pin to a specific version

Por padrão, cada versão da ferramenta rastreia a linha MAJOR.MINOR da CLI, portanto, a execução de uip tools update após uma atualização da CLI traz todas as ferramentas instaladas para a etapa. Consulte Ferramentas ( plugins ) para o contrato de anexação.

Desinstalando

Remova a CLI com o método que você usou para instalá-la:

npm uninstall -g @uipath/cli
# or
pnpm remove -g @uipath/cli
# or
bun remove -g @uipath/cli
# or, if installed via Homebrew
brew uninstall uip

Isso remove o uip executável. As ferramentas instaladas (@uipath/orchestrator-tool e semelhantes) residem no prefixo global do npm, independentemente de qual método instalou o host, e não são removidas automaticamente — execute uip tools uninstall <tool> primeiro ou exclua $(npm root -g)/@uipath depois para limpar tudo de uma vez.

Remover credenciais e dados

A desinstalação do pacote deixa várias partes do estado no disco para trás. Limpe-os manualmente quando quiser um novo início ou precisar desativar uma máquina.

Credenciais da sessão

uip login persiste a sessão dentro de ~/.uipath/ em seu diretório inicial por padrão. Quando a CLI é iniciada, ela sobe do diretório atual procurando uma pasta .uipath/ primeiro — para que uma pasta do projeto possa carregar sua própria sessão sem modificar o diretório inicial do usuário. Verifique os dois locais ao limpar:

# macOS / Linux
rm -rf ~/.uipath

# Windows PowerShell
Remove-Item -Recurse -Force "$env:USERPROFILE\.uipath"

Marque também cada projeto em que você trabalha para um .uipath/ local. Consulte Sessões e credenciais para obter o layout completo.

Conclusão do shell

Se você executou uip completion, o bloco de conclusão ainda estará em seu arquivo rc do shell após a desinstalação. Remova-o antes de desinstalar @uipath/cli ou limpe-o manualmente a partir de ~/.zshrc, ~/.bashrc ou $PROFILE:

# Before uninstalling, while uip is still available:
uip completion --uninstall

cache global npm

O npm mantém um cache local de tarballs baixados no caminho relatado por npm config get cache. Isso não precisa ser limpo para a maioria dos usuários; limpe-o apenas para recuperar espaço em disco ou para solucionar problemas de um download corrompido:

npm cache clean --force

Solução de problemas

uip: comando não encontrado após a instalação

O diretório global npm não está em seu PATH. Execute npm config get prefix para ver onde o npm colocou o inicializador uip , em seguida, adicione a subpasta bin desse diretório ao seu PATH e abra um novo terminal.

EACESS ou erros de permissão na instalação

No macOS e Linux, evite sudo npm install. Configure o npm para usar um prefixo de usuário local uma vez:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

Em seguida, reinstale: npm install -g @uipath/cli.

A instalação automática da ferramenta trava ou expira

Você pode estar atrás de um proxy que bloqueia o npm. Configure HTTPS_PROXY conforme descrito em Atrás de um proxy corporativo ou pré-instale as ferramentas em uma máquina com acesso à Internet e copie o node_modules global para a máquina de destino.

Versão do nó muito antiga

uip requer Node.js 22 ou posterior. Atualize o Node.js ou alterne as versões com o nvm use 22.

Consulte Solução de problemas para obter mais erros e suas resoluções.

Próximas Etapas

• Início rápido — faça login, liste pastas do Orchestrator e execute um trabalho em cinco minutos.
• Seu primeiro pipeline — empacotar um projeto e implantá-lo a partir do CI.
• Autenticação — login interativo, credenciais de cliente de aplicativos externos, federada/workload-identity e autenticação de variável de ambiente para CI.
• Uso do UiPath CLI com agentes de codificação — Instale habilidades no Claude Code, Cursor, GitHub Copilot e outros agentes de codificação de IA compatíveis.