Ferramentas ( plugins )

O UiPath CLI é um pequeno host envolvido em um conjunto de ferramentas instaláveis. Cada ferramenta é um pacote npm comum que registra um comando de nível superior (e seus subcomandos) com o host. Esse é o conceito mais importante para entender por que uip funciona da maneira que faz — o que é instalado automaticamente, o que não é, como as versões são mantidas sincronizadas e por que uip --help mostra comandos diferentes em máquinas diferentes.

Host e ferramentas

O host (@uipath/cli, o executável uip ) possui apenas um conjunto restrito de conceitos:

• Autenticação (uip login, uip logout, uip login status, uip login tenant …).
• Gerenciamento de sessões e credenciais.
• Ciclo de vida da ferramenta (uip tools list / search / install / update / uninstall).
• Habilidades para agentes de codificação (uip skills install / update / uninstall).
• A ponte de Protocolo de Contexto do Modelo (uip mcp).
• Instalação de conclusão de shell (uip completion).
• Opções globais (--output, --output-filter, --log-level, --log-file) e o envelope de saída JSON.

Tudo o que entra em contato com uma superfície da UiPath — Orchestrator, Soluções, Agentes, Fluxos, Maestro, empacotamento de RPA, Test Manager, Integration Service, Data Fabric, Insights, Traces, DocsAI, Fluxo de trabalho de API, Soluções verticais, Agentes codificados e Coded Apps — reside em um pacote npm separado que o host carrega sob demanda.

Por que a divisão:

• Cadências de lançamento independentes — a ferramenta do Orchestrator pode ser enviada sem lançar novamente o host e vice-versa.
• Espaço de instalação menor — um usuário que executa apenas pipelines de teste não precisa das ferramentas Flow ou Maestro no disco.
• Contrato estável — as ferramentas comunicam-se com o host por meio de uma interface programática versionada (registro de comando, envelope de saída, contexto, telemetria), não por meio de componentes internos compartilhados.
• Inicialização mais rápida — o código da ferramenta é carregado lentamente. O host faz o mínimo para analisar argv e identificar a ferramenta relevante e, em seguida, exige o pacote dessa ferramenta uma vez.

A lista de permissões de instalação automática

Um conjunto de ferramentas de propriedade da UiPath está em uma lista de permissões de instalação automática. O host os conhece por seu alias de comando e mapeia o alias para um pacote npm:

Alias	Pacote	Nome longo
or	@uipath/orchestrator-tool	Orchestrator
solution	@uipath/solution-tool	Solução
resource	@uipath/resource-tool	Recurso
rpa	@uipath/rpa-tool	RPA (empacotamento do Studio, analisador, restauração)
agent	@uipath/agent-tool	Agente
codedagent	@uipath/codedagent-tool	Agente codificado
codedapp	@uipath/codedapp-tool	Aplicativo codificado
maestro	@uipath/maestro-tool	Maestro
tm	@uipath/test-manager-tool	Test Manager
is	@uipath/integrationservice-tool	Integration Service
vss	@uipath/vertical-solutions-tool	Soluções verticais
api-workflow	@uipath/api-workflow-tool	Fluxo de trabalho da API
df	@uipath/data-fabric-tool	Data Fabric
insights	@uipath/insights-tool	Insights
traces	@uipath/traces-tool	Traces
docsai	@uipath/docsai-tool	Docs AI

O host trata todo o resto como não uma ferramenta. Duas ferramentas adicionais são fornecidas, mas exigem instalação explícita — elas não estão na lista de permissões de instalação automática:

• Fluxo (@uipath/flow-tool, alias flow) — instale com uip tools install @uipath/flow-tool antes de executar comandos uip flow .
• RPA Legacy (@uipath/rpa-legacy-tool, alias rpa-legacy) — wrapper somente do Windows em torno de uipcli.exe para os comandos do Studio ainda não transferidos para a ferramenta rpa multiplataforma (debug, validate, Find-activities, Find-package, definição de tipo, pacote). Instale com uip tools install @uipath/rpa-legacy-tool. Consulte uip rpa-legacy.

O que é instalado automaticamente e o que não é

Nada é pré-instalado. Um npm install -g @uipath/cli novo coloca apenas o host no disco.

Duas maneiras de uma ferramenta ser instalada em sua máquina:

1. Instalar automaticamente no primeiro uso. A primeira vez que você invoca um comando cujo prefixo corresponde a uma entrada da lista de permissões — por exemplo uip or folders list antes da instalação da ferramenta do Orchestrator — o host baixa e instala @uipath/orchestrator-tool a partir do npm e, em seguida, executa seu comando. As invocações subsequentes usam a ferramenta instalada diretamente, então a segunda execução é rápida.

2. Instalação explícita. Execute uip tools install <alias> (ou o nome completo do pacote). Mesmo estado final; mais rápido no runtime porque nenhuma etapa de instalação automática é necessária. Consulte a referência de ferramentas uip.

Use a instalação explícita em executores de CI e para ambientes offline para que os tempos de compilação sejam determinísticos e o primeiro comando em um trabalho não paga o custo de download único. Consulte a seção de instalação automática do guia de instalação para a compensação completa.

Observação:

Não é possível desabilitar a instalação automática hoje. Não há variável de ambiente ou sinalizador que a ignore — nem mesmo CI=true. A solução prática é pré-instalar as ferramentas que você sabe que usará; a instalação automática será um no-op quando a ferramenta já estiver presente. Isso é provável que mude em uma versão futura do MINOR.

Ferramentas de terceiros não são compatíveis com o UiPath CLI 1.x. O host valida em relação à lista de permissões no momento da instalação, então uip tools install my-company/some-tool falha com um ValidationError. Um mecanismo de extensão pública pode aparecer em uma versão posterior; por enquanto, uip carrega apenas as ferramentas na tabela acima.

Onde as ferramentas ficam no disco

As ferramentas são instaladas em uma pasta @uipath/ sob o prefixo npm que possui o script de entrada da CLI:

• Se você instalou @uipath/cli globalmente (npm install -g @uipath/cli), as ferramentas são instaladas globalmente ao lado dele — em $(npm root -g)/@uipath/<tool-name>/.
• Se você instalou a CLI em um projeto local (npm install @uipath/cli dentro de um pacote), as ferramentas são instaladas localmente ao lado dela — no node_modules/@uipath/<tool-name>/ desse projeto.

Em outras palavras, as ferramentas seguem a CLI: CLI global, ferramentas globais; CLI local, ferramentas locais. Isso é tratado automaticamente — você não precisa passar nenhum sinalizador de escopo para uip tools install.

uip tools list para ver quais ferramentas estão instaladas e qual versão. Execute npm root -g para encontrar o caminho de instalação global na sua máquina.

Resolução da versão — as ferramentas rastreiam o host

Por padrão, cada versão da ferramenta é fixada na linha major.minor da CLI. Quando você executa uip tools install or com CLI 1.0.x, o host resolve o @uipath/orchestrator-tool mais recente cuja versão começa com 1.0. e o instala. Quando você executa uip tools update, cada ferramenta instalada é ativada para a versão mais recente ainda dentro da linha major.minor da CLI.

As consequências práticas:

• A atualização da CLI para uma nova versão MINOR é uma operação em duas etapas. Após npm install -g @uipath/cli@1.1.0, execute uip tools update para trazer cada ferramenta instalada para a versão 1.1.x linha.
• Fixar a CLI fixe todas as ferramentas de forma eficaz. npm install -g @uipath/cli@1.0.3 , em seguida, uip tools update produz um conjunto determinístico de versões de ferramentas em qualquer máquina.
• Host e ferramentas enviam alterações de protocolo compatíveis juntos. Uma ferramenta criada para a versão 1.1.x pode chamar contrato interno que 1.0.x não sabe — permitir versões mistas de CLI+ferramenta se arriscaria a carregar uma ferramenta que o host não pode entender.

Você pode substituir o padrão e instalar uma versão específica da ferramenta explicitamente:

uip tools install orchestrator-tool@1.2.3
uip tools update --name @uipath/orchestrator-tool --version 1.2.5

Os canais (alpha, beta) são compatíveis por meio do mecanismo dist-tag do npm — por exemplo, uip tools install orchestrator-tool@beta escolhe a versão beta mais recente. Os comandos de visualização dentro de uma ferramenta estável são rotulados de forma independente; consulte Controle de versão e estabilidade.

Dica:

Para verificar quais versões de ferramenta estão em uma máquina após uma implantação, uip tools list --output json imprime o nome, versão e prefixo de comando de cada ferramenta instalada. Compare isso com um instantâneo conhecido para detectar descompassos.

Como o host carrega ferramentas

Quando uip <alias> … é executado:

1. O host lê argv, remove sinalizadores globais (--output, --log-level etc.) e identifica o primeiro token sem sinalizador como um alias de ferramenta em potencial.
2. Se o alias corresponder a uma ferramenta instalada, o host carregará essa ferramenta sob demanda e solicitará que ela registre seus subcomandos.
3. Se o alias estiver na lista de permissões, mas a ferramenta não estiver instalada, o host executará a instalação automática (veja acima) e, então, irá para a etapa 2.
4. Se o alias não estiver na lista de permissões e não for um comando de host reconhecido, o host falhará com "comando desconhecido" e imprimirá o uso.

Esse é todo o modelo de carregamento. Não há manifesto de plug-in, nenhum arquivo de configuração de registro, nenhuma lista editável pelo usuário. A lista de permissões integrada ao pacote do host é a fonte da verdade.

O que ler a seguir

• referência de ferramentas uip — sintaxe completa e exemplos para cada subcomando uip tools .
• Instalação do UiPath CLI — instale o host; as ferramentas seguem a partir de lá.
• Controle da instalação automática da ferramenta — a realidade sem opção de exclusão e a solução alternativa de pré-instalação para CI.
• Gerenciamento de ferramentas e habilidades — fluxos de trabalho do dia a dia (atualização, fixar versões, inspecionar desvio).
• Habilidades — um sistema paralelo para ensinar agentes de codificação a usar uip. As habilidades não são ferramentas e uip skills é um grupo de comando separado.
• Controle de versão e estabilidade — como as versões do host e da ferramenta são coordenadas sob semver.