バージョン管理と安定性

UiPath CLI v1.0.0 は、 セマンティック バージョニング (MAJOR.MINOR.PATCH) に従います。これは、従来の .NET CLI で使用されていたカレンダーベースのスキーム (2023.10、 2024.10、 2025.10) を置き換えるものです。このページは、あるリリースから次のリリースまで信頼できるもの、変更できるもの、およびホストとツールのバージョンがどのように歩調を合わせるかについての契約です。

semverの実際の意味

バンプ	発生時	変更できるもの
メジャー (1.x.x → 2.0.0)	コマンド名、フラグ セマンティクス、JSON エンベロープの重大な変更	コマンドは名前を変更したり、削除したりできます。フラグは名前が変更されたり、意味が変更されたりする場合があります。エンベロープの最上位フィールドの形状が変わることがあります。メジャーリリースの前に完全な非推奨化サイクルが始まります — 非推奨のコマンドは、以前のメジャーの最後のマイナーで機能し続けます。
マイナー (1.0.x → 1.1.0)	新しいコマンド、新しいツール、新しいフラグ、新しいサブコマンド。	コマンド面にのみ加算されます。ただし、JSON エンベロープ内の Data の形状はコマンド固有であり、 新しい フィールドが追加されたり、場合によってはフィールドの名前が変更されたり、ネストされたりする可能性があります。特定のフィールド名を解析するスクリプトは、マイナーバンプで再検証する必要があります。
パッチ ( 、 、1.0.0 → 1.0.1)	バグ修正。	動作の変更は文書化されていません。動作を変更するパッチは、パッチ自体のバグレポートとして扱われます。

--preview フラグはありません (Azure CLI とは異なります)。プレビュー状態コマンドはリファレンスページにラベルが付けられており、マイナーリリース内で警告なしに変更される可能性があります — 以下の コマンドごとの安定性 を参照してください。

安定した契約

以下は、MINOR バージョンまたは PATCH バージョン間で変更はありません。彼らに対して自由に台本を書いた。

エンベロープのフィールド

すべてのコマンドは、次のトップレベル フィールドを持つエンベロープを stdout に出力します。

フィールド	安定 性	意味
Result	安定版	Success、 Failure、 ConfigError、 AuthenticationError、 ValidationError、 TimeoutError。
Code	MAJOR内で安定	コマンド固有の成功識別子 (FolderList、 SolutionPackなど)。新しいコマンドは、マイナーリリースで新しいコードが表示される場合があります。
Data	コマンド固有	各コマンドによって定義されるペイロードの形状。マイナー リリースでフィールドを追加する場合があります。まれに、マイナーでフィールドの名前が変更されることがあります — リリース ノートをご覧ください。
Message, Instructions	安定版	人間が判読できるエラー テキスト。コンテンツはリリースごとに改善される可能性があります。存在感と役割は変わりません。
Context, Log	安定版	任意のフィールド。存在条件は安定しています。

詳しくは、エンベロープ の出力フォーマット を参照してください。

終了コード

5段階のエグジットコード契約(0 / 1 / 2 / 3 / 4とユーザーキャンセルの130)は、メジャーリリース内で安定しています。4 は予約されていますが(現在、1.xではコマンドが出力しません)、すでにそれを処理しているスクリプトは機能し続けます。

グローバル オプション

--output、 --output-filter、 --log-level、 --log-file —これら4つのフラグは、マイナーバンプ全体で安定しています。新しいグローバルオプションが追加される可能性があります。既存のものは、メジャーリリースなしで名前を変更したり削除したりすることはありません。

Stdout / stderr分離

Stdout はエンベロープです。stderr は、ログ、進行状況、および人間向けのエラー テキストです。この分離は、すべてのコマンド、すべての形式、すべてのリリースに当てはまります。

ホストとツールのバージョン

ホスト (@uipath/cli、 uip 実行可能ファイル) と各ツール ( @uipath/orchestrator-toolなど) は、それぞれ独自の semver を持つ独立した npm パッケージとして公開されます。これらは、バージョン 1.0.x のホストが 1.0.xでツールを実行するように調整されます。

既定のバージョン解決

明示的なバージョンなしで uip tools install <alias> を実行すると、ホストはメジャーの最新のツールバージョンを選択します。MINOR は、CLI の現在の MAJOR と一致します。マイナーライン。CLI を 1.0.x から 1.1.0 にアップグレードしてから実行すると uip tools update インストールされているすべてのツールが 1.1.x ラインに追加されます。

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

特定のツールのデフォルトを上書きできます。

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

ピン留めが重要な理由

ツールは、バージョン管理された TypeScript コントラクト (コマンド登録、出力形式、テレメトリ、コンテキスト) を介してホストと通信します。マイナー バージョン間でコントラクトが変更された場合は、ホストとツールを一緒に移動する必要があります。バージョンをピン留めするデフォルトは、ユーザーがそれについて考える必要なしに、彼らがそうすることを保証しています。

Channels

ホストはツールの npm dist-tags を認識します。

• latest — 安定した行(タグが渡されない場合のデフォルト)。
• beta — プレビューは、安定したラインの前に構築されます。
• alpha — 早期アクセス、不安定なビルド。

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

チャネルはツールレベルであり、ホストレベルではありません。特定のワークフロー用に安定したホストとベータツールを組み合わせることができますが、この組み合わせは十分にテストされていないことに注意してください。

コマンドごとの安定性

個々のコマンドとフラグには、3 つの安定性ラベルのうちの 1 つが付いています。各コマンドのリファレンス ページの上部にあるものを探します。

ラベル	意味
一般提供 (既定、ラベルなし)	このコマンドは、上記の semver 契約の対象となります。メジャーリリース内で名前が変更されたり削除されたりすることはありません。
プレビュー	司令部は活発に開発されています。フラグ、デフォルト、および出力形状は、重大な変更はまれであり、リリースノートで発表されますが、大きなバンプなしで変更される可能性があります。運用環境では、リリースごとに再検証する準備ができている場合にのみ使用してください。
非推奨	このコマンドは、次のメジャー リリースで削除される予定です。1.x でも引き続き動作し、stderr で警告を発します。非推奨化に関するメモに記載されている後続エンジンを使用します。

これは、gcloud が使用するのと同じ規則です。UiPath CLI では、プレビュー コマンドはオプトイン フラグでゲートされません。コマンドは --help に表示され、呼び出し可能です。

ピン留めに関する推奨事項

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

これにより、アップストリームリリースに耐えられる再現可能な環境が得られます。パイプラインの統合テストを使用して、各CLIバンプの後に再検証します。既知のData形状の変更については、リリース ノートをご覧ください。

開発者ワークステーションの場合:

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

再現性が低く、より便利。

非推奨化のサイクル

コマンドまたはフラグがなくなる場合、パスは次のとおりです。

1. 非推奨化の発表 — コマンドはリファレンス ページで Deprecated とマークされており、非推奨化を導入したマイナー リリースのリリース ノートにはこのコマンドが記載されています。交換品が文書化されています。
2. 実行時の警告 — uip <deprecated-command> ... は引き続き機能しますが、stderr で警告を発します。stdout を使用するスクリプトは影響を受けません。
3. 次のメジャーでの削除 — コマンドは次のメジャーバージョンのバンプで削除されます。非推奨化と削除の間には 、少なくとも 1 つの完全な MAJOR サイクル があり、サポートされているライフサイクルのパイプラインが移行するのに十分な長さです。

uip <command> --helpを実行して、コマンドが非推奨かどうかを確認します。ラベルは [概要] に表示されます。

データの形状が変更されたとき

Dataはコマンド固有であり、マイナー リリースで変更される可能性があるため、特定のフィールド (--output-filter "Data.Jobs[0].Key") を抽出するパイプラインは、マイナー チャーンの影響を最も受けやすいパイプラインです。2 つの軽減策:

• CI のピン@uipath/cli (上記参照)。新しい図形を検証するタイミングを選択します。
• 防御的なクエリ — 可能であれば、欠落しているフィールド (Data.Jobs[0].Key || '') を許容する JMESPath 式を優先します。アップグレード前にリリース ノートを確認します。

MINOR で Data 形状の破壊的変更はまれであり、リリース ノートでは changed コマンドの [Data shape] としてフラグが付けられます。

変更に注意する場所

• リリースノート — 追加されたコマンド、変更されたフラグ、および形状の変更のバージョンごとの要約。
• uip --versionとuip tools list — マシンに現在インストールされているもの。環境間で比較してドリフトをキャッチします。
• 各ツールのパッケージは npm にあります — パブリッシャーは dist-tags とリリース履歴をそこにリストします。

参照

• 出力フォーマット : コントラクトが記述するエンベロープ形状。
• 終了コード — 5段階の契約。
• ツール (プラグイン) — バージョンピン留めがサポートするホストツールモデル。
• リリース ノート — 変更内容と変更時期
• レガシ .NET CLI からの移行 — 2025.10 以前から移行する場合。