Versionierung und Stabilität

UiPath CLI 1.0.0 folgt der semantischen Versionierung (MAJOR.MINOR.PATCH). 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 ist reserviert – kein Befehl gibt es heute in 1.x aus – aber Skripte, die es bereits verarbeiten, funktionieren weiterhin.

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

Kanäle

Der Host erkennt npm dis-Tags auf Tools:

• latest – die stabile Zeile (Standard, wenn kein Tag übergeben wird).
• beta – Vorschau-Builds vor der stabilen Linie.
• alpha – Early Access, instabile Builds.

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

Kanäle befinden sich auf Tool-Ebene, nicht auf Host-Ebene. Sie können einen stabilen Host mit einem Betatool für einen bestimmten Workflow kombinieren – beachten Sie, dass die Kombination weniger gut getestet ist.

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.