Ferramentas ( plugins )

Arquitetura de ferramentas no UiPath CLI, cobrindo como os pacotes npm instaláveis estendem o host com novos comandos de nível superior.

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 (trabalhos, pastas, processos, pacotes, máquinas, usuários, funções, licenças, ativos, filas, buckets de armazenamento, bibliotecas, gatilhos, webhooks)
solution	@uipath/solution-tool	Solução
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
rpa-legacy	@uipath/rpa-legacy-tool	RPA Legado — wrapper apenas do Windows em torno de uipcli.exe para os comandos do Studio ainda não portados para a ferramenta rpa multiplataforma (depurar, validar, encontrar-atividades, encontrar-pacote, definição de tipo, pacote). Consulte uip rpa-legacy.
eval	@uipath/eval-tool	Avaliação em runtime de pacotes implantados em relação a um processo do Orchestrator — avaliadores, conjuntos de avaliação, avaliações, agendamentos. Pacote independente, não um subcomando de or.
platform	@uipath/platform-tool	Plataforma — licenciamento de tenants, pacotes de usuários, regras de grupo, consumíveis
admin	@uipath/admin-tool	Admin — usuários, grupos, contas de Robots, aplicativos externos, SMTP, autorização, restrição de IP, organizações, tenants, gateways VPN, catálogo de recursos, auditoria
gov	@uipath/gov-tool	Governança — políticas de AOps, políticas de acesso, pacotes de conformidade
agenthub	@uipath/agenthub-tool	AgentHub — registros de servidor MCP, ferramentas, agentes A2A remotos
ah	@uipath/automation-hub-tool	Automation Hub — ideias, pipeline, taxonomia, usuários
aops	@uipath/aops-tool	StudioAdmin AOps — conexões, repositórios, projetos, soluções, pipelines, execuções
coder	@uipath/coder-tool	Programador — agente de codificação de IA (apenas visualização de compilação)
context-grounding	@uipath/context-grounding-tool	Contextualização — Bridge do Python
conversational	@uipath/conversational-tool	Conversacional — chat, agentes, histórico de conversas, truncamentos
function	@uipath/function-tool	Funções — criar, servir e publicar funções JS/TS e Python
guardrails	@uipath/guardrails-tool	Proteções — configurações de proteção BYO, AI Trust Layer
ixp	@uipath/ixp-tool	IXP — Processamento inteligente de documentos (projetos, taxonomia, documentos, implantações)
llm-configuration	@uipath/llmgw-tool	Configuração de LLM — Conexões BYO LLM, AI Trust Layer. Observe que o nome do pacote (llmgw-tool) não corresponde ao alias.
llm-gateway	@uipath/llm-gateway-tool	Gateway de LLM — listar modelos disponíveis. Um pacote separado do llm-configuration acima, apesar do nome semelhante.
model-hub	@uipath/model-hub-tool	Hub do modelo — Configuração de roteamento do gateway de LLM
pm	@uipath/pm-tool	Process Mining — aplicativos, transformações, ingestão de dados
tasks	@uipath/tasks-tool	Tarefas do Action Center — catálogos, comentários, rótulos, metadados, dados

O host trata todo o resto como não uma ferramenta. Esta tabela corresponde exatamente à TOOLS_WHITELIST atual — cada entrada tem uma página de referência neste site. @uipath/flow-tool e @uipath/case-tool estão deliberadamente ausentes: eles não são incluídos em listas de permissões independentemente, mas dependências que @uipath/maestro-tool importa diretamente para registrar suas ramificações flow e case (consulte a nota em Sobre a UiPath CLI).

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:

CI=true não desabilita a instalação automática — essa variável não é consultada em nenhum lugar no caminho de instalação automática. A desativaçã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 (consulte Resolução de versão abaixo). Sem ele, a solução prática ainda é pré-instalar as ferramentas que você sabe que usará — a instalação automática é um não operacional quando a ferramenta já está presente.

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

As compilações de visualização não são selecionadas com uma dist-tag npm como @beta no comando de instalação — essa sintaxe não existe. Em vez disso, o canal de lançamento em toda a CLI é uma configuração de configuração, core.updateChannel, gerenciada com uip config:

uip config set updateChannel preview   # opt into preview tool builds
uip tools install orchestrator-tool    # now resolves the preview line

uip config set updateChannel stable    # switch back

updateChannel é um dos stable (padrão) preview ou; um terceiro dev canal não anunciado existe para compilações de CLI publicadas a partir main de. Os comandos de visualização dentro de uma ferramenta estável são rotulados de forma independente; consulte Controle de versão e estabilidade.

A CLI também mantém a si mesma e suas ferramentas atualizadas automaticamente. Uma vez por dia, o primeiro comando uip elegível verifica uma versão mais recente da CLI no canal configurado e se executa novamente nele, se houver (nunca cruzando uma nova versão MAJOR não assistida); separadamente, cada ferramenta instalada é atualizada para a versão mais recente na própria linha da CLI na primeira vez que você a usa cada dia. Ambas as verificações falham fechadas em vez de ignorar silenciosamente se não puderem ser concluídas. Desabilite ambos com UIPATH_CLI_DISABLE_VERSION_SYNC=true. Para congelar a linha da versão você mesmo em vez de rastrear "mais recente", fixe-a com uip config set version <major.minor[.patch]> — consulte uip config para obter o contrato version/updateChannel exato.

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 — UIPATH_CLI_DISABLE_AUTOINSTALL 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.