Versiones y estabilidad

Contrato de versionado semántico para UiPath CLI, que cubre los cambios en MAYOR, MENOR y PARCHE y la matriz de compatibilidad de host/herramienta.

UiPath CLI sigue el versionado semántico (MAJOR.MINOR.PATCH), alcanzando la disponibilidad general en la versión 1.197.0. Esto reemplaza el esquema basado en calendario (2023.10, 2024.10, 2025.10) utilizado por la CLI de .NET heredada. Esta página es el contrato: en qué puedes confiar de una versión a la siguiente, qué puede cambiar y cómo las versiones de host y herramienta se mantienen en sintonía.

Qué significa semver en la práctica

Mejora	Cuando sucede	Qué puede cambiar
MAYOR (1.x.x → 2.0.0)	Romper los cambios en los nombres de los comandos, la semántica de los marcadores o el sobre JSON.	Los comandos pueden cambiarse de nombre o eliminarse; los marcadores pueden cambiar de nombre o modificar su significado; los campos de nivel superior del sobre pueden cambiar de forma. Un ciclo completo de obsolescencia precede a cualquier versión MAYOR: los comandos obsoletos siguen funcionando en la versión MENOR final de la versión MAYOR anterior.
MENOR (1.0.x → 1.1.0)	Nuevos comandos, nuevas herramientas, nuevos marcadores, nuevos subcomandos.	Aditivo solo en la superficie de comando. Sin embargo, la forma de Data dentro del sobre JSON es específica del comando y puede cambiar : nuevos campos añadidos, ocasionalmente campos renombrados o anidados. Los scripts que analizan nombres de campo específicos deben volver a validarse en un aumento MENOR.
PARCHE (1.0.0 → 1.0.1)	Corrección de errores.	No hay cambios de comportamiento documentados. Un parche que cambia el comportamiento se trata como un informe de error en el propio parche.

No hay ningún marcador --preview (a diferencia de la CLI de Azure). Los comandos de estado de vista previa están etiquetados en su página de referencia y pueden cambiar dentro de una versión MENOR sin previo aviso; consulta Estabilidad por comando a continuación.

El contrato estable

Lo siguiente no cambia en las versiones MINOR o PATCH. Script en contra de ellos libremente.

Campos del sobre

Cada comando emite un sobre en la salida estándar con estos campos de nivel superior:

Campo	Estabilidad	Significado
Result	Estable	Success, Failure, ConfigError, AuthenticationError, ValidationError, TimeoutError.
Code	Estable dentro de MAYOR	Identificador de éxito específico del comando (FolderList, SolutionPack, etc.). Pueden aparecer nuevos códigos en versiones menores para nuevos comandos.
Data	Específico del comando	Forma de carga útil definida por cada comando. Se pueden añadir campos en versiones menores. En raras ocasiones, los campos pueden cambiar el nombre a MENOR: ver notas de la versión.
Message, Instructions	Estable	Texto de error legible por humanos. El contenido puede mejorarse de una versión a otra; la presencia y el rol no cambian.
Context, Log	Estable	Campos opcionales. Las condiciones de presencia son estables.

Consulta Formatos de salida para el sobre en detalle.

Códigos de salida

El contrato de código de salida de cinco niveles (0/1/2/3/4 más 130 para la cancelación del usuario) es estable dentro de una versión MAYOR. 4 es emitido hoy solo por uip tm perf-scenario execute --wait en el tiempo de espera; los comandos de ejecución más larga pueden adoptarlo, así que trátelo como "tiempo de espera".

Opciones globales

--output, --output-filter, --log-level, --log-file : estos cuatro marcadores son estables en golpes MENORES. Se pueden añadir nuevas opciones globales; los existentes no se cambiarán de nombre ni se eliminarán sin una versión MAYOR.

Separación de stdout/stderr

Stdout es el sobre; stderr son los registros, el progreso y el texto de error de cara a las personas. Esta separación se mantiene en todos los comandos, todos los formatos y todas las versiones.

Versiones de host y herramienta

El host (@uipath/cli, el ejecutable uip ) y cada herramienta (por ejemplo, @uipath/orchestrator-tool) se publican como paquetes npm independientes, cada uno con su propio servidor. Están coordinados para que un host en la versión 1.0.x ejecute herramientas en 1.0.x.

Resolución de versión predeterminada

Al ejecutar uip tools install <alias> sin una versión explícita, el host selecciona la última versión de la herramienta cuya MAYOR.MENOR coincida con la línea MAYOR.MENOR actual de CLI. Actualizar la CLI de 1.0.x a 1.1.0 y luego ejecutar uip tools update trae todas las herramientas instaladas a la línea 1.1.x .

npm install -g @uipath/cli@1.1.0
uip tools update          # all tools → latest 1.1.x

Puedes anular el valor predeterminado para una herramienta específica:

uip tools install orchestrator-tool@1.0.2
uip tools update --name maestro-tool --version 1.1.5

Por qué importa la fijación

Las herramientas se comunican con el host a través de un contrato de TypeScript versionado (registro de comandos, formato de salida, telemetría, contexto). Si el contrato cambia entre versiones MENOR, el host y la herramienta deben moverse juntos. El valor predeterminado de fijación de versiones garantiza que lo hagan, sin que el usuario tenga que pensar en ello.

Canales de actualización

La compilación en la que se resuelven el host y sus herramientas se rige por un canal : una configuración en el nivel de host CLI, no una etiqueta npm por herramienta pasada en el comando de instalación. Existen tres canales: stable (predeterminado), preview y un dev oculto. Configúralo con uip config:

uip config set updateChannel preview   # persistent, affects every uip invocation
uip update --channel preview           # one invocation only
uip config set updateChannel stable    # back to stable

Cada canal se asigna a una etiqueta de distribución npm real:

Canal	Publicado desde	Registro	Etiqueta de distancia
stable	Ejecución de lanzamiento manual en release/*	npmjs	latest (o previous para un backport por debajo de latest)
preview	Insertar a release/*	npmjs, reflejado en Paquetes de GitHub	preview
dev	Insertar a main	Solo paquetes de GitHub	dev

dev se acepta (uip config set updateChannel dev) pero se ha dejado deliberadamente fuera de --help y "valores válidos" listas: existe, por lo que una CLI -dev.* resuelve las herramientas en su propia línea, no como un canal en el que optar.

Anclar una versión preliminar exacta directamente sigue funcionando para una única vez (uip tools install maestro-tool@1.0.0-preview.1), pero updateChannel es lo que rige la resolución en curso: un uip tools update no anclado o una instalación automática siempre se vuelve a resolver en el canal, no una etiqueta que aprobado una vez. Consulta uip config para obtener la referencia completa de la clave updateChannel/version .

Actualizaciones automáticas

Si se deja solo, uip se mantiene actualizado: esto sucede de forma predeterminada, sin habilitación.

La sincronización CLI diaria

Una vez al día, el primer comando elegible busca una versión CLI más reciente en el canal resuelto, la instala, actualiza las habilidades y vuelve a ejecutar tu comando original en la nueva versión , de forma transparente, en mitad de la invocación. Solo escribe en stderr (un spinner en terminales interactivos) y nunca cambia el código de salida de tu comando. Esta puerta diaria nunca limita un uip update manual.

Nunca cruza una versión MAYOR unattended. Sin pin de versión, la sincronización diaria se limita a la MAYOR que ya se está ejecutando: publicar 2.0.0 en latest no actualiza silenciosamente una instalación 1.x de la noche a la mañana. Anuncia la nueva versión que ha rechazado para que puedas habilitarla deliberadamente:

uip update                          # explicit, unrestricted — crosses the major
uip config set version 2.0          # or pin the new line instead

La sincronización omite ciertos contextos automáticamente (CI env-var auth, una comprobación de monorepo, una instalación incluida en Studio, update/login/logout/mcp/completion/config/skills/help verbos, --version/--help, un pin exacto core.version) y se puede desactivar por completo con:

export UIPATH_CLI_DISABLE_VERSION_SYNC=true

El estado se rastrea en ~/.uipath/version-sync.json; uip login nunca lo toca.

La comprobación diaria por herramienta

Por separado, la primera vez que se ejecuta un verbo de herramienta cada día, la CLI realiza una búsqueda de registro para esa herramienta en la línea de la CLI en ejecución major.minor e instala la compilación más reciente que coincida antes de que se cargue la herramienta. el mismo proceso. Esta comprobación falla: si la búsqueda o la instalación fallan, el comando no se ejecuta en absoluto (un resultado Failure te pide que compruebes la conectividad y vuelvas a intentarlo) en lugar de arriesgarte a ejecutar una herramienta obsoleta. UIPATH_CLI_DISABLE_VERSION_SYNC y UIPATH_CLI_DISABLE_AUTOINSTALL omiten esta comprobación; lo mismo ocurre con un pin core.version exacto.

Estabilidad por comando

Los comandos y marcadores individuales llevan una de tres etiquetas de estabilidad. Búscalos en la parte superior de la página de referencia de cada comando.

Etiqueta	Significado
GA (predeterminado; sin etiquetar)	El comando está cubierto por el contrato de período anterior. No se cambiará el nombre ni se eliminará dentro de una versión MAYOR.
Preliminar	El comando está en desarrollo activo. Los marcadores, los valores predeterminados y la forma de salida pueden cambiar sin un cambio IMPORTANTE, aunque los cambios de última hora son raros y se anuncian en las notas de la versión. Utilízalo en producción solo cuando estés preparado para volver a validar en cada versión.
Obsoleto	El comando está programado para su eliminación en la próxima versión MAYOR. Sigue funcionando en 1.x y emite una advertencia en stderr. Utiliza el sucesor enumerado en la nota de obsolescencia.

Esta es la misma convención que utiliza gcloud. UiPath CLI no bloquea los comandos de vista previa detrás de un marcador de aceptación: son visibles en --help y se pueden llamar.

Recomendaciones de anclaje

Para procesos de CI:

# pin host version
npm install -g @uipath/cli@1.0.0

# pin each tool you use
uip tools install @uipath/orchestrator-tool@1.0.2 \
                  @uipath/solution-tool@1.0.1

Esto te proporciona un entorno reproducible que sobrevive a las versiones anteriores. Vuelve a validar después de cada aumento de CLI utilizando las pruebas de integración de tu proceso; consulta las notas de la versión para ver los cambios conocidos en Datashape.

Para estaciones de trabajo de desarrollador:

npm install -g @uipath/cli@latest
uip tools update    # after each CLI upgrade

Menos reproducible, más conveniente.

Ciclo de obsolescencia

Cuando un comando o marca va a desaparecer, la ruta es:

1. Obsolescencia anunciada : el comando está marcado como Deprecated en su página de referencia, y las notas de la versión MENOR que introdujo la obsolescencia lo enumeran. Se documenta un reemplazo.
2. Advertencia de runtime : uip <deprecated-command> ... sigue funcionando, pero emite una advertencia en stderr. Los scripts que consumen stdout no se ven afectados.
3. Eliminación en la siguiente versión MAYOR : el comando se elimina en la siguiente versión MAYOR. Hay al menos un ciclo MAYOR completo entre la obsolescencia y la eliminación: tiempo suficiente para que cualquier proceso en el ciclo de vida compatible migre.

Ejecuta uip <command> --help para ver si un comando está obsoleto; la etiqueta aparece en la sinopsis.

Cuando cambia la forma de datos

Dado que Data es específico de un comando y puede cambiar en las versiones MENOR, los procesos que extraen campos específicos (--output-filter "Data.Jobs[0].Key") son los más expuestos a la rotación MENOR. Dos mitigaciones:

• Anclar @uipath/cli en CI (ver arriba). Tú eliges cuándo validar nuevas formas.
• Consulta de forma defensiva : prefiere las expresiones JMESPath que toleran campos faltantes (Data.Jobs[0].Key || '') cuando puedas; consulta las notas de la versión antes de actualizar.

Los cambios de forma Data en MINOR son raros y se marcan en las notas de la versión como [Data shape] en el comando cambiado.

Dónde observar los cambios

• Notas de la versión : resumen por versión de los comandos añadidos, marcadores modificados y cambios de forma.
• uip --version y uip tools list : lo que está instalado actualmente en una máquina. Compara entre entornos para detectar la deriva.
• El paquete de cada herramienta en npm : los editores enumeran las etiquetas de distribución y el historial de versiones allí.

Ver también

• Formatos de salida : la forma del sobre que describe el contrato.
• Códigos de salida : el contrato de cinco niveles.
• Herramientas (complementos) : el modelo de herramienta de host que admite la fijación de versiones.
• Notas de la versión : qué ha cambiado y cuándo.
• Migración desde .NET CLI heredado : si vienes de 2025.10 o anterior.