迁移：重大变更

以标志换标志端口无法捕获的方式破坏管道的语义更改。移植前请阅读此页； “命令映射”和“标志重命名”处理机制重命名工作。

下方每项更改都具有相同的结构：更改内容、更改原因、变更内容。请浏览第一行粗体内容，并深入了解管道受影响的位置。

已删除身份验证模式

更改内容。旧版uipcli接受每条命令的三种身份验证模式：用户/密码（ -u / -p ）、刷新令牌（ -t / -a ）和外部应用程序（ -A / -I / -S / --applicationScope ）。新的 CLI仅接受外部应用程序客户端凭据（适用于 CI）、交互式 OAuth2（适用于开发者）和环境变量访问令牌（适用于容器）。用户/密码和刷新令牌身份验证已消失 — 标志字母-u 、 -p 、 -t和-a未分配（ -u 、 -p和-a ）或改变了用途（ -t现在为--tenant ）。

为什么。 Automation Cloud 已弃用新工作负载的用户/密码流程和刷新令牌流程。外部应用程序凭据是唯一可在 CI 运行器之间实现良好扩展的流程，支持组织级别的审核，并且可以在不轮换人类帐户的情况下撤销凭据。

操作。在 UiPath 中创建一个外部应用程序，其中使用的作用域与您的管道当前在--applicationScope下列出的相同，然后将每个基于命令的身份验证块替换为单个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 身份验证读取

更改内容。当缺少相应标志时，旧版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.表单在运行时读取变量，而不会将其展开到命令行中，因此密码不会出现在 Shell 历史记录或ps输出中，这是比旧版隐式读取更安全的模式。请参阅身份验证 — env.VAR_NAME前缀。

已取消由日历版本控制的版本

更改内容。旧版作为 NuGet 上的日历版本（ 2023.10 、 2024.10 、 2025.10 ）提供（ UiPath.CLI 、 UiPath.CLI.Windows ），文件夹布局类似于.../UiPath.CLI.25.10.xxxx/tools/uipcli.dll 。新的 CLI 在 npm 上作为@uipath/cli分发，具有语义版本控制（ 1.0.0 、 1.0.1 、 1.1.0 、 2.0.0 ）。

为什么。日历版本控制传达发布日期，但不传达兼容性。Semver 传达兼容性信息： 1.0.x → 1.1.x具有附加性， 1.x → 2.x具有破坏性，并且是一个弃用周期。主机 + 工具包还会在语义版本上进行协调 — 工具版本自动固定到 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 ...

如需完整的语义化版本合同，请参阅安装 UiPath CLI和版本控制和稳定性。

Runtime 更改：Node.js 18+ 取代.NET 作为 CLI Runtime； rpa-tool 保留.NET 依赖项

更改内容。旧版uipcli完全在.NET 上运行（ UiPath.CLI需要.NET 6 跨平台； UiPath.CLI.Windows使用.NET Framework）。新的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 打包程序和工作流编译器，两者都是.NET 支持的。除了 Node.js 之外，运行uip rpa …命令的管道还需要.NET 运行时，而不是取代 Node.js。有关当前先决条件，请参阅UIP RPA 参考。

为什么。核心 CLI 移至 Node，以获得更小、更便于移植的运行时占用空间、更简单的跨平台分发以及单个注册表 (npm) 的故事。RPA 特定界面保留了其.NET 后端，因为 Studio 打包器和分析器是原生.NET — 重写它们超出了 1.0 的范围。

操作。

1. 始终在运行器上配置 Node.js 18+ 。这对于uip本身为必要项；未运行节点， 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 ，但.NET 运行时本身仍然必须存在，以便rpa-tool可以调用 Studio 打包程序。

3. 如果您的管道不调用uip rpa … ，请删除.NET/ dotnet-sdk设置步骤。其余工具（Orchestrator、解决方案、智能体、流、Maestro、Test Manager 等）则不需要这些数据。

请参阅安装 UiPath CLI — CI/CD 。

退出代码合同收紧

更改内容。旧版uipcli发出更广泛的退出代码，通常将.NET 流程级代码（1-3 位数，特定于框架）与命令级代码混合使用。新的 CLI 仅发出五个规范代码（ 0 、 1 、 2 、 3 、 4 ）以及用于用户取消的130 ，并且从结果到代码的映射在主要版本中保持稳定。

退出代码	意义
0	成功。
1	一般性故障或配置错误。
2	身份验证错误 (401、403)。
3	验证错误（错误标志、未知选项、标志互斥）。
4	超时错误。保留；在 1.x 中没有命令会发出它。
130	已取消用户 (Ctrl+C)。

一次特定于域的重用： uip tm wait在超时时返回2 （因此脚本可以区分超时和身份验证槽）。在其他方面，合同为统一合同。

为什么。一组稳定的代码使 CI 重试/升级逻辑简单明了： 2表示“重新身份验证，然后重试”； 表示“重新身份验证，然后重试”。 3表示“从不重试，修复命令”； 1表示“如有暂时性情况，则重试一次”。旧版广泛需要管道来单独处理每个命令的代码。

操作。将特定于代码的分支替换为新的五个分支。如果您的管道包含“对任何非零代码进行重试”等逻辑，请将其收紧，以仅在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

注意：Test Manager 接受运行请求后， uip tm testsets run始终退出0 。失败通过uip tm wait + uip tm report get和Data.Failed来指示，而不是run的退出代码。请参阅退出代码。uip tm wait页面记录了其退出代码语义。

标准输出默认为 JSON

更改内容。旧版uipcli已将人工可读的日志文本写入标准输出；退出代码和生成的任何文件是唯一的计算机可读输出。默认情况下，新的 CLI 会在执行每个命令时将JSON 信封写入标准输出：

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

无论--output的值如何，日志、进度和面向人的错误都将记录到标准错误 (stderr)中。人工可读的表格视图可通过--output table加入。

为什么。 JSON 优先的输出意味着每个命令都可编写脚本，无需解析技巧，并且相同的调用在终端和管道中以相同的方式工作。STderr 上的日志意味着管道可以完全执行command > payload.json 2> log.txt操作。

操作。任何使用 grep 命令搜索到的uipcli文本输出的 Shell 步骤都必须切换到以下选项之一：

• --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将<orchestrator_url>和<orchestrator_tenant>作为每个动词的位置参数( job run "<name>" "<url>" "<tenant>" ... )。新的 CLI 从uip login编写的经过身份验证的会话中解析这两者；不需要位置 URL，并且租户是会话默认值，每个命令都可以使用-t, --tenant <name>覆盖该默认值。

为什么。管道中的每个命令通常都针对同一个 Orchestrator；在每次调用时传递 URL 和租户是重复的，并且会邀请复制粘贴错误。每次调用覆盖的会话状态是标准 CLI 模式 (参见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"

对于多租户脚本，请在一次调用中向需要不同租户的任何命令传递-t TENANT 。请参阅身份验证 — 在会话中管理租户。

CLI 表面上已弃用传统文件夹概念

更改内容。旧版 CLI 包含多个传统文件夹专用标志：针对-e, --environments <csv> package deploy 、针对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 运行）

更改内容。旧版存在一个隐藏的--captureCommandToJsonFile <path>标志，用于将当前调用序列化为 JSON，以及一个uipcli run <file>动词，它使用该 JSON 来重播命令。两者都将被删除。

为什么。该模式主要用于调试 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
新添加 uip	UIPATH_TELEMETRY_DISABLED	1 或者 true

为什么。新名称更短，遵循 CLI 其他位置使用的<SCOPE>_DISABLED模式，并删除EXTENSIONS_前缀（新 CLI 不是任何内容的扩展）。

操作。更新已设置UIPATH_EXTENSIONS_CLI_TELEMETRY_ENABLED=False CI 运行器和开发计算机以设置UIPATH_TELEMETRY_DISABLED=1 。新 CLI 会忽略旧版变量，因此仅设置旧名称的计算机将再次发送遥测数据，直到添加新名称为止。请参阅新增功能 — 其他有意义的转变。

另请参阅

• 命令映射— 要调用的动词。
• 标记重命名— 逐个标记映射。
• 管道示例— 在常见 CI 平台的 YAML 之前/之后。
• 退出代码— 五层合同。
• 新增功能— 每个重写亮点的正面总结。