UiPath Documentation
uipath-cli
latest
false
UiPath CLI user guide

uip tools

Syntax and options for `uip tools`, which installs, updates, and removes the npm-based tools that extend UiPath CLI.

uip tools manages the installable tools that extend the CLI. See Tools (plugins) for the concept.

For how to control auto-install on CI runners, see Controlling tool auto-install.

Synopsis​

uip tools list
uip tools search [<query>]
uip tools install <package-spec>
uip tools update [--name <package>]
uip tools uninstall [<package>] [--all]
uip tools list
uip tools search [<query>]
uip tools install <package-spec>
uip tools update [--name <package>]
uip tools uninstall [<package>] [--all]

All uip tools subcommands honor the global options (--output, --output-filter, --log-level, --log-file). Exit codes follow the standard contract.

uip tools list​

List the tools currently installed alongside the CLI.

Arguments​

None.

Options​

None.

Example​

uip tools list --output table
uip tools list --output table

Data shape (--output json)​

{
  "Code": "ToolList",
  "Data": [
    {
      "Name": "orchestrator-tool",
      "Version": "1.2.3",
      "Description": "UiPath Orchestrator Tool",
      "CommandPrefix": "or",
      "Status": "ok"
    },
    {
      "Name": "agent-tool",
      "Version": "1.1.7",
      "Description": "UiPath Agent Tool",
      "CommandPrefix": "agent",
      "Status": "needs update"
    }
  ]
}
{
  "Code": "ToolList",
  "Data": [
    {
      "Name": "orchestrator-tool",
      "Version": "1.2.3",
      "Description": "UiPath Orchestrator Tool",
      "CommandPrefix": "or",
      "Status": "ok"
    },
    {
      "Name": "agent-tool",
      "Version": "1.1.7",
      "Description": "UiPath Agent Tool",
      "CommandPrefix": "agent",
      "Status": "needs update"
    }
  ]
}
FieldDescription
NameTool name.
VersionInstalled version.
DescriptionTool description.
CommandPrefixThe top-level alias you type — for example, or for Orchestrator. Use it to confirm what uip <prefix> … runs.
Statusok when the installed version is on the running CLI's MAJOR.MINOR line. needs update when it is off that line; the CLI replaces the tool with a version on its line the next time you run one of the tool's commands. In an interactive table, needs update rows are highlighted.

Search the UiPath tool catalog for tools you can install. Results are filtered to the allowlisted @uipath/ tools (including rpa-legacy, which requires explicit install). Third-party packages are not returned.

Arguments​

  • <query> (optional) — substring match against package name and description. Without it, all allowlisted tools are listed.

Options​

None.

Example​

uip tools search orchestrator
uip tools search orchestrator

Data shape (--output json)​

{
  "Code": "SearchResult",
  "Data": [
    {
      "Name": "@uipath/orchestrator-tool",
      "LatestVersion": "1.2.3",
      "Description": "Manage UiPath Orchestrator resources from the CLI",
      "AvailableVersions": ["1.2.3", "1.2.2", "1.2.1"]
    }
  ]
}
{
  "Code": "SearchResult",
  "Data": [
    {
      "Name": "@uipath/orchestrator-tool",
      "LatestVersion": "1.2.3",
      "Description": "Manage UiPath Orchestrator resources from the CLI",
      "AvailableVersions": ["1.2.3", "1.2.2", "1.2.1"]
    }
  ]
}

Search reads from the npm registry configured for the @uipath scope (typically https://registry.npmjs.org/ via the default npm config, or an overridden registry set in your .npmrc). Results are filtered client-side against the allowlist, so any @uipath/ package that is not on the allowlist is omitted.

uip tools install​

Install an allowlisted tool from the npm registry. The CLI resolves the version from whichever registry npm's own configuration sets for the @uipath scope (a scoped @uipath:registry entry in .npmrc, otherwise npm's default registry).

Arguments​

  • <package-spec> (required) — the tool to install. Any of:
    • Command alias: or, solution, tm, is, vss, df, …
    • Short name: orchestrator-tool, solution-tool, …
    • Full npm name: @uipath/orchestrator-tool, @uipath/solution-tool, …
    • With explicit version: orchestrator-tool@1.0.2, @uipath/orchestrator-tool@1.0.2. The value after @ must be a valid semver string (e.g. 1.0.2 or 1.0.0-preview.1) — a bare channel name like @beta is rejected with a ValidationError.

Options​

None.

Examples​

# by alias — simplest
uip tools install or

# by short name
uip tools install orchestrator-tool

# by full npm name
uip tools install @uipath/orchestrator-tool

# specific version
uip tools install orchestrator-tool@1.0.2

# exact preview build
uip tools install orchestrator-tool@1.0.0-preview.1

# preview channel — switch the channel, then install normally
uip config set updateChannel preview
uip tools install orchestrator-tool
# by alias — simplest
uip tools install or

# by short name
uip tools install orchestrator-tool

# by full npm name
uip tools install @uipath/orchestrator-tool

# specific version
uip tools install orchestrator-tool@1.0.2

# exact preview build
uip tools install orchestrator-tool@1.0.0-preview.1

# preview channel — switch the channel, then install normally
uip config set updateChannel preview
uip tools install orchestrator-tool

Version resolution​

  • With an explicit semver version (e.g. @1.0.2 or @1.0.0-preview.1), that version is used as-is. There is no npm-dist-tag shorthand like @beta — the value after @ must parse as semver, or the command fails with a ValidationError.
  • Without a version, the host resolves against the CLI's update channel (stable by default, or preview/dev via uip config set updateChannel <channel>) and its current MAJOR.MINOR line — so a stable CLI 1.0.x installs the latest matching stable tool 1.0.*. This keeps host and tool protocol-compatible. See Versioning and stability and uip config.

Install target: the tool is installed next to the CLI's npm package — globally if the CLI is a global install, locally if the CLI is a project-scoped install. You do not pass a scope flag. Run npm root -g to find the global install path on your machine.

Allowlist enforcement: <package-spec> must resolve to one of the allowlisted @uipath/ packages (or rpa-legacy). Any other value fails with ValidationError and exit code 3 — third-party tools are not supported in 1.x.

Data shape (--output json)​

{
  "Code": "Message",
  "Data": { "Message": "Successfully installed @uipath/orchestrator-tool@1.2.3" }
}
{
  "Code": "Message",
  "Data": { "Message": "Successfully installed @uipath/orchestrator-tool@1.2.3" }
}

Failures​

When no version can be resolved for the CLI's line, the failure envelope carries an ErrorCode that names the cause. When npm's configuration can be read, the message also names the registry that was queried.

ErrorCodeCauseWhat to do
authentication_requiredThe registry rejected the credentials.Fix that registry's credentials in .npmrc, then re-run.
network_errorThe registry could not be reached.Check network access and any proxy or registry configuration in .npmrc, then re-run.
not_foundThe registry has no version of the tool on the CLI's MAJOR.MINOR line.Install a build for this line with uip tools install <tool>@<version>, run uip update to move the CLI onto a line that publishes the tool, or point the @uipath scope at the registry that publishes it.
server_errorThe registry returned metadata the CLI could not read.Re-run. If it persists, check whether a proxy or mirror is rewriting the response.

uip tools update​

Update one or more installed tools to the latest compatible version.

Arguments​

None.

Options​

  • --name <package> — update a single tool. Accepts alias, short name, or full npm name. Without --name, every installed tool is updated.
Important:

There is no --version flag on uip tools update — only --name is registered. Every tool updates to the latest version allowed by the active version policy (normally pinned to the CLI's MAJOR.MINOR line); to pin a specific version instead, use uip config set version <line> or reinstall with an explicit version via uip tools install <package>@<version>.

Examples​

# update every installed tool to the latest version within the CLI's major.minor line
uip tools update

# update just the Orchestrator tool
uip tools update --name or
# update every installed tool to the latest version within the CLI's major.minor line
uip tools update

# update just the Orchestrator tool
uip tools update --name or

Data shape (--output json)​

{
  "Code": "UpdateResult",
  "Data": [
    {
      "Name": "orchestrator-tool",
      "Status": "updated",
      "From": "1.2.2",
      "To": "1.2.3"
    },
    {
      "Name": "agent-tool",
      "Status": "up-to-date",
      "From": "1.2.3",
      "To": "1.2.3"
    }
  ]
}
{
  "Code": "UpdateResult",
  "Data": [
    {
      "Name": "orchestrator-tool",
      "Status": "updated",
      "From": "1.2.2",
      "To": "1.2.3"
    },
    {
      "Name": "agent-tool",
      "Status": "up-to-date",
      "From": "1.2.3",
      "To": "1.2.3"
    }
  ]
}

Status is updated or up-to-date. If any tool fails to update, the command emits a Failure envelope naming the number of tools that failed, and exits with code 1. Run with --log-level debug to see the per-tool error.

If core.version is pinned to an exact version (not a MAJOR.MINOR line), the update is skipped entirely — the command still exits 0 with an empty Data array and an Instructions note explaining the pin, since a pinned installation intentionally never moves.

uip tools uninstall​

Remove one installed tool, or every installed tool at once.

Arguments​

  • [package-name] (optional) — alias, short name, or full npm name. Mutually exclusive with --all. Provide exactly one of the argument or --all — omitting both, or passing both, is a ValidationError.

Options​

  • --all — uninstall every installed tool. Mutually exclusive with [package-name].

Examples​

# uninstall a single tool
uip tools uninstall orchestrator
uip tools uninstall @uipath/solution-tool

# uninstall every installed tool
uip tools uninstall --all
# uninstall a single tool
uip tools uninstall orchestrator
uip tools uninstall @uipath/solution-tool

# uninstall every installed tool
uip tools uninstall --all

Data shape (--output json)​

Uninstalling a single tool emits Code: "Message":

{
  "Code": "Message",
  "Data": { "Message": "Successfully uninstalled @uipath/orchestrator-tool" }
}
{
  "Code": "Message",
  "Data": { "Message": "Successfully uninstalled @uipath/orchestrator-tool" }
}

--all emits Code: "UninstallResult" with one row per tool:

{
  "Code": "UninstallResult",
  "Data": [
    { "Name": "orchestrator-tool", "Status": "uninstalled" },
    { "Name": "agent-tool", "Status": "uninstalled" }
  ]
}
{
  "Code": "UninstallResult",
  "Data": [
    { "Name": "orchestrator-tool", "Status": "uninstalled" },
    { "Name": "agent-tool", "Status": "uninstalled" }
  ]
}

Status is uninstalled, skipped for a tool that ships with the CLI itself, or failed. Skipped and failed rows carry an Error field. If any tool fails to uninstall in the --all path, the command exits with code 1 — the full per-tool breakdown is still emitted.

After uninstall, invoking uip or … will auto-install the Orchestrator tool again on next use, unless auto-install is blocked (for example, on a runner without network access). Install explicitly to avoid that.

Exit codes​

  • 0 — success.
  • 1 — failure (install, update, uninstall, or a tool-level error). For update with multiple tools, at least one failed.
  • 3 — validation error (unknown alias, non-allowlisted package, invalid version string) on install and update.

uninstall's own argument-validation errors (missing package name, or --all combined with a package name) exit 1 rather than 3, even though the response body still reports Result: "ValidationError" — branch on Result/ErrorCode in the JSON body rather than the exit code if you need to distinguish this case from other failures.

See Exit codes for the full table.

See also​

Was this page helpful?

Connect

Need help? Support(opens in new window)

Want to learn? UiPath Academy(opens in new window)

Have questions? UiPath Forum(opens in new window)

Stay updated