バージョン管理と安定性

UiPath CLI のセマンティック バージョン管理コントラクトです。MAJOR、MINOR、PATCH の変更点と、ホスト/ツールの相互運用性マトリクスを記載しています。

UiPath CLI は セマンティック バージョン管理 (MAJOR.MINOR.PATCH) に従い、バージョン 1.197.0 で 一般提供 (GA) になりました。これは、従来の .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) は、MAJOR リリース内で安定しています。4 は、現在、タイムアウト時に uip tm perf-scenario execute --wait によってのみ発行されます。より長期実行のコマンドでは採用される可能性があるため、「タイムアウト」として扱います。

グローバル オプション

--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 maestro-tool --version 1.1.5

ピン留めが重要な理由

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

更新チャネル

ホストとそのツールがどのビルドに解決されるかは、 チャネル (CLI ホストレベルの設定であり、install コマンドで渡されるツールごとの npm タグではありません) によって制御されます。stable (既定)、preview、および非表示のdevの 3 つのチャネルが存在します。で設定します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

各チャネルは、実際の npm dist-tag にマップされます。

Channel	公開元	レジストリ	dist-tag
stable	手動リリース実行日 release/*	NPMJS	latest (または latest未満のバックポートの場合は previous )
preview	プッシュ先 release/*	GitHub パッケージにミラーリングされた npmjs	preview
dev	プッシュ先 main	GitHub パッケージのみ	dev

dev は受け入れられます (uip config set updateChannel dev)が、 --help リストと「有効な値」リストから意図的に除外されています — -dev.* CLI がツールを独自の行で解決するためであり、オプトインするチャネルとして存在しません。

正確なプレリリース バージョンを直接ピン留めしても 1 回限り (uip tools install maestro-tool@1.0.0-preview.1) でも機能しますが、 updateChannel が継続的な解決を左右します。ピン留めされていない uip tools update または自動インストールは、一度渡したタグではなく、常にチャネルに対して再解決されます。updateChannel/version キーの完全なリファレンスについては、uip configをご覧ください。

自動更新

放っておくと、 uip は最新の状態を維持します。これは既定で実行され、オプトインはありません。

毎日の CLI の同期

1 日に 1 度、 最初に 適格なコマンドは、解決されたチャネルで新しい CLI バージョンをチェックし、インストールし、スキルを更新し、 新しいバージョンで元のコマンドを再実行 します (呼び出しの途中で透過的に)。stderr (対話型ターミナルのスピナー) にのみ書き込み、コマンドの終了コードを変更することはありません。手動 uip update が、この日次ゲートによって調整されることはありません。

メジャー バージョンを無人で越えることはありません。バージョンのピンがない場合、毎日の同期はすでに実行されている MAJOR で制限されます — 2.0.0 を latest に公開しても、 1.x インストールが一晩でサイレントにアップグレードされるわけではありません。拒否した新しいバージョンがアナウンスされるため、意図的にオプトインできます。

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

同期では、特定のコンテキスト (CI 環境変数認証、モノリポジトリ チェックアウト、Studio にバンドルされたインストール、 update/login/logout/mcp/completion/config/skills/help 動詞、 --version/--help、正確な core.version ピン) は自動的にスキップされ、以下を使用して完全にオフにすることができます。

export UIPATH_CLI_DISABLE_VERSION_SYNC=true

ステートは ~/.uipath/version-sync.jsonで追跡されます。 uip login 決して触れません。

ツールごとの日次チェック

これとは別に、ツール動詞が毎日初めて実行されると、CLI は実行中の CLI の major.minor 行でそのツールのレジストリ検索を 1 回行し、ツールがロードされる前に最新の一致するビルドをインストールします — ツールは同じプロセスで遅延ロードされるため、再実行は行われません。このチェック は閉じて失敗します。検索またはインストールが失敗した場合、古いツールを実行するリスクがなくなり、コマンドはまったく実行されません ( Failure 結果では接続を確認してリトライするように求められます)。UIPATH_CLI_DISABLE_VERSION_SYNC と UIPATH_CLI_DISABLE_AUTOINSTALL の両方がこのチェックをスキップします。正確な core.version ピンも同様です。

コマンドごとの安定性

個々のコマンドとフラグには、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 以前から移行する場合。