Migration: changements radicaux

Modifications sémantiques qui interrompent les pipelines d'une manière qu'un port indicateur pour indicateur ne détecterait pas. Lisez cette page avant de procéder au port; la carte de commande et les changements de nom d'indicateur gèrent le travail de changement de nom mécanisme.

Chaque modification ci-dessous a la même structure: ce qui a changé, pourquoi il a changé, que faire. Ignorez les premières lignes en gras et indiquez l'endroit où votre pipeline est affecté.

Modes d’authentification supprimés

Ce qui a changé. L'héritage uipcli acceptait trois modes d'authentification par commande: utilisateur/mot de passe (-u/-p), actualiser le jeton (-t/-a) et Application externe (-A/-I/-S/--applicationScope). La nouvelle CLI accepte uniquement les informations d’identification du client de l’application externe (pour CI), interactive OAuth2 (pour les développeurs) et les jetons d’accès variables pour l’environnement (pour les conteneurs). L'authentification par utilisateur/mot de passe et jeton d'actualisation a disparu - les lettres d'indicateur -u, -p, -t, -a sont soit non affectées (-u, -p, -a) ou réaffectées (-t est maintenant --tenant).

Pourquoi. Automation Cloud a rendu obsolète les flux d'utilisateur/mot de passe et de jeton d'actualisation pour les nouvelles charges de travail. Les informations d’identification d’application externe sont le seul flux qui s’adapte correctement entre les exécuteurs CI, prennent en charge l’audit au niveau de l’organisation et peuvent être révoqués sans rotation d’un compte humain.

Que faire. Créez une application externe dans UiPath avec les mêmes étendues que votre pipeline répertorie actuellement sous --applicationScope, puis remplacez chaque bloc d'authentification par commande par un seul appel 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"

Voir Authentification pour le catalogue complet de flux. La section Authentification de Changement du nom de l'indicateur répertorie chaque indicateur supprimé.

Lecture d’authentification implicite env-var supprimée

Ce qui a changé. L'héritage uipcli lisait implicitement UIPATH_CLIENT_ID et UIPATH_CLIENT_SECRET dans l'environnement lorsque les indicateurs correspondants étaient absents. La nouvelle CLI ne fonctionne pas — les variables d'environnement ne sont en lecture que lorsque vous les référencez explicitement via le préfixe env.VAR_NAME sur --client-id / --client-secret ou via le flux de jeton d'accès UIPATH_CLI_ENABLE_ENV_AUTH=true .

Pourquoi. Les lectures implicites rendaient impossible de le savoir à partir d'une étape de pipeline unique secrète dont dépendait la commande. Le préfixe env. explicite fait apparaître la dépendance dans l’invocation elle-même, ce qui rend l’audit, la rotation et l’analyse du secret fiables.

Que faire. Remplacez tout recours implicite aux variables d'environnement par des références env. explicites:

# 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"

Le formulaire env. lit la variable au moment de l'exécution sans la développer dans la ligne de commande, de sorte que le secret n'apparaît pas dans l'historique du shell ou la sortie ps — un modèle plus sûr que la lecture implicite héritée. Voir Authentification — le préfixe env.VAR_NAME .

Les versions basées sur le calendrier sont terminées

Ce qui a changé. Héritage est livré sous forme de versions de calendrier (2023.10, 2024.10, 2025.10) sur NuGet (UiPath.CLI, UiPath.CLI.Windows), avec des mises en page de dossier comme .../UiPath.CLI.25.10.xxxx/tools/uipcli.dll. La nouvelle CLI est distribuée sur npm en tant que @uipath/cli avec un contrôle de version sémantique (1.0.0, 1.0.1, 1.1.0, 2.0.0).

Pourquoi. La gestion des versions du calendrier communique la date de publication, mais pas la compatibilité. Samver communique la compatibilité: 1.0.x → 1.1.x se cumule, 1.x → 2.x se déclenche et est précédé d'un cycle d'obsolescence. Les packages d'hôte + d'outil se coordonnent également sur le serveur - les versions d'outil s'épinglent automatiquement à la ligne MAJOR.MINOR de la CLI.

Que faire. Supprimez chaque référence aux packages NuGet versionnés par calendrier, aux chemins uipcli.dll et aux noms de dossier annuels des pipelines. Installer avec npm, épingler avec @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 ...

Voir Installation de la UiPath CLI et Contrôle des versions et stabilité pour le contrat du serveur complet.

Modification du runtime: Node.js 18+ remplace .NET comme runtime de la CLI; rpa-tool conserve une dépendance.NET

Ce qui a changé. L'héritage uipcli s'exécutait entièrement sur.NET (UiPath.CLI a requis une multiplate-forme .NET 6; UiPath.CLI.Windows a utilisé .NET Framework). Le nouvel hôte uip est un programme Node.js — chaque invocation nécessite Node.js 18 ou une version ultérieure sur le runtime, quels que soient les outils utilisés. L’hôte lui-même n’a pas de dépendance.NET et la plupart des outils (Orchestrator, Solution, Agent, Flow, Maestro, Test Manager, Integration Service, Data Fabric, Insights, Traces, DocsAI) effectuent uniquement des appels HTTPS et n’ajoutent rien d’autre.

L’ outil RPA (@uipath/rpa-tool, invoqué en tant que uip rpa pack / analyze / restore) est l’exception. Il encapsule le packeur Studio et le compilateur de workflow, qui sont tous deux pris en charge par.NET. Les pipelines qui exécutent les commandes uip rpa … ont besoin d'un runtime.NET en plus de Node.js, et non à la place. Voir la référence uip rpa pour connaître les conditions préalables actuelles.

Pourquoi. La CLI principale a été déplacée vers Node pour une empreinte de runtime plus petite et plus portable, une distribution multiplateforme plus simple et une conversation sur le registre unique. L'interface spécifique à la RPA a conservé son backend .NET, car le packeur et l'analyseur Studio sont des fichiers .NET natifs; leur réécriture était hors du cadre de la version 1.0.

Que faire.

1. Enregistrez toujours Node.js 18+ sur le runtime. Cela est nécessaire pour uip lui-même; sans nœud, aucune exécution de commande uip .

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

2. Si votre pipeline appelle uip rpa pack, uip rpa analyze ou uip rpa restore, conservez également un runtime.NET disponible sur le runtime. Vous n’installez plus l’ancien uipcli via dotnet tool install, mais le runtime.NET lui-même doit toujours être présent afin que rpa-tool puisse invoquer le package Studio.

3. Si votre pipeline n'appelle pas uip rpa …, supprimez l'étape de configuration.NET/ dotnet-sdk . Les outils restants (Orchestrator, Solution, Agent, Flow, Maestro, Test Manager, etc.) n'en ont pas besoin.

Voir Installation de la UiPath CLI — CI/CD.

Contrat de code de sortie renforcée

Ce qui a changé. L'héritage uipcli a émis une plus large gamme de codes de sortie, combinant souvent des codes de niveau de processus.NET (1-3 chiffres, spécifiques à l'infrastructure) avec des codes de niveau de commande. La nouvelle CLI génère exactement cinq codes canoniques (0, 1, 2, 3, 4) plus 130 pour l'annulation de l'utilisateur, et le mappage du résultat au code est stable dans une version MAJOR .

Code de sortie	Signification
0	Réussite.
1	Échec générique ou erreur de configuration.
2	Erreur d’authentification (401/403).
3	Erreur de validation (indicateur incorrect, option inconnue, indicateurs mutuellement exclusifs).
4	Erreur de délai d’expiration. Réservé; aucune commande ne l'émet dans 1.x.
130	Utilisateur annulé.

Une réutilisation spécifique au domaine: uip tm wait renvoie 2 au délai d'attente (les scripts peuvent donc distinguer le délai d'attente de l'emplacement d'authentification). Sinon, le contrat est uniforme.

Pourquoi. Un petit ensemble stable de codes simplifie la logique de nouvelle tentative/d'escalade du CI: 2 signifie « réauthentifier, puis réessayer»; 3 signifie « ne réessayez jamais, corrigez la commande»; 1 signifie « réessayer une fois si temporaire». La vaste plage héritée nécessitait que les pipelines gèrent les codes de chaque commande individuellement.

Que faire. Remplacez les branches spécifiques au code par les cinq nouvelles. Si votre pipeline a une logique comme « Réessayer sur n'importe quel code non nul», renforcez-le pour réessayer sur 1 uniquement:

# 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

Remarque: uip tm testsets run quitte toujours 0 une fois que Test Manager a accepté la requête d'exécution. Les échecs passent par uip tm wait + uip tm report get avec Data.Failed, et non le code de sortie de run. Voir Codes de sortie. La page uip tm wait documente la sémantique de son code de sortie.

Stdout est JSON par défaut

Ce qui a changé. L'héritage uipcli a écrit le texte du journal lisible par un humain dans stdout; et tous les fichiers produits étaient les seules sorties lisibles par machine. La nouvelle CLI écrit une enveloppe JSON dans stdout par défaut pour chaque commande:

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

Les journaux, la progression et les erreurs liées à un humain sont transmis à stderr, quelle que soit la valeur --output . La vue de la table lisible par un humain est activée en option avec --output table

Pourquoi. La sortie JSON-first signifie que chaque commande est scriptable sans astuces d'analyse, et que la même invocation fonctionne de manière identique dans un terminal et un pipeline. La journalisation stderr signifie qu’un pipeline peut correctement command > payload.json 2> log.txt.

Que faire. Toute étape du shell qui a saisi la sortie de uipcli texte doit basculer vers l'une des éléments suivants:

• --output-filter "<JMESPath>" --output plain — extraire un seul champ sous forme de texte brut. Exemple: --output-filter "Data.Key" --output plain.
• jq — analyser l'enveloppe complète.
• --output table — lecture seule; n'analysez pas la sortie de la table.

# 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)

Voir Formats de sortie. L'indicateur --output-filter lui-même est documenté dans les options globales.

Le locataire et les URL Orchestrator sont des états de session, et non des indicateurs par commande

Ce qui a changé. L'héritage uipcli prenait <orchestrator_url> et <orchestrator_tenant> comme arguments positionnels sur chaque verbe (job run "<name>" "<url>" "<tenant>" ...). La nouvelle CLI résout les deux à partir de la session authentifiée écrite par uip login; aucune URL positionnelle n'est jamais nécessaire, et le locataire est une session par défaut que chaque commande peut remplacer par -t, --tenant <name>

Pourquoi. Chaque commande d'un pipeline cible généralement le même Orchestrator; la transmission de l'URL et du locataire à chaque appel était une erreur de copier-coller répétitive et invitée. L'état de la session avec remplacement par appel est le modèle CLI standard (voir az account set, gcloud config set, kubectl config use-context).

Que faire. Déposez l'URL positionnelle et le locataire de chaque commande. Définissez le locataire à la connexion (ou remplacez-le par appel avec -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"

Pour les scripts multi-locataires, transmettez -t TENANT n'importe quelle commande qui a besoin d'un locataire différent pour cet appel. Voir Authentification — gérer les locataires à la mi-session.

Les concepts de dossier classique sont obsolètes sur l'interface CLI

Ce qui a changé. La CLI héritée transportait plusieurs indicateurs classiques uniquement: -e, --environments <csv> sur package deploy, -r, --robots <csv> sur job run et le routage basé sur l'environnement. La nouvelle CLI cible le modèle de dossier moderne exclusivement sur ses verbes publics. Les dossiers classiques existent toujours sur Orchestrator, mais uip n'expose pas des indicateurs spécifiques au classique.

Pourquoi. Les dossiers modernes sont définis par défaut depuis 2020. Conserver les indicateurs classiques uniquement sur la nouvelle CLI impliquerait le report d’un comportement obsolète dans une nouvelle version.

Que faire. Si votre pipeline cible un dossier classique, soit (a) migrez le dossier vers moderne (interface d'administration Orchestrator), soit (b) continuez à utiliser uipcli pour ces appels spécifiques via le wrapper @uipath/rpa-legacy-tool . Voir uip rpa — Le wrapper hérité Windows uniquement.

Indicateur de langue/locale supprimé

Ce qui a changé. L'héritage -l, --language <locale> a traduit la sortie du journal dans la région donnée. La nouvelle CLI génère des journaux en anglais uniquement.

Pourquoi. Les messages de journal sont destinés à être consommés par les opérateurs et les systèmes de livraison de journaux, qui sont tous deux standardisés en anglais. La localisation était un coût sans rémunération clair pour la couche CLI.

Que faire. Supprimez les indicateurs -l / --language du pipeline. Aucun remplacement n'est nécessaire.

Capture-et-replay (--captureCommandToJsonFile + uipcli run) supprimé

Ce qui a changé. L'héritage avait un indicateur --captureCommandToJsonFile <path> masqué qui sérialisait l'invocation actuelle en JSON et un verbe uipcli run <file> qui utilisait ce JSON pour lire la commande. Les deux sont supprimés.

Pourquoi. Le modèle était principalement utilisé pour déboguer la façon dont la tâche GUI dans Azure DevOps était mappée aux indicateurs CLI, et non en tant que mécanisme de production. Le nouveau filtrage par défaut JSON-stdout et JMESPath de la CLI couvre l’utilisation de débogage sans sous-système distinct.

Que faire. Réécrivez toute étape de pipeline qui utilisait uipcli run <file> comme invocation directe uip . Si vous dépendiez de --captureCommandToJsonFile pour le débogage, le nouvel équivalent est uip <command> --log-level debug --log-file ./uip.log — le fichier journal contient chaque appel HTTP, actualisation d'authentification et chargement d'outil.

Variable d'environnement de désactivation de la télémétrie renommée

Ce qui a changé. Les deux versions sont livrées avec une désactivation anonyme de la télémétrie par défaut - la télémétrie est activée à moins que vous ne la désactiviez explicitement. Le nom de la variable env var a changé:

Génération	Variable	Valeur à désactiver
Héritage uipcli	UIPATH_EXTENSIONS_CLI_TELEMETRY_ENABLED	False
Nouveau uip	UIPATH_TELEMETRY_DISABLED	1 ou true

Pourquoi. Le nouveau nom est plus court, suit le modèle <SCOPE>_DISABLED utilisé ailleurs dans la CLI et supprime le préfixe EXTENSIONS_ (la nouvelle CLI n'est pas une extension de quoi que ce soit).

Que faire. Mettez à jour les exécuteurs CI et les machines de développement qui ont déjà défini UIPATH_EXTENSIONS_CLI_TELEMETRY_ENABLED=False sur au lieu de définir UIPATH_TELEMETRY_DISABLED=1. La variable héritée est ignorée par la nouvelle CLI, de sorte qu’une machine qui définit uniquement l’ancien nom enverra à nouveau la télémétrie jusqu’à ce que le nouveau soit ajouté. Consultez Nouveautés — Autres changements significatifs.

Voir également

• Carte de commande — quel verbe appeler.
• Renommage de l'indicateur — Mappage indicateur par indicateur.
• Exemples de pipeline — avant/après YAML pour les plates-formes CI courantes.
• Codes de sortie — le contrat à cinq niveaux.
• Nouveautés — résumé positif de chaque surbrillance de réécriture.