Migración: romper cambios

Cambios semánticos que rompen los procesos de formas que un puerto de bandera por bandera no detectaría. Lee esta página antes de portar; el mapa de comandos y los cambios de nombre de banderas se encargan del trabajo de cambio de nombre mecánico.

Cada cambio a continuación tiene la misma estructura: qué cambió, por qué cambió, qué hacer. Ojea las primeras líneas en negrita y profundiza en dónde se ve afectado tu proceso.

Modos de autenticación eliminados

Qué ha cambiado. El uipcli heredado aceptaba tres modos de autenticación por comando: usuario/contraseña (-u/-p), token de actualización (-t/-a) y Aplicación externa (-A/-I/-S/--applicationScope). La nueva CLI solo acepta credenciales de cliente de aplicación externa (para CI), OAuth2 interactivo (para desarrolladores) y tokens de acceso a variables de entorno (para contenedores). La autenticación de usuario/contraseña y el token de actualización han desaparecido: las letras indicadoras -u, -p, -t, -a no están asignadas (-u, -p, -a) o se han reutilizado (-t es ahora --tenant).

Por qué. Automation Cloud ha considerado obsoletos los flujos de usuario/contraseña y token de actualización para las nuevas cargas de trabajo. Las credenciales de aplicación externa son el único flujo que se escala limpiamente en los ejecutores de CI, admite la auditoría a nivel de organización y puede revocarse sin rotar una cuenta humana.

Qué hacer. Crea una aplicación externa en UiPath con los mismos ámbitos que tu proceso enumera actualmente en --applicationScope y luego reemplaza cada bloque de autenticación por comando con una sola llamada uip login :

# Legacy — auth on every command
uipcli job run "MyProcess" "https://cloud.uipath.com/" "Tenant" \
    -u "[e-mail]" -p "$PASSWORD" -o "Shared"

# uip — auth once, use many
uip login \
    --client-id env.UIPATH_CLIENT_ID \
    --client-secret env.UIPATH_CLIENT_SECRET \
    --tenant "$UIPATH_TENANT"
uip or jobs start "$PROCESS_KEY"

Consulta Autenticación para ver el catálogo de flujo completo. La sección Autenticación de Cambios de nombre de marcador enumera todos los marcadores eliminados.

Se ha eliminado la lectura de autenticación implícita de env-var

Qué ha cambiado. El uipcli heredado leía implícitamente UIPATH_CLIENT_ID y UIPATH_CLIENT_SECRET del entorno cuando los marcadores correspondientes estaban ausentes. La nueva CLI no lo hace: las variables de entorno son de solo lectura cuando se hace referencia a ellas explícitamente a través del prefijo env.VAR_NAME en --client-id / --client-secret, o a través del flujo de token de acceso UIPATH_CLI_ENABLE_ENV_AUTH=true .

Por qué. Las lecturas implícitas hacían imposible saber solo a partir de un paso del proceso de qué secretos dependía el comando. La forma explícita del prefijo env. muestra la dependencia en la propia invocación, lo que hace que la auditoría, la rotación y el escaneo de secretos sean fiables.

Qué hacer. Reemplaza cualquier dependencia implícita en las variables de entorno por referencias env. explícitas:

# Before — relied on implicit reading
UIPATH_CLIENT_ID="..." UIPATH_CLIENT_SECRET="..." uipcli job run ...

# After — explicit reference
uip login \
    --client-id env.UIPATH_CLIENT_ID \
    --client-secret env.UIPATH_CLIENT_SECRET \
    --tenant "$UIPATH_TENANT"

El formulario env. lee la variable en tiempo de ejecución sin expandirla en la línea de comandos, por lo que el secreto no aparece en el historial del shell ni en la salida ps : un patrón más seguro que la lectura implícita heredada. Consulta Autenticación: el prefijo env.VAR_NAME .

Las versiones de calendario han desaparecido

Qué ha cambiado. Las versiones heredadas se envían como versiones de calendario (2023.10, 2024.10, 2025.10) en NuGet (UiPath.CLI, UiPath.CLI.Windows), con diseños de carpeta como .../UiPath.CLI.25.10.xxxx/tools/uipcli.dll. La nueva CLI se distribuye en npm como @uipath/cli con versiones semánticas (1.0.0, 1.0.1, 1.1.0, 2.0.0).

Por qué. El control de versiones del calendario comunica la fecha de lanzamiento, pero no la compatibilidad. Semver comunica la compatibilidad: 1.0.x → 1.1.x es aditivo, 1.x → 2.x se está interrumpiendo y está precedido por un ciclo de obsolescencia. Los paquetes de host + herramientas también se coordinan en semver: las versiones de herramientas se anclan a la línea MAJOR.MINOR de CLI automáticamente.

Qué hacer. Elimina todas las referencias a paquetes NuGet con versión de calendario, rutas uipcli.dll y nombres de carpetas anuales de los procesos. Instalar con npm, anclar con @x.y.z:

# Before — Azure DevOps example
curl -L -O https://www.nuget.org/api/v2/package/UiPath.CLI.Windows/25.10.xxxx
unzip UiPath.CLI.Windows.25.10.xxxx -d ./cli
./cli/tools/uipcli.exe ...

# After
npm install -g @uipath/cli@1.0.0
uip tools install or solution tm   # pre-install tools (optional but deterministic)
uip ...

Consulta Instalar UiPath CLI y Control de versiones y estabilidad para el contrato de período completo.

Cambio de runtime: Node.js 18+ reemplaza a .NET como runtime de CLI; rpa-tool mantiene una dependencia de .NET

Qué ha cambiado. El uipcli heredado se ejecutaba completamente en .NET (UiPath.CLI requería .NET 6 multiplataforma; UiPath.CLI.Windows utilizaba .NET Framework). El nuevo host uip es un programa Node.js: cada invocación requiere Node.js 18 o posterior en el ejecutor, independientemente de las herramientas que se utilicen. El host en sí no tiene dependencia de .NET, y la mayoría de las herramientas (Orchestrator, Solution, Agent, Flow, Maestro, Test Manager, Integration Service, Data Fabric, Insights, Traces, DocsAI) solo realizan llamadas HTTPS y no añaden nada más.

La herramienta RPA (@uipath/rpa-tool, invocada como uip rpa pack / analyze / restore) es la excepción. Envuelve el empaquetador de Studio y el compilador de flujo de trabajo, ambos respaldados por .NET. Los procesos que ejecutan comandos uip rpa … necesitan un tiempo de ejecución .NET además de Node.js, no en lugar de este. Consulta la referencia de uip rpa para conocer los requisitos previos actuales.

Por qué. La CLI principal se trasladó a Node para obtener un espacio de runtime más pequeño y portátil, una distribución multiplataforma más simple y una historia de registro único (npm). La superficie específica de RPA mantuvo su backend.NET porque el empaquetador y el analizador de Studio son nativos de.NET: reescribirlos estaba fuera del alcance de 1.0.

Qué hacer.

1. Aprovisiona siempre Node.js 18+ en el ejecutor. Esto es necesario para uip en sí mismo; sin Node, no se ejecuta ningún comando uip .

   # GitHub Actions example
   - uses: actions/setup-node@v4
     with:
       node-version: '20'
   

2. Si tu proceso llama uip rpa pack, uip rpa analyze o uip rpa restore, mantén también un runtime .NET disponible en el ejecutor. Ya no instalas el uipcli heredado a través de dotnet tool install, pero el propio tiempo de ejecución .NET aún tiene que estar presente para que rpa-tool pueda invocar el empaquetador de Studio.

3. Si tu proceso no llama a uip rpa …, elimina el paso de configuración .NET/ dotnet-sdk . Las herramientas restantes (Orchestrator, Solution, Agent, Flow, Maestro, Test Manager, etc.) no lo necesitan.

Consulta Instalar UiPath CLI — CI/CD.

Contrato de código de salida más estricto

Qué ha cambiado. El uipcli heredado emitía una gama más amplia de códigos de salida, a menudo mezclando códigos de nivel de proceso .NET (1-3 dígitos, específicos del marco) con códigos de nivel de comando. El nuevo CLI emite exactamente cinco códigos canónicos (0, 1, 2, 3, 4) más 130 para la cancelación del usuario, y la asignación del resultado al código es estable dentro de una versión MAYOR .

Código de salida	Significado
0	Correcto.
1	Fallo genérico o error de configuración.
2	Error de autenticación (401/403).
3	Error de validación (marcador incorrecto, opción desconocida, marcadores mutuamente excluyentes).
4	Error de tiempo de espera. Reservado; ningún comando lo emite en 1.x.
130	El usuario canceló (Ctrl + C).

Una reutilización específica del dominio: uip tm wait devuelve 2 en el tiempo de espera (para que los scripts puedan distinguir el tiempo de espera de la ranura de autenticación). De lo contrario, el contrato es uniforme.

Por qué. Un conjunto de códigos pequeño y estable hace que la lógica de reintento/escalada de CI sea sencilla: 2 significa "volver a autenticar y luego reintentar"; 3 significa "no reintentar nunca, corregir el comando"; 1 significa "reintentar una vez si es transitorio". El amplio rango heredado requería procesos para manejar los códigos de cada comando individualmente.

Qué hacer. Reemplaza las ramas específicas del código por las nuevas cinco. Si tu proceso tiene una lógica como "reintentar en cualquier código distinto de cero", ajústala para reintentar solo en 1 :

# Before — broad retry
if ! uipcli job run ...; then sleep 30; uipcli job run ...; fi

# After — targeted branching
if ! uip or jobs start "$KEY" --wait-for-completion; then
    case $? in
        2)   uip login ...; uip or jobs start "$KEY" --wait-for-completion ;;
        3)   exit 3 ;;   # don't retry bad input
        *)   exit 1 ;;
    esac
fi

Nota: uip tm testsets run siempre sale de 0 una vez que Test Manager acepta la solicitud de ejecución. Los fallos se producen a través de uip tm wait + uip tm report get con Data.Failed, no el código de salida de run. Consulta Códigos de salida. La página uip tm wait documenta su semántica de código de salida.

La salida estándar es JSON de forma predeterminada

Qué ha cambiado. La versión heredada uipcli escribió un texto de registro legible por humanos en la salida estándar; el código de salida y cualquier archivo producido eran las únicas salidas legibles por la máquina. La nueva CLI escribe un sobre JSON en la salida estándar de forma predeterminada en cada comando:

{
  "Result": "Success",
  "Code": "JobCompleted",
  "Data": { "Key": "...", "State": "Successful", "...": "..." }
}

Los registros, el progreso y los errores de cara a humanos van a stderr, independientemente del valor --output . La vista de tabla legible por humanos está habilitada con --output table.

Por qué. La salida JSON primero significa que cada comando es programable sin trucos de análisis, y la misma invocación funciona de forma idéntica en un terminal y un proceso. Los registros en stderr significan que un proceso puede command > payload.json 2> log.txt limpiar.

Qué hacer. Cualquier paso de shell que grepped la salida de texto uipcli debe cambiar a uno de:

• --output-filter "<JMESPath>" --output plain — extraer un único campo como texto sin formato. Ejemplo: --output-filter "Data.Key" --output plain.
• jq : analiza el sobre completo.
• --output table : solo visualización; no analizar la salida de la tabla.

# Before
JOB_ID=$(uipcli job run ... | grep -oP 'JobId=\K[0-9a-f-]+')

# After
JOB_KEY=$(uip or jobs start "$KEY" \
    --output-filter "Data.Jobs[0].Key" \
    --output plain)

Consulta Formatos de salida. El propio marcador --output-filter está documentado en Opciones globales.

La URL del tenant y de Orchestrator son estados de sesión, no marcadores por comando

Qué ha cambiado. El uipcli heredado tomaba <orchestrator_url> y <orchestrator_tenant> como argumentos posicionales en cada verbo (job run "<name>" "<url>" "<tenant>" ...). La nueva CLI resuelve tanto desde la sesión autenticada escrita por uip login; nunca se necesita ninguna URL posicional, y el tenant es un valor predeterminado de sesión que cada comando puede anular con -t, --tenant <name>.

Por qué. Cada comando en un proceso normalmente se dirige al mismo Orchestrator; pasar la URL y el tenant en cada llamada era repetitivo e invitaba a errores de copiar y pegar. El estado de sesión con anulación por llamada es el patrón CLI estándar (cf. az account set, gcloud config set, kubectl config use-context).

Qué hacer. Suelta la URL posicional y el tenant de cada comando. Establece el tenant al iniciar sesión (o anula por llamada con -t):

# Before
uipcli package deploy "./pkg.nupkg" \
    "https://cloud.uipath.com/" "ProdTenant" \
    -A "org" -I "..." -S "..." -o "Shared"
uipcli job run "Process" \
    "https://cloud.uipath.com/" "ProdTenant" \
    -A "org" -I "..." -S "..." -o "Shared"

# After
uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET --tenant ProdTenant
uip or packages upload ./pkg.nupkg
uip or processes create --name Process --package-key Process --package-version 1.0.0 --folder-path Shared
uip or jobs start "$PROCESS_KEY"

Para los scripts de tenant múltiple, pasa -t TENANT en cualquier comando que necesite un tenant diferente para esa llamada. Consulta Autenticación: gestionar tenants a mitad de sesión.

Los conceptos de carpeta clásica están obsoletos en la superficie CLI

Qué ha cambiado. La CLI heredada incluía varios marcadores de solo carpeta clásica: -e, --environments <csv> en package deploy, -r, --robots <csv> en job run y enrutamiento basado en el entorno relacionado. La nueva CLI se dirige al modelo de carpeta moderno exclusivamente en sus verbos públicos. Las carpetas clásicas siguen existiendo en Orchestrator, pero uip no expone marcadores específicos de clásicas.

Por qué. Las carpetas modernas han sido las predeterminadas desde 2020. Mantener los marcadores solo clásicos en la nueva CLI habría significado llevar el comportamiento obsoleto a una nueva versión.

Qué hacer. Si tu proceso se dirige a una carpeta clásica, (a) migra la carpeta a moderna (superficie de administración de Orchestrator), o (b) sigue usando uipcli para esas llamadas específicas a través del contenedor @uipath/rpa-legacy-tool . Consulta uip rpa: contenedor heredado solo para Windows.

Marca de idioma/configuración regional eliminada

Qué ha cambiado. La salida de registro heredada -l, --language <locale> traducida a la configuración regional dada. La nueva CLI emite registros solo en inglés.

Por qué. Los mensajes de registro están destinados a ser consumidos por los operadores y los sistemas de envío de registros, los cuales están estandarizados en inglés. La localización suponía un coste sin una compensación clara para la capa CLI.

Qué hacer. Elimine los marcadores -l / --language del proceso. No se necesita reemplazo.

Capturar y reproducir (--captureCommandToJsonFile + uipcli run) eliminado

Qué ha cambiado. El legado tenía un marcador --captureCommandToJsonFile <path> oculto que serializaba la invocación actual a JSON, y un verbo uipcli run <file> que consumía ese JSON para reproducir el comando. Ambos se eliminan.

Por qué. El patrón se utilizó principalmente para depurar cómo la tarea de GUI en Azure DevOps se asignaba a los marcadores CLI, no como un mecanismo de producción. El nuevo JSON-stdout predeterminado de CLI y el filtrado JMESPath cubren el caso de uso de depuración sin un subsistema independiente.

Qué hacer. Reescribe cualquier paso del proceso que utilizara uipcli run <file> como una invocación directa uip . Si dependías de --captureCommandToJsonFile para la depuración, el nuevo equivalente es uip <command> --log-level debug --log-file ./uip.log : el archivo de registro contiene cada llamada HTTP, actualización de autenticación y carga de herramientas.

Se ha cambiado el nombre de la variable de entorno de exclusión de telemetría

Qué ha cambiado. Ambas generaciones se envían con la opción de exclusión de telemetría anónima de forma predeterminada : la telemetría está activada a menos que la deshabilites explícitamente. El nombre de la variable de entorno ha cambiado:

Generación	Variable	Valor para deshabilitar
Legado uipcli	UIPATH_EXTENSIONS_CLI_TELEMETRY_ENABLED	False
Nuevo uip	UIPATH_TELEMETRY_DISABLED	1 o true

Por qué. El nuevo nombre es más corto, sigue el patrón <SCOPE>_DISABLED utilizado en otras partes de la CLI y elimina el prefijo EXTENSIONS_ (la nueva CLI no es una extensión de nada).

Qué hacer. Actualice los ejecutores de CI y las máquinas de desarrollo que ya están configurados UIPATH_EXTENSIONS_CLI_TELEMETRY_ENABLED=False para establecer en su lugar UIPATH_TELEMETRY_DISABLED=1. La nueva CLI ignora la variable heredada, por lo que una máquina que establece solo el nombre antiguo enviará telemetría de nuevo hasta que se añada la nueva. Consulta Novedades: otros cambios significativos.

Ver también

• Mapa de comandos : qué verbo llamar.
• Cambios de nombre de bandera : asignación de bandera por bandera.
• Ejemplos de proceso : antes/después de YAML para las plataformas de CI comunes.
• Códigos de salida : el contrato de cinco niveles.
• Novedades : resumen positivo de cada reescritura destacada.