安装 UiPath CLI

UiPath CLI 在 npm 上作为@uipath/cli分发，并全局安装uip命令。它可以在 Node.js 18 或更高版本支持的任何平台上运行：x64 和 ARM64 上的 Windows、macOS 和 Linux。

先决条件

• Node.js 18或更高版本。Node.js 附带npm ，这足以安装和运行uip 。
• 任何平台 — Windows（x64、ARM64）、macOS（x64、ARM64）、Linux（x64、ARM64）。

检查您的节点版本：

node --version

如果 Node.js 版本低于 18 或未安装，请从nodejs.org下载或使用版本管理器，例如nvm (macOS/Linux) 或nvm-windows 。

安装

NPM

npm install -g @uipath/cli

pnpm

pnpm add -g @uipath/cli

备注：

两个包管理器都从公共 npm 注册表中安装相同的@uipath/cli包。使用您团队已有的服务。

安装程序会在您的PATH上放置uip可执行文件。在 Windows 中， uip.cmd / uip.ps1启动器位于%APPDATA%\npm\下；在 macOS 和 Linux 上， uip启动器（ node ./dist/index.js周围的小填充程序）位于npm config get prefix报告的前缀下（通常是/usr/local/bin或~/.npm-global/bin ）。

验证安装

uip --version

您应该会看到已安装的版本号（例如1.0.0 ）。

uip --help

您应该会看到核心命令列表： login （包含status 、 tenant list和tenant set子命令）、 logout 、 tools 、 skills 、 mcp 、 completion通过计算机上已安装或注册的工具。

要确认uip启动器及其工具所在的位置，请执行以下操作：

npm root -g              # directory holding @uipath/cli and installed tools
npm config get prefix    # parent directory whose bin/ folder holds the uip launcher

第一个命令

UiPath CLI 仅附带主机和一小部分核心命令。未预装任何工具。首次调用前缀与自动安装白名单上的工具匹配的命令时，主机会自动从 npm 下载并安装该工具。

例如，首次运行 Orchestrator 命令时， uip会安装@uipath/orchestrator-tool ：

uip or folders list

Installing @uipath/orchestrator-tool...
✓ Installed @uipath/orchestrator-tool
...

后续的uip or ...调用将直接使用已安装的工具。您还可以使用uip tools install显式安装工具：

uip tools install @uipath/orchestrator-tool
uip tools install @uipath/solution-tool

有关完整的白名单，请参阅“工具（插件）” ，有关日常工具管理的信息，请参阅“管理工具和技能” 。

控制工具自动安装

每当调用的动词位于白名单中且尚未安装工具时，自动安装都会运行。没有退出标志或环境变量 — 特别是， CI=true不会禁用自动安装。在无状态 CI 运行程序上，这意味着内部版本中的第一个命令下载其工具，同一作业中的后续命令将重用已安装的副本。这使得第一个命令比后续命令慢，除非您预安装。

为了保持 CI 构建时间的确定性，请作为单独步骤预安装您使用的工具，以便后续每次uip调用都会发现这些工具已经存在：

uip tools install @uipath/orchestrator-tool @uipath/solution-tool

当工具已安装时，自动安装不会执行任何操作，因此预安装步骤是您唯一需要更改的行为。

启用 shell 补全

UiPath CLI 附带了bash 、 zsh 、 Files和pwsh的 Tab 键补全。从 CLI 本身中安装补全：

uip completion

在终端中， uip completion会从$SHELL / $PSModulePath /平台检测您的 Shell，输出将要修改的目标 rc 文件，并要求您确认。接受提示并重新打开 Shell — uip <TAB>现在可以完成子命令和选项。

对于脚本化设置，请直接将补全脚本通过管道传输到 rc 文件中：

# zsh
uip completion zsh >> ~/.zshrc

# bash
uip completion bash >> ~/.bashrc

# fish
uip completion fish > ~/.config/fish/completions/uip.fish

# PowerShell
uip completion pwsh >> $PROFILE

其他选项：

• uip completion --print — 在不修改文件系统的情况下，预览目标路径和将要写入的块。
• uip completion --uninstall — 删除托管补全块。

备注：

动态标志值补全（例如uip or packages upload --package-name <TAB> ）仅适用于 zsh ，并且需要jq上的PATH实用程序。如果没有jq ，系统将压缩动态候选对象；静态子命令和选项名称完成仍然适用于所有四种 Shell。

警告：

每次升级 CLI 或工具后重新运行补全

补全脚本是运行uip completion时已知子命令和选项名称的静态快照。在npm install -g @uipath/cli@<new-version> 、 uip tools install <new-tool>或uip tools update之后，重新运行uip completion ，以便将新添加的命令和标志编入索引：

uip completion              # interactive — refreshes the existing block
uip completion zsh >> ~/.zshrc   # or pipe into the rc file directly

如果不刷新，新动词（例如，在工具次要版本中添加的动词）即使在命令行中工作，也将不会自动完成。

平台说明

Windows

从PowerShell 、 Windows 终端或cmd运行命令。如果在安装后无法识别uip ，请打开一个新的终端窗口，以便更新的PATH生效，或运行：

npm config get prefix

并确认返回的目录在您的PATH中。

macOS 和 Linux

大多数包管理器会将uip可执行文件放置在默认的PATH上。如果您将 npm 全局安装到用户本地目录中（按照建议 — 避免sudo ），请确保该目录位于您的PATH上。例如，使用~/.npm-global前缀：

export PATH="$HOME/.npm-global/bin:$PATH"

将此行添加到您的 Shell 配置文件（ ~/.zshrc 、 ~/.bashrc等）中，以将其保留。

位于公司代理后面

UiPath CLI 在 CLI 本身和工具自动安装中遵循标准 HTTP 代理环境变量：

变量	用途
HTTP_PROXY / http_proxy	用于 HTTP 请求的代理
HTTPS_PROXY / https_proxy	HTTPS 请求代理
NO_PROXY / no_proxy	绕过代理的主机的逗号分隔列表

示例:

# macOS / Linux
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal.corp
uip login

# Windows PowerShell
$env:HTTPS_PROXY = "http://proxy.example.com:8080"
$env:NO_PROXY = "localhost,127.0.0.1,.internal.corp"
uip login

:: Windows cmd
set HTTPS_PROXY=http://proxy.example.com:8080
set NO_PROXY=localhost,127.0.0.1,.internal.corp
uip login

通过在 URL 中包含凭据来支持代理进行基本身份验证： http://user:[e-mail]:8080 。

提示：

CLI 捆绑了代理感知fetch实现，因此无需在 Node.js 上进行额外配置即可实现HTTPS_PROXY / HTTP_PROXY

遥测

UiPath CLI 向 UiPath 发送匿名使用情况遥测数据，以帮助改进产品。不会传输任何命令参数、文件内容或凭据。

变量	行为
UIPATH_TELEMETRY_DISABLED	设置为1或true以选择退出。
UIPATH_AI_CONNECTION_STRING	覆盖 Application Insights 连接字符串 — 例如，将遥测路由到您自己的实例。

# Opt out for the current shell
export UIPATH_TELEMETRY_DISABLED=1

# Or just for one command
UIPATH_TELEMETRY_DISABLED=1 uip login

在 CI/CD 中安装

作为管道中的一个步骤安装 CLI。由于uip未预安装工具，因此可以让工具在首次使用时自动安装，或显式预安装——后者在无状态运行程序上速度更快，因为每个步骤下载一次工具，而非每个命令下载一次。

GitHub 操作

steps:
  - uses: actions/setup-node@v4
    with:
      node-version: '20'

  - name: Install UiPath CLI
    run: npm install -g @uipath/cli

  - name: Pre-install tools
    run: uip tools install @uipath/orchestrator-tool @uipath/solution-tool

  - name: Authenticate
    run: uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET
    env:
      UIPATH_CLIENT_ID: ${{ secrets.UIPATH_CLIENT_ID }}
      UIPATH_CLIENT_SECRET: ${{ secrets.UIPATH_CLIENT_SECRET }}

  - name: Run CLI commands
    run: uip or folders list --output json

Azure DevOps

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'
    displayName: 'Use Node.js 20'

  - script: npm install -g @uipath/cli
    displayName: 'Install UiPath CLI'

  - script: uip tools install @uipath/orchestrator-tool @uipath/solution-tool
    displayName: 'Pre-install UiPath CLI tools'

  - script: uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET
    displayName: 'Authenticate'
    env:
      UIPATH_CLIENT_ID: $(UIPATH_CLIENT_ID)
      UIPATH_CLIENT_SECRET: $(UIPATH_CLIENT_SECRET)

Jenkins （声明性管道）

stage('Install UiPath CLI') {
  steps {
    sh 'npm install -g @uipath/cli'
    sh 'uip tools install @uipath/orchestrator-tool @uipath/solution-tool'
  }
}

stage('Authenticate') {
  steps {
    withCredentials([
      string(credentialsId: 'UIPATH_CLIENT_ID', variable: 'UIPATH_CLIENT_ID'),
      string(credentialsId: 'UIPATH_CLIENT_SECRET', variable: 'UIPATH_CLIENT_SECRET')
    ]) {
      sh 'uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET'
    }
  }
}

有关完整管道示例，包括“打包”、“发布”和“测试”阶段，请参阅CI/CD 秘钥。

提示：

在内部版本之间缓存 npm 全局目录，以避免在每次运行时重新安装@uipath/cli及其工具。在 GitHub Actions 上，使用actions/cache键入已固定的 CLI 版本。

从 GitHub npm 注册表安装

@uipath/*工具包的子集（当前为@uipath/rpa-tool和@uipath/flow-tool ）发布到GitHub npm 注册表( https://npm.pkg.github.com )，而不是公共 npm 注册表。在uip tools install解决问题之前，将 npm 配置为通过 GitHub 注册表路由@uipath作用域。

使用以下内容创建（或更新） ~/.npmrc （用户级）或./.npmrc （项目级）：

@uipath:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

GITHUB_TOKEN至少需要read:packages作用域；对于未经身份验证的公共 GitHub 包拉取，可以省略令牌行（每个包的行为各不相同 — 请查看存储库的可见性）。

export GITHUB_TOKEN=<your-pat>
npm install -g @uipath/cli
uip tools install @uipath/rpa-tool

配置后， uip tools install和uip tools update会采用与选取公开包相同的方式选取 GitHub 注册的包。

备注：

主机包@uipath/cli本身位于公共 npm 注册表中。只有在发行说明中标记为已在 GitHub 注册的工具才需要额外的.npmrc 。

以未全局安装的方式运行

对于临时使用或不希望全局安装的管道，您可以通过npx运行 CLI：

npx -y @uipath/cli <command>

例如：

npx -y @uipath/cli login
npx -y @uipath/cli or folders list

第一次调用将下载包；后续调用将重用 npm 缓存。

升级

使用用于安装包的相同命令重新安装包，选择最新版本或固定版本：

# latest release
npm install -g @uipath/cli@latest

# pinned version
npm install -g @uipath/cli@1.0.0

等效的 pnpm 命令为pnpm add -g @uipath/cli@latest 。

提示：

在 CI 中固定确切版本。 @uipath/cli遵循语义版本控制，但 JSON 输出中Data的形式特定于命令，并且可能在次要版本之间发生变化（请参阅版本控制和稳定性）。“固定”可以避免解析 JSON 的管道在构建时出现意外。冲突时，请重新验证依赖特定字段名称的脚本。

有关版本之间的更改，请参阅发行说明。

升级主机不会自动升级已安装的工具。要更新工具：

uip tools update                        # update all installed tools
uip tools update --name <package>       # update a single tool
uip tools update --name <package> --version <version>   # pin to a specific version

默认情况下，每个工具版本都会跟踪 CLI 的 MAJOR.MINOR 行，因此在 CLI 升级后运行uip tools update可使每个已安装的工具保持一致。有关固定合同，请参阅工具（插件） 。

卸载

使用用于安装 CLI 的包管理器删除 CLI：

npm uninstall -g @uipath/cli
# or
pnpm remove -g @uipath/cli

这将删除uip可执行文件和已安装的工具。

移除凭据和数据

卸载包会留下一些磁盘状态。当您想要重新开始或需要停用计算机时，请手动清理它们。

会话凭据

默认情况下， uip login会将会话保留在主目录的~/.uipath/中。当 CLI 启动时，它会首先从当前目录开始查找.uipath/文件夹，因此项目文件夹可以在无需修改用户主目录的情况下进行会话。清理时检查这两个位置：

# macOS / Linux
rm -rf ~/.uipath

# Windows PowerShell
Remove-Item -Recurse -Force "$env:USERPROFILE\.uipath"

还要查看您在本地.uipath/工作过的每个项目。有关完整布局，请参阅会话和凭据。

Shell 补全

如果您运行的是uip completion ，则卸载后，补全块仍位于 shell rc 文件中。在卸载@uipath/cli之前将其删除，或使用~/.zshrc 、 ~/.bashrc或$PROFILE手动将其清理：

# Before uninstalling, while uip is still available:
uip completion --uninstall

npm 全局缓存

npm 在npm config get cache报告的路径上保留下载的 tarball 的本地缓存。对于大多数用户而言，无需清理此内容；仅出于恢复磁盘空间或对下载损坏的故障进行故障排除的目的而清理：

npm cache clean --force

故障排除

uip：安装后未找到命令

npm 全局目录不在您的PATH上。运行npm config get prefix以查看 npm 将uip启动器放置的位置，然后将该目录的bin子文件夹添加到PATH并打开一个新终端。

EACCES 或安装时出现权限错误

在 macOS 和 Linux 上，避免sudo npm install 。将 npm 配置为使用用户本地前缀一次：

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
export PATH="$HOME/.npm-global/bin:$PATH"

然后重新安装： npm install -g @uipath/cli 。

工具自动安装挂起或超时

您使用的代理可能会阻止 npm。按照在公司代理后面所述配置HTTPS_PROXY ，或在可以访问互联网的计算机上预安装工具，并将全局node_modules复制到目标计算机。

节点版本过旧

uip需要 Node.js 18 或更高版本。升级 Node.js 或使用nvm use 20切换版本。

有关更多错误及其解决方案，请参阅故障排除。

后续步骤

• 快速入门— 登录、列出 Orchestrator 文件夹并在五分钟内运行作业。
• 您的第一个管道— 打包项目并从 CI 进行部署。
• 身份验证— 适用于 CI 的交互式登录、外部应用程序客户端凭据和环境变量身份验证。
• 将 UiPath CLI 与 Coding Agents 结合使用— 将技能安装到 Claude Code、Cursor、GitHub Copilot 或 Gemini CLI 中。