Instalando o UiPath CLI

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 18 ou posterior — Windows, macOS e Linux, em x64 e ARM64.

Pré-requisitos

• Node.js 18 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 18 ou não estiver instalado, baixe-o em nodejs.org ou use um gerenciador de versão, como nvm (macOS/Linux) ou nvm-windows.

Instalar

NPM

npm install -g @uipath/cli

Pnpm

pnpm add -g @uipath/cli

Observação:

Ambos os gerenciadores de pacotes instalam o mesmo pacote @uipath/cli do registro público npm. Use o que sua equipe já tiver em vigor.

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. Não há sinalizador de exclusão ou variável de ambiente — em particular, CI=true não desabilita a instalação automática. Em executores de CI sem estado, isso significa que o primeiro comando em uma compilação baixa sua ferramenta, e comandos posteriores no mesmo trabalho reutilizam a cópia já instalada. Isso torna o primeiro comando mais lento que os subsequentes, a menos que você faça a pré-instalação.

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.

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: '20'

  - 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: '20.x'
    displayName: 'Use Node.js 20'

  - 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

Um subconjunto de pacotes de ferramentas @uipath/* — atualmente @uipath/rpa-tool e @uipath/flow-tool — é publicado no registro npm do GitHub (https://npm.pkg.github.com) em vez de no registro público npm. Antes que uip tools install possa resolvê-los, 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=${GITHUB_TOKEN}

GITHUB_TOKEN precisa pelo menos do escopo read:packages ; para um pull não autenticado de um pacote público do GitHub, a linha do token pode ser omitida (o comportamento varia de acordo com o pacote — verifique a visibilidade do repositório).

export GITHUB_TOKEN=<your-pat>
npm install -g @uipath/cli
uip tools install @uipath/rpa-tool

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:

O @uipath/cli pacote de host está no registro público npm. Apenas as ferramentas marcadas nas notas de versão como registradas no GitHub precisam do .npmrc extra.

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

Reinstale o pacote com o mesmo comando usado para instalá-lo, escolhendo a versão mais recente ou uma versão fixada:

# latest release
npm install -g @uipath/cli@latest

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

O comando pnpm equivalente é pnpm add -g @uipath/cli@latest.

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 gerenciador de pacotes que você usou para instalá-la:

npm uninstall -g @uipath/cli
# or
pnpm remove -g @uipath/cli

Isso remove o uip e as ferramentas instaladas.

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 o Node.js 18 ou posterior. Atualize o Node.js ou alterne as versões com nvm use 20.

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 clientes de aplicativos externos e autenticação de variáveis de ambiente para CI.
• Uso do UiPath CLI com Agentes de Codificação — instale habilidades no Claude Code, Cursor, GitHub Copilot ou Gemini CLI.