Herramientas (complementos)

UiPath CLI es un pequeño host envuelto en un conjunto de herramientas instalables. Cada herramienta es un paquete npm ordinario que registra un comando de nivel superior (y sus subcomandos) con el host. Este es el concepto individual más importante para comprender por qué uip funciona de la forma en que lo hace: qué se instala automáticamente, qué no, cómo se mantienen sincronizadas las versiones y por qué uip --help muestra diferentes comandos en diferentes máquinas.

Host y herramientas

El host (@uipath/cli, el ejecutable uip ) solo posee un conjunto limitado de preocupaciones:

• Autenticación (uip login, uip logout, uip login status, uip login tenant …).
• Gestión de sesiones y credenciales.
• Ciclo de vida de la herramienta (uip tools list / search / install / update / uninstall).
• Habilidades para codificar agentes (uip skills install / update / uninstall).
• El puente del protocolo de contexto del modelo (uip mcp).
• Instalación de finalización de Shell (uip completion).
• Opciones globales (--output, --output-filter, --log-level, --log-file) y el sobre de salida JSON.

Todo lo que afecta a una superficie de UiPath (Orchestrator, soluciones, agentes, flujos, Maestro, empaquetado RPA, Test Manager, Integration Service, Data Fabric, Insights, Traces, DocsAI, flujo de trabajo de API, soluciones verticales, agentes codificados y Coded Apps) reside en un paquete npm independiente que el host carga bajo demanda.

Por qué la división:

• Cadencias de lanzamiento independientes : la herramienta Orchestrator puede enviarse sin volver a lanzar el host, y viceversa.
• Menor huella de instalación : un usuario que solo ejecuta procesos de prueba no necesita las herramientas Flow o Maestro en el disco.
• Contrato estable : las herramientas se comunican con el host a través de una interfaz programática versionada (registro de comandos, sobre de salida, contexto, telemetría), no a través de componentes internos compartidos.
• Inicio más rápido : el código de la herramienta se carga de forma diferida. El host hace lo mínimo para analizar argv e identificar la herramienta relevante, luego requiere el paquete de esa herramienta una vez.

La lista blanca de instalación automática

Un conjunto de herramientas propiedad de UiPath está en una lista blanca de instalación automática. El host los reconoce por su alias de comando y asigna el alias a un paquete npm:

Alias	Paquete	Nombre largo
or	@uipath/orchestrator-tool	Orchestrator
solution	@uipath/solution-tool	Solución
resource	@uipath/resource-tool	Recurso
rpa	@uipath/rpa-tool	RPA (empaquetado, analizador y restauración de Studio)
agent	@uipath/agent-tool	Agente
codedagent	@uipath/codedagent-tool	Agente codificado
codedapp	@uipath/codedapp-tool	Aplicación codificada
maestro	@uipath/maestro-tool	Maestro
tm	@uipath/test-manager-tool	Test Manager
is	@uipath/integrationservice-tool	Integration Service
vss	@uipath/vertical-solutions-tool	Soluciones verticales
api-workflow	@uipath/api-workflow-tool	Flujo de trabajo de API
df	@uipath/data-fabric-tool	Data Fabric
insights	@uipath/insights-tool	Insights
traces	@uipath/traces-tool	Seguimientos
docsai	@uipath/docsai-tool	IA de Documentos

El host trata todo lo demás como si no fuera una herramienta. Se envían dos herramientas adicionales, pero requieren una instalación explícita: no están en la lista blanca de instalación automática:

• Flujo (@uipath/flow-tool, alias flow): instala con uip tools install @uipath/flow-tool antes de ejecutar los comandos uip flow .
• RPA heredado (@uipath/rpa-legacy-tool, alias rpa-legacy): contenedor solo para Windows de uipcli.exe para los comandos de Studio que aún no se han migrado a la herramienta multiplataforma rpa (depurar, validar, buscar actividades, encontrar paquete, definición de tipo, paquete). Instalar con uip tools install @uipath/rpa-legacy-tool. Consulta uip rpa-legacy.

Qué se instala automáticamente y qué no

No hay nada preinstalado. Un nuevo npm install -g @uipath/cli pone solo el host en el disco.

Dos formas de instalar una herramienta en tu máquina:

1. Instalación automática en el primer uso. La primera vez que invocas un comando cuyo prefijo coincide con una entrada de la lista blanca, por ejemplo, uip or folders list antes de que se instale la herramienta Orchestrator, el host descarga e instala @uipath/orchestrator-tool desde npm y luego ejecuta tu comando. Las invocaciones posteriores utilizan la herramienta instalada directamente, por lo que la segunda ejecución es rápida.

2. Instalación explícita. Ejecuta uip tools install <alias> (o el nombre completo del paquete). Mismo estado final; más rápido en runtime porque no se necesita ningún paso de instalación automática. Consulta la referencia de herramientas de UIP.

Utiliza la instalación explícita en ejecutores de CI y para entornos sin conexión para que los tiempos de compilación sean deterministas y el primer comando de un trabajo no pague el coste de descarga único. Consulta la sección de instalación automática de la guía de instalación para ver la compensación completa.

Nota:

La instalación automática no se puede deshabilitar hoy. No hay variable de entorno o marcador que lo omita, ni siquiera CI=true. La solución práctica es preinstalar las herramientas que sabes que utilizarás; la instalación automática no es operativa cuando la herramienta ya está presente. Es probable que esto cambie en una futura versión MENOR.

Las herramientas de terceros no son compatibles con UiPath CLI 1.x. El host se valida con la lista blanca en el momento de la instalación, por lo que uip tools install my-company/some-tool falla con un ValidationError. Un mecanismo de extensión público puede aparecer en una versión posterior; por ahora, uip solo carga las herramientas de la tabla anterior.

Dónde residen las herramientas en el disco

Las herramientas se instalan en una carpeta @uipath/ bajo el prefijo npm que posee el script de entrada de CLI:

• Si instalaste @uipath/cli globalmente (npm install -g @uipath/cli), las herramientas se instalan globalmente junto a él, en $(npm root -g)/@uipath/<tool-name>/.
• Si instalaste el CLI en un proyecto local (npm install @uipath/cli dentro de un paquete), las herramientas se instalan localmente junto a él, en el node_modules/@uipath/<tool-name>/ de ese proyecto.

En otras palabras, las herramientas siguen la CLI: CLI global, herramientas globales; CLI local, herramientas locales. Esto se gestiona automáticamente: no es necesario pasar ningún marcador de ámbito a uip tools install.

Ejecuta uip tools list para ver qué herramientas están instaladas y qué versión. Ejecuta npm root -g para encontrar la ruta de instalación global en tu máquina.

Resolución de versiones: herramientas que realizan un seguimiento del host

De forma predeterminada, cada versión de la herramienta se ancla a la línea major.minor de CLI. Al ejecutar uip tools install or con CLI 1.0.x, el host resuelve la última @uipath/orchestrator-tool cuya versión comienza con 1.0. y la instala. Al ejecutar uip tools update, cada herramienta instalada se actualiza a la última versión que aún se encuentra dentro de la línea major.minor de CLI.

Las consecuencias prácticas:

• Actualizar CLI a una nueva versión MENOR es una operación de dos pasos. Después de npm install -g @uipath/cli@1.1.0, ejecute uip tools update para llevar todas las herramientas instaladas a la versión 1.1.x línea.
• Anclar el CLI ancla de forma efectiva todas las herramientas. npm install -g @uipath/cli@1.0.3 y luego uip tools update produce un conjunto determinista de versiones de herramientas en cualquier máquina.
• El host y las herramientas envían cambios de protocolo compatibles juntos. Una herramienta creada para 1.1.x puede llamar al contrato interno que 1.0.x no conoce: permitir versiones mixtas de CLI+herramienta correría el riesgo de cargar una herramienta que el host no puede entender.

Puedes anular el valor predeterminado e instalar una versión específica de la herramienta explícitamente:

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

Los canales (alpha, beta) son compatibles a través del mecanismo dist-tag de npm; por ejemplo, uip tools install orchestrator-tool@beta elige la versión beta más reciente. Los comandos de vista previa dentro de una herramienta estable se etiquetan de forma independiente; consulta Control de versiones y estabilidad.

Consejo:

Para verificar qué versiones de herramientas hay en una máquina después de una implementación, uip tools list --output json imprime el nombre, la versión y el prefijo de comando de cada herramienta instalada. Compara esto con una instantánea en buen estado para detectar la deriva.

Cómo carga el host las herramientas

Cuando se ejecuta uip <alias> … :

1. El host lee argv, elimina los marcadores globales (--output, --log-level, etc.) e identifica el primer token sin marcador como un alias de herramienta potencial.
2. Si el alias coincide con una herramienta instalada, el host carga esa herramienta bajo demanda y le pide que registre sus subcomandos.
3. Si el alias está en la lista blanca pero la herramienta no está instalada, el host ejecuta la instalación automática (ver arriba) y luego va al paso 2.
4. Si el alias no está en la lista blanca y no es un comando de host reconocido, el host falla con "comando desconocido" e imprime el uso.

Ese es todo el modelo de carga. No hay manifiesto de complemento, no hay archivo de configuración de registro, no hay lista editable por el usuario. La lista blanca integrada en el paquete del host es la fuente de la verdad.

Qué leer a continuación

• Referencia de herramientas de UIP : sintaxis completa y ejemplos para cada subcomando uip tools .
• Instalar UiPath CLI : instala el host; las herramientas siguen a partir de ahí.
• Controlar la instalación automática de la herramienta : la realidad de no darse de baja y la solución alternativa previa a la instalación para CI.
• Gestionar herramientas y habilidades : flujos de trabajo cotidianos (actualización, anclar versiones, inspeccionar deriva).
• Habilidades : un sistema paralelo para enseñar a los agentes de codificación a utilizar uip. Las habilidades no son herramientas, y uip skills es un grupo de comandos independiente.
• Control de versiones y estabilidad : cómo se coordinan las versiones del host y la herramienta en semver.