Versiones y estabilidad

UiPath CLI 1.0.0 sigue el control de versiones semántico (MAJOR.MINOR.PATCH). Esto reemplaza el esquema basado en calendario (2023.10, 2024.10, 2025.10) utilizado por el .NET CLI heredado. 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 está reservado: ningún comando lo emite en la versión 1.x hoy en día, pero los scripts que ya lo gestionan seguirán funcionando.

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 flow-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

El host reconoce las etiquetas de distribución npm en las herramientas:

• latest — la línea estable (predeterminado cuando no se pasa ninguna etiqueta).
• beta : vista previa de compilaciones por delante de la línea estable.
• alpha : compilaciones inestables de acceso temprano.

uip tools install flow-tool@beta
uip tools update --name flow-tool --version alpha

Los canales son a nivel de herramienta, no a nivel de host. Puedes combinar un host estable con una herramienta beta para un flujo de trabajo específico. Ten en cuenta que la combinación está menos probada.

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.