移行: 重大な変更

flag-for-flagポートがキャッチできない方法でパイプラインを中断するセマンティック変更。移植する前にこのページをお読みください。 コマンド マップ と フラグの名前の変更 は、機械的な名前変更作業を処理します。

以下のすべての変更は、 何が変更されたのか、 なぜ変更されたのか、 何をすべきかという同じ構造を持っています。大胆な最初の行に目を通し、パイプラインが影響を受ける場所を掘り下げます。

認証モードの削除

何が変わったのか。レガシ uipcli では、コマンドごとに 3 つの認証モードを使用できます。 ユーザー/パスワード (-u/-p)、 更新トークン (-t/-a)、 外部アプリケーション (-A/-I/-S/--applicationScope) です。新しいCLIは、外部アプリケーションクライアントクレデンシャル(CIの場合)、インタラクティブOAuth2(開発者向け)、および環境変数アクセストークン(コンテナの場合) のみ を受け入れます。ユーザー/パスワードと更新トークン認証はなくなりました — -u、 -p、 -t、 -a は割り当て解除(-u、 -p、 -a)または再利用(-t が --tenantになりました)のいずれかです。

なぜでしょうか。 Automation Cloud では、新しいワークロードのユーザー/パスワード フローと更新トークン フローを非推奨としました。外部アプリケーションの資格情報は、CI ランナー間でクリーンにスケーリングされ、組織レベルの監査をサポートし、人間のアカウントをローテーションせずに取り消すことができる唯一のフローです。

何をすべきか。パイプラインが現在 --applicationScopeに一覧表示しているスコープと同じスコープを UiPath で外部アプリケーションを作成し、コマンドごとのすべての認証ブロックを 1 回の uip login 呼び出しに置き換えます。

# Legacy — auth on every command
uipcli job run "MyProcess" "https://cloud.uipath.com/" "Tenant" \
    -u "[e-mail]" -p "$PASSWORD" -o "Shared"

# uip — auth once, use many
uip login \
    --client-id env.UIPATH_CLIENT_ID \
    --client-secret env.UIPATH_CLIENT_SECRET \
    --tenant "$UIPATH_TENANT"
uip or jobs start "$PROCESS_KEY"

完全なフロー カタログの 「認証 」をご覧ください。[フラグの名前変更] の [認証] セクションには、削除されたすべてのフラグが一覧表示されます。

暗黙的な env-var auth の読み取りの削除

何が変わったのか。レガシ uipcli は、対応するフラグがない場合、環境から UIPATH_CLIENT_ID と UIPATH_CLIENT_SECRET を暗黙的に読み取りました。新しい CLI では、環境変数は、--client-id/--client-secretの env.VAR_NAME プレフィックス、または UIPATH_CLI_ENABLE_ENV_AUTH=true アクセス トークン フローを使用して明示的に参照した場合にのみ読み取られます。

なぜでしょうか。 暗黙的な読み取りでは、パイプラインのステップだけでは、コマンドがどのシークレットに依存しているかを見分けることができませんでした。明示的な env. プレフィックス形式は、呼び出し自体の依存関係を明らかにするため、監査、ローテーション、およびシークレット スキャンの信頼性が高まります。

何をすべきか。環境変数への暗黙的な依存を明示的な env. 参照に置き換えます。

# Before — relied on implicit reading
UIPATH_CLIENT_ID="..." UIPATH_CLIENT_SECRET="..." uipcli job run ...

# After — explicit reference
uip login \
    --client-id env.UIPATH_CLIENT_ID \
    --client-secret env.UIPATH_CLIENT_SECRET \
    --tenant "$UIPATH_TENANT"

env.フォームは、コマンドラインに展開せずに実行時に変数を読み取るため、シークレットはシェル履歴やps出力に表示されず、従来の暗黙的な読み取りよりも安全なパターンです。「認証 — env.VAR_NAME接頭辞」を参照してください。

カレンダー バージョン管理されたリリースは終了しました

何が変わったのか。レガシ パッケージは、カレンダー バージョン (2023.10、 2024.10、 2025.10) として NuGet (UiPath.CLI、 UiPath.CLI.Windows) で、フォルダー レイアウトは [ .../UiPath.CLI.25.10.xxxx/tools/uipcli.dll] のようなものでした。新しいCLIは、セマンティックバージョニング(1.0.0、1.0.1、1.1.0、2.0.0)で@uipath/clinpmで配布されます。

なぜでしょうか。 カレンダーのバージョン管理は、リリース日を通知しますが、互換性は通知しません。Semver は互換性を伝達します。 1.0.x → 1.1.x は付加的であり、 1.x → 2.x は破壊的であり、その前に非推奨化サイクルが続きます。ホスト + ツール パッケージも semver で調整します — ツール バージョンは CLI の MAJOR.MINOR 行に自動的にピン留めされます。

何をすべきか。カレンダーでバージョン管理された NuGet パッケージ、 uipcli.dll パス、年間フォルダー名への参照をすべてパイプラインから削除します。npmでインストールし、 @x.y.zで固定します。

# Before — Azure DevOps example
curl -L -O https://www.nuget.org/api/v2/package/UiPath.CLI.Windows/25.10.xxxx
unzip UiPath.CLI.Windows.25.10.xxxx -d ./cli
./cli/tools/uipcli.exe ...

# After
npm install -g @uipath/cli@1.0.0
uip tools install or solution tm   # pre-install tools (optional but deterministic)
uip ...

semver の完全契約については、「 UiPath CLI をインストールする 」および「 バージョン管理と安定性 」をご覧ください。

ランタイムの変更: Node.js 18+ は CLI ランタイムとしての .NET を置き換えるものです。rpa-tool は .NET の依存関係を保持します

何が変わったのか。レガシ uipcli は完全に .NET 上で実行されていました (.NET 6 クロスプラットフォームが必要UiPath.CLI 、.NET Framework UiPath.CLI.Windows 使用)。新しい uip ホストはNode.jsプログラムであり、どのツールを使用するかに関係なく、すべての呼び出しはランナーで Node.js 18 以降を必要とします。ホスト自体は .NET への依存を持たず、ほとんどのツール (Orchestrator、Solution、Agent、Flow、Maestro、Test Manager、Integration Service、Data Fabric、Insights、Traces、DocsAI) は HTTPS 呼び出しのみを行い、それ以上は何も追加しません。

RPA ツール (@uipath/rpa-toolは例外です。uip rpa pack / analyze / restoreとして呼び出されます)。Studio パッケージャーとワークフロー コンパイラをラップします。どちらも .ネットに裏打ちされています。uip rpa … コマンドを実行するパイプラインには、Node.js の代わりにではなく、.NET ランタイムに加えて .NET ランタイムが必要です。現在の前提条件については、 uip RPA のリファレンス をご覧ください。

なぜでしょうか。コアCLIは、より小さく、より移植性の高いランタイムフットプリント、よりシンプルなクロスプラットフォーム配布、および単一レジストリ(npm)ストーリーのためにNodeに移動しました。Studio のパッケージャーとアナライザーはネイティブ .NET であるため、RPA 固有のサーフェスでは .NET バックエンドが維持され、書き換えは 1.0 の範囲外でした。

何をすべきか。

1. ランナーには常に 18+ Node.jsプロビジョニング します。これは、 uip 自体に必要です。Node がない場合、 uip コマンドは実行されません。

   # GitHub Actions example
   - uses: actions/setup-node@v4
     with:
       node-version: '20'
   

2. パイプラインが uip rpa pack、 uip rpa analyze、または uip rpa restoreを呼び出す場合は、ランナーで .NET ランタイムも使用可能な状態に保ちます 。レガシ uipcli を dotnet tool installでインストールする必要がなくなりましたが、Studio パッケージャーを呼び出せるようにするには rpa-tool .NET ランタイム自体が存在している必要があります。

3. パイプラインで uip rpa …が呼び出されない場合は、.NET/ dotnet-sdk のセットアップ手順を削除します。残りのツール (Orchestrator、ソリューション、エージェント、フロー、Maestro、Test Manager など) には必要ありません。

「 UiPath CLI — CI/CD をインストールする」をご覧ください。

エグジットコードの契約が引き締まる

何が変わったのか。レガシ uipcli では、より広範な終了コードが出力され、多くの場合、.NET プロセス レベルのコード (1 から 3 桁のフレームワーク固有) とコマンド レベルのコードが混在していました。新しいCLIは、5 つの正規コード (0、 1、 2、 3、 4)とユーザーキャンセル用の 130 を出力し、結果からコードへのマッピングはメジャーリリース内で安定しています。

終了コード	意味
0	成功。
1	一般的なエラーまたは設定エラー。
2	認証エラー (401/403)。
3	検証エラー (不正なフラグ、不明なオプション、相互に排他的なフラグ)
4	タイムアウト エラーです。予約;1.x ではコマンドが出力されません。
130	ユーザーがキャンセルされました (Ctrl+C)。

ドメイン固有の再利用の 1 つ: uip tm wait はタイムアウト時に 2 を返します (スクリプトがタイムアウトと認証スロットを区別できるようにします)。それ以外の場合、契約は一様です。

なぜでしょうか。小さくて安定したコードセットにより、CIの再試行/エスカレーションロジックが簡単になります: 2 は「再認証してから再試行する」ことを意味します。 3 は「再試行しない、コマンドを修正する」という意味です。 1 は、「一時的な場合は 1 回リトライする」という意味です。従来の幅広いパイプラインでは、各コマンドのコードを個別に処理する必要がありました。

何をすべきか。コード固有のブランチを新しい 5 つに置き換えます。パイプラインに "0 以外のコードで再試行する" などのロジックがある場合は、 1 でのみ再試行するように調整します。

# Before — broad retry
if ! uipcli job run ...; then sleep 30; uipcli job run ...; fi

# After — targeted branching
if ! uip or jobs start "$KEY" --wait-for-completion; then
    case $? in
        2)   uip login ...; uip or jobs start "$KEY" --wait-for-completion ;;
        3)   exit 3 ;;   # don't retry bad input
        *)   exit 1 ;;
    esac
fi

注:uip tm testsets run は常に、Test Manager が実行要求を受け入れる 0終了します。失敗は、runの終了コードではなく、Data.Faileduip tm wait + uip tm report getを介して発生します。「終了コード」を参照してください。uip tm wait ページには、終了コードのセマンティクスが記載されています。

Stdout は既定で JSON です

何が変わったのか。レガシ uipcli 人間が判読できるログ テキストを stdout に書き込みました。終了コードと生成されたファイルは、機械判読可能な唯一の出力でした。新しい CLI では、すべてのコマンドで既定で JSON エンベロープ が stdout に書き込まれます。

{
  "Result": "Success",
  "Code": "JobCompleted",
  "Data": { "Key": "...", "State": "Successful", "...": "..." }
}

ログ、進行状況、および人間が直面するエラーは、--output値に関係なく stderr に送られます。人間が判読できる表ビューは、 --output tableでオプトインできます。

なぜでしょうか。 JSON ファースト出力とは、すべてのコマンドが解析トリックなしでスクリプト化可能であり、同じ呼び出しがターミナルとパイプラインで同じように機能することを意味します。stderr のログは、パイプラインがきれいに command > payload.json 2> log.txtできることを意味します。

何をすべきか。テキスト出力 uipcli grep したシェルステップは、次のいずれかに切り替える必要があります。

• --output-filter "<JMESPath>" --output plain — 単一のフィールドをプレーン テキストとして抽出します。例: --output-filter "Data.Key" --output plain
• jq — エンベロープ全体を解析します。
• --output table — 表示専用表の出力を解析しないでください。

# Before
JOB_ID=$(uipcli job run ... | grep -oP 'JobId=\K[0-9a-f-]+')

# After
JOB_KEY=$(uip or jobs start "$KEY" \
    --output-filter "Data.Jobs[0].Key" \
    --output plain)

詳しくは、「出力形式」をご覧ください。--output-filterフラグ自体は、グローバルオプションに記載されています。

テナントと Orchestrator URL はセッション ステートであり、コマンドごとのフラグではありません

何が変わったのか。レガシuipcliは、すべての動詞(job run "<name>" "<url>" "<tenant>" ...)の位置引数として<orchestrator_url>と<orchestrator_tenant>を取りました。新しいCLIは、 uip loginによって記述された認証済みセッションから両方を解決します。指定位置 URL は不要で、テナントは各コマンドが -t, --tenant <name>で上書きできるセッションのデフォルトです。

なぜでしょうか。パイプライン内のすべてのコマンドは、通常は同じ Orchestrator を対象とします。各呼び出しで URL とテナントを渡すと、コピーと貼り付けのエラーが繰り返され、エラーが発生していました。呼び出しごとのオーバーライドを伴うセッション状態は、標準のCLIパターンです(cf.az account set、 gcloud config set、 kubectl config use-context)。

何をすべきか。すべてのコマンドから位置 URL とテナントを削除します。ログイン時にテナントを設定します(または呼び出しごとに -tで上書きします)。

# Before
uipcli package deploy "./pkg.nupkg" \
    "https://cloud.uipath.com/" "ProdTenant" \
    -A "org" -I "..." -S "..." -o "Shared"
uipcli job run "Process" \
    "https://cloud.uipath.com/" "ProdTenant" \
    -A "org" -I "..." -S "..." -o "Shared"

# After
uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET --tenant ProdTenant
uip or packages upload ./pkg.nupkg
uip or processes create --name Process --package-key Process --package-version 1.0.0 --folder-path Shared
uip or jobs start "$PROCESS_KEY"

マルチテナント スクリプトの場合は、その 1 回の呼び出しに別のテナントを必要とするコマンドに -t TENANT を渡します。「 認証 — セッション中のテナントの管理」をご覧ください。

クラシック フォルダーの概念は、CLI サーフェスでは非推奨です

何が変わったのか。レガシCLIには、package deploy上の-e, --environments <csv>、job run上の-r, --robots <csv>、および関連する環境ベースのルーティングなど、いくつかのクラシックフォルダー専用フラグがありました。新しい CLI は、パブリック 動詞でのみ モダン フォルダー モデル を対象としています。クラシック フォルダーは Orchestrator 上に引き続き存在しますが、クラシック固有のフラグは公開 uip 。

なぜでしょうか。 2020 年以降はモダン フォルダーが既定となっています。新しいCLIでクラシックのみのフラグを保持することは、非推奨の動作を新規リリースに持ち込むことを意味しました。

何をすべきか。パイプラインがクラシック フォルダーを対象とする場合は、(a) フォルダーをモダン フォルダー (Orchestrator の管理者用画面) に移行するか、(b) @uipath/rpa-legacy-tool ラッパーを通じて特定の呼び出しに uipcli を使用し続けます。「uip rpa — Windows 専用レガシ ラッパー」をご覧ください。

言語/ロケール フラグの削除

何が変わったのか。レガシ -l, --language <locale> ログ出力を指定されたロケールに変換しました。新しいCLIは 、ログを英語でのみ出力します。

なぜでしょうか。 ログ メッセージは、英語で標準化されているオペレーターとログ配布システムによって使用されることを意図しています。ローカリゼーションは、CLI レイヤーにとって明確な見返りのないコストでした。

何をすべきか。パイプラインから -l / --language フラグを削除します。交換は必要ありません。

キャプチャと再生 (--captureCommandToJsonFile + uipcli run) の削除

何が変わったのか。レガシには、現在の呼び出しを JSON にシリアル化する非表示の --captureCommandToJsonFile <path> フラグと、その JSON を使用してコマンドを再生する uipcli run <file> 動詞がありました。両方が削除されます。

なぜでしょうか。このパターンは、運用メカニズムとしてではなく、Azure DevOps の GUI タスクが CLI フラグにどのようにマップされるかをデバッグするために主に使用されていました。新しいCLIのJSON-stdoutのデフォルトとJMESPathフィルタリングは、個別のサブシステムなしでデバッグのユースケースをカバーします。

何をすべきか。uipcli run <file> を直接uip呼び出しとして使用していたパイプライン ステップを書き換えます。デバッグを --captureCommandToJsonFile に依存していた場合、新しい同等のものは uip <command> --log-level debug --log-file ./uip.log です—ログファイルには、すべてのHTTP呼び出し、認証更新、およびツールの読み込みが含まれます。

テレメトリのオプトアウト環境変数の名前の変更

何が変わったのか。どちらの世代にも、 デフォルトで 匿名のテレメトリオプトアウトが付属しています—テレメトリは明示的に無効にしない限りオンです。環境変数名が変更されました。

生成	変数	無効化する値
レガシ エクスペリエンス uipcli	UIPATH_EXTENSIONS_CLI_TELEMETRY_ENABLED	False
New uip	UIPATH_TELEMETRY_DISABLED	1 OR true

なぜでしょうか。新しい名前は短く、CLI の他の場所で使用されている <SCOPE>_DISABLED パターンに従い、 EXTENSIONS_ プレフィックスを削除します(新しい CLI は、何の拡張機能でもありません)。

何をすべきか。既に UIPATH_EXTENSIONS_CLI_TELEMETRY_ENABLED=False を設定している CI ランナーと開発マシンを更新して、代わりに UIPATH_TELEMETRY_DISABLED=1を設定します。レガシ変数は新しい CLI では無視されるため、古い名前のみを設定したマシンは、新しい名前が追加されるまで、テレメトリが再度送信されます。新機能 — その他の意味のある変化を参照してください。

参照

• コマンドマップ — 呼び出す動詞。
• フラグの名前変更 — フラグごとのマッピング。
• パイプラインの例 — 一般的なCIプラットフォームのYAMLの前/後。
• 終了コード — 5段階の契約。
• 新着情報 — すべてのリライトのハイライトの肯定的な要約。