Contrôle des versions et stabilité

Contrat de contrôle de version sémantique pour la UiPath CLI, couvrant les modifications apportées à MAJOR, administrateur minimum et PATCH, ainsi que la matrice de compatibilité hôte/outil.

La UiPath CLI suit le contrôle de version sémantique (MAJOR.MINOR.PATCH), pour atteindre la disponibilité générale à la version 1.197.0. Cela remplace le schéma basé sur le calendrier (2023.10, 2024.10, 2025.10) utilisé par la CLI.NET héritée. Cette page constitue le contrat - ce sur quoi vous pouvez vous appuyer d’une version à l’autre, ce qui peut changer et comment les versions de l’hôte et de l’outil restent à l’étape.

Ce que signifie le serveur dans la pratique

Champ	Quand cela se produit	Éléments modifiables
MAJOr (1.x.x → 2.0.0)	Modifications radicales des noms de commande, de la sémantique des indicateurs ou de l'enveloppe JSON.	Les commandes peuvent être renommées ou supprimées; les indicateurs peuvent être renommés ou voir leur signification modifiée; les champs de niveau supérieur de l'enveloppe peuvent changer de forme. Un cycle d'obsolescence complet précède toute version MAJOR — les commandes obsolètes continuent de fonctionner dans la INFÉRIEUR dernière de la version MAJOR précédente.
Mineur (1.0.x → 1.1.0)	Nouvelles commandes, nouveaux outils, nouveaux indicateurs, nouvelles sous-commandes.	Additif uniquement sur l'interface de commande. Cependant, la forme de Data à l’intérieur de l’enveloppe JSON est spécifique à la commande et peut changer — de nouveaux champs ont été ajoutés, parfois des champs renommés ou imbriqués. Les scripts qui analysent des noms de champs spécifiques doivent être revalidés lors d'un bogue mineur.
PATCH (1.0.0 → 1.0.1)	Corrections de bogues.	Aucun changement de comportement documenté. Un correctif qui modifie le comportement est traité comme un rapport de bogue relatif au correctif lui-même.

Il n'y a pas d'indicateur --preview (contrairement à Azure CLI). Les commandes de statut d'aperçu sont libellées sur leur page de référence et peuvent changer dans une version mineure sans avertissement - voir Stabilité par commande ci-dessous.

Le contrat stable

Les éléments suivants ne changent pas entre les versions mineures ou PATCH. Écrivez librement un script contre eux.

Champs de l'enveloppe

Chaque commande va générer une enveloppe sur stdout avec ces champs de niveau supérieur:

Champ	Stabilité	Signification
Result	Stable	Success, Failure, ConfigError, AuthenticationError, ValidationError, TimeoutError
Code	Stable dans MAJOR	Identificateur de réussite spécifique à la commande (FolderList, SolutionPack, etc.). De nouveaux codes peuvent apparaître dans les versions mineures pour les nouvelles commandes.
Data	Spécifique à la commande	Format de charge utile défini par chaque commande. Peut ajouter des champs dans les versions mineures. Rarement, les champs peuvent être renommés dans mineur - vérifiez les notes de version.
Message, Instructions	Stable	Texte d'erreur lisible par un humain. Le contenu peut être amélioré d’une version à l’autre; la présence et le rôle ne changent pas.
Context, Log	Stable	Champs facultatifs. Les conditions de présence sont stables.

Voir la section Formats de sortie de l'enveloppe en détail.

Codes de sortie

Le contrat de code de sortie à cinq niveaux (0 / 1 / 2 / 3 / 4 plus 130 pour l'annulation de l'utilisateur) est stable dans une version majeure. 4 est émis aujourd'hui uniquement par uip tm perf-scenario execute --wait lors du délai d'expiration; des commandes plus longue durée peuvent l'adopter, donc gérez-la comme un "timeout".

Options globales

--output, --output-filter, --log-level, --log-file — ces quatre indicateurs sont stables sur les augmentations mineures. De nouvelles options globales peuvent être ajoutées; ceux existants ne seront pas renommés ou supprimés sans publication majeure.

Séparation stdout/stderr

Stdout est l'enveloppe. stderr correspond aux journaux, à la progression et au texte d'erreur présenté à un humain. Cette séparation s'applique à chaque commande, à chaque format et à chaque version.

Versions de l’hôte et de l’outil

L'hôte (@uipath/cli, l'exécutable uip ) et chaque outil (par exemple, @uipath/orchestrator-tool) sont publiés sous forme de packages npm indépendants, chacun avec son propre serveur. Ils sont coordonnés de sorte qu'un hôte au niveau de la version 1.0.x exécute les outils au niveau de 1.0.x.

Résolution de la version par défaut

Lorsque vous exécutez uip tools install <alias> sans version explicite, l’hôte sélectionne la dernière version de l’outil dont MAJOR.MINIOR correspond à la ligne MAJOR.MINOR actuelle de la CLI. La mise à niveau de la CLI de 1.0.x vers 1.1.0 , puis l'exécution de uip tools update place chaque outil installé dans la ligne 1.1.x .

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

Vous pouvez remplacer la valeur par défaut d’un outil spécifique:

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

Importance de l’épinglage

Les outils communiquent avec l’hôte via un contrat TypeScript avec version (enregistrement de la commande, formatage de sortie, télémétrie, contexte). Si le contrat change entre les versions mineures, l’hôte et l’outil doivent être déplacés ensemble. L'option par défaut d'épinglage des versions garantit qu'ils le font, sans que l'utilisateur ait à y réfléchir.

Canaux de mise à jour

La version de l'hôte et de ses outils est régie par un canal — un paramètre au niveau de l'hôte CLI, et non une balise npm par outil transmise à la commande d'installation. Trois canaux existent: stable (par défaut), preview et un dev masqué. Définissez-le avec 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

Chaque canal correspond à un dist-tag npm:

Canal	Publié depuis	Registre	Dist-balise
stable	Date d'exécution manuelle release/*	npmjs	latest (ou previous pour un renvoi inférieur à latest)
preview	Transmettre à release/*	npmjs, mis en miroir avec les packages GitHub	preview
dev	Transmettre à main	Packages GitHub uniquement	dev

dev est accepté (uip config set updateChannel dev) mais délibérément omis de --help et de « valeurs valides » — il existe afin qu’une CLI -dev.* résolve les outils sur sa propre ligne, et non en tant que canal dans lequel opter.

L'épinglage d'une version préliminaire exacte fonctionne toujours pour une résolution unique (uip tools install maestro-tool@1.0.0-preview.1), mais updateChannel est ce qui régit la résolution continue — un uip tools update non épinglé ou une installation automatique se résout toujours par rapport au canal, pas une balise que vous transmis une fois. Voir uip config pour la référence complète de la clé updateChannel/version .

Mises à jour automatiques

Si elle est laissée seule, uip se maintient à jour — cela se produit par défaut sans option d'inscription.

La synchronisation CLI quotidienne

Une fois par jour, la première commande éligible vérifie une version de CLI plus récente sur le canal résolu, l'installe, actualise les compétences et réexécute votre commande d'origine sur la nouvelle version , de manière transparente, à mi-invocation. Il écrit uniquement dans stderr (un compteur sur les terminaux interactifs) et ne modifie jamais le code de sortie de votre commande. Une uip update manuelle n'est jamais limitée par cette passerelle quotidienne.

Il ne franchit jamais une version MAJOR Unattended. Sans épingle de version, la synchronisation quotidienne se limite à la valeur MAJOR qu'elle est déjà en cours d'exécution - la publication de 2.0.0 vers latest ne met pas à niveau silencieusement une installation 1.x pendant la nuit. Elle annonce la nouvelle version qu'elle a refusée afin que vous puissiez l'accepter délibérément:

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

La synchronisation ignore automatiquement certains contextes (authentification env-var updateloginlogoutmcpcompletionconfigd’Envskills/help verbes, /, une épingle--version--help core.version exacte) et peut être entièrement désactivé avec:

export UIPATH_CLI_DISABLE_VERSION_SYNC=true

L’état est suivi dans ~/.uipath/version-sync.json; uip login n'y touche jamais.

La vérification quotidienne par outil

Séparément, la première fois qu'un verbe d'outil s'exécute chaque jour, la CLI effectue une recherche dans le registre pour cet outil sur la ligne major.minor de la CLI en cours d'exécution et installe la version correspondante la plus récente avant le chargement de l'outil — aucune réexécution, car les outils se chargent par lasiquement dans le même processus. Cette vérification échoue: si la recherche ou l’installation échoue, la commande ne s’exécute pas du tout (un résultat Failure vous demande de vérifier la connectivité et de réessayer) plutôt que de risquer d’exécuter un outil obsolète. UIPATH_CLI_DISABLE_VERSION_SYNC et UIPATH_CLI_DISABLE_AUTOINSTALL ignorent tous deux cette vérification; il en va de même pour une épingle core.version exacte.

Stabilité par commande

Les commandes et les indicateurs individuels comportent l'un des trois libellés de stabilité. Recherchez-les en haut de la page de référence de chaque commande.

Label	Signification
Disponibilité générale (par défaut; sans libellé)	La commande est couverte par le contrat du serveur ci-dessus. Il ne sera pas renommé ou supprimé dans une version MAJOR.
Aperçu	La commande est en développement actif. Les indicateurs, les valeurs par défaut et la forme de sortie peuvent changer sans augmentation majeure, bien que les changements radicaux soient rares et annoncés dans les notes de publication. Utilisez-les en production uniquement lorsque vous êtes prêt à valider à nouveau pour chaque version.
Obsolète	La suppression de la commande est prévue dans la prochaine version MAJOR. Il continue de fonctionner dans la version 1.x et génère un avertissement lors de l'exécution. Utilisez le successeur répertorié dans la note d’obsolescence.

Il s’agit de la même convention qu’utilise GCloud. La UiPath CLI ne gère pas les commandes d'aperçu derrière un indicateur d'inscription - elles sont visibles dans --help et appelables.

Épinglage des recommandations

Pour les pipelines 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

Cela vous donne un environnement reproductible qui survit aux versions en amont. Validez à nouveau après chaque saut de CLI à l'aide des tests d'intégration de votre pipeline; consultez les notes de publication pour connaître les modifications apportées au Dataprofil -forme.

Pour les stations de travail développeur:

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

Moins reproductible, plus pratique.

Cycle d’obsolescence

Lorsqu'une commande ou un indicateur s'efface, le chemin d'accès est:

1. Obsolescence annoncée : la commande est marquée Deprecated dans sa page de référence, et les notes de version de la version mineure qui a introduit l'obsolescence la listent. Un remplacement est documenté.
2. Avertissement de runtime — uip <deprecated-command> ... continue de fonctionner mais envoie un avertissement sur stderr. Les scripts qui utilisent stdout ne sont pas affectés.
3. Suppression dans la version MAJOR suivante — la commande est supprimée au prochain saut de version MAJOR. Il y a au moins un cycle MAJOR complet entre l'obsolescence et la suppression, suffisamment long pour effectuer la migration de tout pipeline du cycle de vie pris en charge.

Exécutez uip <command> --help pour voir si une commande est obsolète; le libellé apparaît dans la synthèse.

Lorsque la forme des données change

Étant donné que Data est spécifique à la commande et peut changer dans les versions mineures, les pipelines qui extraient des champs spécifiques (--output-filter "Data.Jobs[0].Key") sont les plus exposés à l'affectation mineure. Deux atténuations:

• Épinglez @uipath/cli dans CI (voir ci-dessus). Vous choisissez quand valider les nouvelles formes.
• Requête défensive : préférez les expressions JMESPath qui tolèrent les champs manquants (Data.Jobs[0].Key || '') lorsque vous le pouvez; Consultez les notes de publication avant la mise à niveau.

Les changements de forme Data dans mineur sont rares et signalés dans les notes de publication comme [Data shape] sous la commande modifié(e).

Où surveiller les modifications

• Notes de publication — Résumé par version des commandes ajoutées, des indicateurs modifiés et des changements de forme.
• uip --version et uip tools list — ce qui est actuellement installé sur une machine. Comparez entre les environnements pour capturer la dérive.
• Le package de chaque outil sur npm — les éditeurs répertorient les dist-balises et l'historique des versions.

Voir également

• Formats de sortie — la forme de l'enveloppe décrite dans le contrat.
• Codes de sortie — le contrat à cinq niveaux.
• Outils (extensions) : le modèle d'outil hôte que l'épinglage de version prend en charge.
• Notes de publication — ce qui a changé et quand.
• Migration depuis la version CLI.NET héritée — si vous venez de 2025.10 ou d'une version antérieure.