Versionierung und Stabilität

Vertrag zur semantischen Versionierung für UiPath CLI, der die Änderungen bei MaJOR, MinOR und PATCH und der Host-/Tool-Kompatibilitätsmatrix abdeckt.

UiPath CLI folgt der semantischen Versionierung (MAJOR.MINOR.PATCH) und erreicht die allgemeine Verfügbarkeit in Version 1.197.0. Dies ersetzt das kalenderbasierte Schema (2023.10, 2024.10, 2025.10), das von der Legacy-.NET-CLI verwendet wird. Diese Seite ist der Vertrag – worauf Sie sich von einer Version zur nächsten verlassen können, was sich ändern kann und wie Host- und Toolversionen im Gleichschritt bleiben.

Was Sever in der Praxis bedeutet

Alarm	Wenn es passiert	Was sich ändern kann
MAIN (1.x.x → 2.0.0)	Durchschlagende Änderungen an Befehlsnamen, Flag-Semantik oder dem JSON-Umschlag.	Befehle können umbenannt oder entfernt werden; Flags können umbenannt oder ihre Bedeutung geändert werden; Die Felder der obersten Ebene des Umschlags können ihre Form ändern. Ein vollständiger Einstellungszyklus geht jeder MaJOR-Version voraus – veraltete Befehle funktionieren weiterhin im letzten Minor des vorherigen MaJOR.
HINWEIS (1.0.x → 1.1.0)	Neue Befehle, neue Tools, neue Flags, neue Unterbefehle.	Addition nur auf der Befehlsoberfläche. Die Form von Data innerhalb des JSON-Umschlags ist jedoch befehlsspezifisch und kann sich ändern – neue Felder hinzugefügt, gelegentlich Felder umbenannt oder verschachtelt. Skripte, die bestimmte Feldnamen analysieren, sollten bei einer geringfügigen Erhöhung erneut validiert werden.
PATCH (1.0.0 → 1.0.1)	Fehlerbehebungen.	Keine dokumentierte Verhaltensänderung. Ein Patch, der das Verhalten ändert, wird als Fehlerbericht auf dem Patch selbst behandelt.

Es gibt kein --preview -Flag (im Gegensatz zu Azure CLI). Befehle mit Vorschaustatus sind auf ihrer Referenzseite gekennzeichnet und können sich innerhalb einer festgelegten Version ohne Warnung ändern – siehe Stabilität pro Befehl weiter unten.

Der stabile Vertrag

Die folgenden Änderungen ändern sich nicht zwischen Minor- und PATCH-Versionen. Skripten Sie frei gegen sie.

Umschlagsfelder

Jeder Befehl gibt bei der Standardausgabe einen Umschlag mit diesen Feldern auf höchster Ebene aus:

Feld	Stabilität	Bedeutung
Result	Stabil	Success, Failure, ConfigError, AuthenticationError, ValidationError, TimeoutError.
Code	Stabil innerhalb von MaJOR	Befehlsspezifischer Erfolgsbezeichner (FolderList, SolutionPack usw.). Neue Codes können in MINOR-Versionen für neue Befehle angezeigt werden.
Data	Befehlsspezifisch	Nutzlastform, die durch jeden Befehl definiert wird. Kann Felder in Machineschrift-Releases hinzufügen. In seltenen Fällen können Felder in Machine Learning Minor umbenannt werden – Versionshinweise ansehen.
Message, Instructions	Stabil	Für Menschen lesbarer Fehlertext. Der Inhalt kann von Version zu Version verbessert werden; Anwesenheit und Rolle ändern sich nicht.
Context, Log	Stabil	Optionale Felder. Anwesenheitsbedingungen sind stabil.

Weitere Informationen finden Sie unter Ausgabeformate für den Umschlag.

Exitcodes

Der fünfstufige Exitcode-Vertrag (0 / 1 / 2 / 3 / 4 plus 130 für die Kündigung durch den Benutzer) ist innerhalb einer MaJOR-Version stabil. 4 wird heute nur von uip tm perf-scenario execute --wait bei einer Timeout ausgegeben; Befehle mit langer Ausführungszeit können dies übernehmen, also behandeln Sie es als „Timeout“.

Globale Optionen

--output, --output-filter, --log-level, --log-file – diese vier Flags sind über hat auch mehrereErgebnisse stabil. Es können neue globale Optionen hinzugefügt werden; Vorhandene werden ohne eine MaJOR-Version nicht umbenannt oder entfernt.

„Stdout/stderr“-Trennung

Stdout ist der Umschlag; „stderr“ besteht aus Protokollen, Fortschritten und menschlichem Fehlertext. Diese Trennung gilt für jeden Befehl, jedes Format, jedes Release.

Host- und Toolversionen

Der Host (@uipath/cli, die ausführbare Datei uip ) und jedes Tool (z. B. @uipath/orchestrator-tool) werden als unabhängige npm-Pakete mit jeweils einem eigenen Server veröffentlicht. Sie sind so koordiniert, dass ein Host unter Version 1.0.x Tools unter 1.0.x ausführt.

Standardversionsauflösung

Wenn Sie uip tools install <alias> ohne eine explizite Version ausführen, wählt der Host die neueste Toolversion aus, deren MaJOR.MINOR mit der aktuellen MaJOR.MINOR-Zeile der CLI übereinstimmt. Wenn Sie die CLI von 1.0.x auf 1.1.0 aktualisieren und dann uip tools update ausführen, wird jedes installierte Tool in die Zeile 1.1.x gebracht.

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

Sie können den Standardwert für ein bestimmtes Tool überschreiben:

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

Warum das Anheften wichtig ist

Tools kommunizieren mit dem Host über einen versionierten TypeScript-Vertrag (Befehlsregistrierung, Ausgabeformatierung, Telemetrie, Kontext). Wenn sich der Vertrag zwischen MINI-Versionen ändert, müssen der Host und das Tool zusammen verschoben werden. Die Standardeinstellung zum Anheften von Versionen garantiert dies, ohne dass der Benutzer darüber denken muss.

Update-Kanäle

In welchen Build der Host und seine Tools aufgelöst werden, wird durch einen Kanal gesteuert – eine Einstellung auf CLI-Hostebene und nicht durch ein npm-Tag pro Tool, das beim Installationsbefehl übergeben wird. Es gibt drei Kanäle: stable (Standard), preview und einen ausgeblendeten dev. Legen Sie es mit uip config fest:

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

Jeder Kanal ist einem echten npm-Dist-Tag zugeordnet:

Kanal	Veröffentlicht aus	Registrierung	Dis-Tag
stable	Manuelle Release-Ausführung auf release/*	npmjs	latest (oder previous für einen Backport unter latest)
preview	Pushen an release/*	npmjs, gespiegelt in GitHub-Paketen	preview
dev	Pushen an main	Nur GitHub-Pakete	dev

dev wird akzeptiert (uip config set updateChannel dev), wird aber absichtlich aus --help und „gültigen Werten“ herausgelassen listes – es ist vorhanden, sodass eine -dev.* -CLI Tools auf einer eigenen Zeile auflöst, nicht als Kanal, für den Sie sich anmelden müssen.

Das Anheften einer genauen Vorabversion direkt funktioniert weiterhin für eine einmalige Installation (uip tools install maestro-tool@1.0.0-preview.1), aber updateChannel regelt die laufende Lösung – ein nicht angeheftetes uip tools update oder eine automatische Installation wird immer erneut für den Kanal aufgelöst, nicht für ein Tag einmal bestanden. Die vollständige Referenz für den Schlüssel updateChannel/version finden Sie unter uip config .

Automatische Aktualisierungen

Allein gelassen hält sich uip selbst auf dem neuesten Stand – dies geschieht standardmäßig ohne Anmeldung.

Die tägliche CLI-Synchronisierung

Einmal am Tag prüft der erste in Frage kommenden Befehl auf dem aufgelösten Kanal nach einer neueren CLI-Version, installiert sie, aktualisiert Fähigkeiten und führt Ihren ursprünglichen Befehl auf der neuen Version erneut aus – transparent mitten im Aufruf. Es schreibt nur in standard (ein Drehfeld für interaktive Terminals) und ändert nie den Exitcode Ihres Befehls. Ein manuelles uip update wird durch dieses tägliche Gate nie gedrosselt.

Es kreuzt nie eine MaJOR-Version als Unattended an. Ohne Versionsnummer begrenzt sich die tägliche Synchronisierung auf den MaJOR, den sie bereits ausführt – durch das Veröffentlichen von 2.0.0 in latest wird eine 1.x -Installation über Nacht im Hintergrund aktualisiert. Sie kündigt die neue Version an, die abgelehnt wurde, sodass Sie sich gezielt dafür entscheiden können:

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

Die Synchronisierung überspringt bestimmte Kontexte automatisch (CI env-var auth, ein Monorepo-Checkout, eine mit Studio gebündelte Installation, die update/login/logout/mcp/completion/config/skills/help Verben, --version/--help, eine genaue core.version -PIN) und kann vollständig deaktiviert werden mit:

export UIPATH_CLI_DISABLE_VERSION_SYNC=true

Status wird in ~/.uipath/version-sync.json nachverfolgt; uip login erreicht es nie.

Die tägliche Prüfung pro Tool

Wenn ein Tool-Verb zum ersten Mal pro Tag ausgeführt wird, führt die CLI eine Registrierungssuche nach diesem Tool in der major.minor -Zeile der laufenden CLI durch und installiert den neuesten übereinstimmenden Build, bevor das Tool geladen wird – keine erneute Ausführung, da Tools nur langsam geladen werden den gleichen Prozess. Diese Prüfung schlägt geschlossen: Wenn die Suche oder Installation fehlschlägt, wird der Befehl überhaupt nicht ausgeführt (ein Failure -Ergebnis fordert Sie auf, die Verbindung zu überprüfen und es erneut zu versuchen), anstatt das Risiko zu laufen, ein veraltetes Tool auszuführen. UIPATH_CLI_DISABLE_VERSION_SYNC und UIPATH_CLI_DISABLE_AUTOINSTALL überspringen beide diese Prüfung; Dies gilt auch für einen genauen core.version -PIN.

Stabilität pro Befehl

Einzelne Befehle und Flags tragen eine von drei Stabilitätsbeschriftungen. Suchen Sie oben auf der Referenzseite jedes Befehls nach ihnen.

Label	Bedeutung
Ga (Standard; unbeschriftet)	Der Befehl wird durch den obigen Semver-Vertrag abgedeckt. Sie wird in einer MaJOR-Version nicht umbenannt oder entfernt.
Vorschau	Der Befehl befindet sich in der aktiven Development. Flags, Standardeinstellungen und Ausgabeform können sich ohne größere Änderungen ändern, obwohl grundlegende Änderungen selten sind und in den Versionshinweisen angekündigt werden. Verwenden Sie sie nur dann in der Produktion, wenn Sie bereit sind, bei jeder Version neu zu validieren.
Veraltet	Der Befehl soll in der nächsten MaJOR-Version entfernt werden. Es funktioniert weiterhin in 1.x und gibt eine Warnung in Standardversion aus. Verwenden Sie den Nachfolger, der im Hinweis zur veralteten Eigenschaft aufgeführt ist.

Dies ist die gleiche Konvention, die auch von gcloud verwendet wird. Die UiPath CLI schaltet Vorschau-Befehle nicht hinter einem Opt-in-Flag – sie sind in --help sichtbar und aufrufbar.

Anheften von Empfehlungen

Für CI-Pipelines:

# 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

Dadurch erhalten Sie eine reproduzierbare Umgebung, die Upstream-Releases übersteht. Führen Sie nach jedem CLI-Error mithilfe der Integrationstests Ihrer Pipeline eine erneute Validierung durch; bekannte Änderungen an Data-Form finden Sie in den Versionshinweisen .

Für Entwickler-Workstations:

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

Weniger reproduzierbar, einfacher.

Verwerfungszyklus

Wenn ein Befehl oder ein Flag verschwindet, lautet der Pfad:

1. Angekündigte Einstellung – Der Befehl ist auf seiner Referenzseite Deprecated gekennzeichnet, und in den Versionshinweisen für die Minor-Version, in der die veraltete Version eingeführt wurde, wird er aufgeführt. Ein Ersatz wird dokumentiert.
2. Runtime-Warnung – uip <deprecated-command> ... funktioniert weiterhin, gibt aber eine Warnung für Standardfehler aus. Skripte, die „stdout“ verwenden, sind nicht betroffen.
3. Entfernen im nächsten MaJOR – der Befehl wird bei der nächsten Erhöhung der MaJOR-Version entfernt. Es gibt mindestens einen vollständigen MaJOR-Zyklus zwischen der Einstellung und dem Entfernen – lange genug, um jede Pipeline auf dem unterstützten Lebenszyklus zu migrieren.

Führen Sie uip <command> --help aus, um anzuzeigen, ob ein Befehl veraltet ist; Die Beschriftung wird in der Synopse angezeigt.

Wenn sich die Datenform ändert

Da Data befehlsspezifisch ist und sich in MINOR-Releases ändern kann, sind Pipelines, die bestimmte Felder (--output-filter "Data.Jobs[0].Key") extrahieren, die am meisten für Minor-Abzeichen betroffen. Zwei Schadensbegrenzungen:

• Anheften von @uipath/cli in CI (siehe oben). Sie wählen aus, wann neue Formen validiert werden sollen.
• Defensiv abfragen – bevorzugen Sie JMESPath-Ausdrücke, die fehlende Felder (Data.Jobs[0].Key || '') tolerieren, wenn Sie können; Lesen Sie die Versionshinweise, bevor Sie ein Upgrade durchführen.

Durchschlagende Data -Formänderungen in Minor sind selten und werden in den Versionshinweisen als [Data shape] unter dem geänderten Befehl gekennzeichnet.

Wo auf Änderungen überwacht werden soll

• Versionshinweise – Zusammenfassung der hinzugefügten Befehle, geänderten Flags und Formänderungen pro Version.
• uip --version und uip tools list – was derzeit auf einer Maschine installiert ist. Vergleichen Sie Umgebungen, um Abweichungen zu erkennen.
• Das Paket jedes Tools auf npm – Publisher führen dort dist-tags und den Release-Verlauf auf.

Siehe auch

• Ausgabeformate – die Umschlagsform, die der Vertrag beschreibt.
• Austrittscodes – der fünfstufige Vertrag.
• Tools (Plugins) – das Host-Tool-Modell, das durch das Anheften von Versionen unterstützt wird.
• Versionshinweise – was sich geändert hat und wann.
• Migration von der Legacy-.NET-CLI – wenn Sie von 2025.10 oder früher kommen.