# Migration from the .NET CLI

> UiPath CLI 1.x (`uip`, distributed on npm as `@uipath/cli`) replaces the legacy .NET CLI (`uipcli.exe`, distributed as `UiPath.CLI` through calendar releases `2023.10`, `2024.10`, and `2025.10`). This page explains who should migrate, what changes at the tooling level, and how to navigate the four detail pages below.

UiPath CLI 1.x (`uip`, distributed on npm as `@uipath/cli`) replaces the legacy .NET CLI (`uipcli.exe`, distributed as `UiPath.CLI` through calendar releases `2023.10`, `2024.10`, and `2025.10`). This page explains who should migrate, what changes at the tooling level, and how to navigate the four detail pages below.

If you only want the flag-for-flag answer to "what do I type instead of `uipcli <verb>`?", jump to [Command map](./migration-command-map.md) and [Flag renames](./migration-flag-renames.md).

## Who this guide is for

You should migrate if any of the following apply:

- Your pipeline calls `uipcli.exe` — directly, through `UiPathCLI` Azure DevOps task, or from a Jenkins / GitHub Actions shell step.
- You pin the legacy CLI to a calendar version (`2023.10`, `2024.10`, `2025.10`) and have been tracking its yearly cadence.
- You use user/password authentication (`-u`/`-p`) or refresh-token authentication (`-t`/`-a`) against Orchestrator.
- You build a `.nupkg` with `uipcli package pack`, deploy with `uipcli package deploy`, or run Orchestrator tests with `uipcli test run`.

You can stay on the legacy CLI for now if you need a Windows-only feature that has not yet been ported to the cross-platform `uip rpa` tool (Studio debugger integration, `validate`, `find-package`, `find-activities`, `type-definition`). A sibling `uip rpa-legacy` tool wraps the 2025.10 binary on Windows; see [uip rpa — Windows-only legacy wrapper](./uip-rpa.md). Everything else — packaging on Linux/macOS, Orchestrator operations, Solutions, Test Manager, Agents, Flows, Maestro — is in `uip` today.

## What changes at a glance

| Dimension | Legacy `uipcli` (through 2025.10) | `uip` 1.x |
|---|---|---|
| Binary name | `uipcli.exe` / `uipcli.dll` | `uip` |
| Distribution | MSI, NuGet (`UiPath.CLI`, `UiPath.CLI.Windows`) | npm (`@uipath/cli`) |
| Runtime | .NET 6 / .NET Framework | Node.js 18+ |
| Platform | Windows (primary), Linux via cross-plat NuGet | Windows, macOS, Linux, ARM64 |
| Versioning | Calendar (`2023.10`, `2024.10`, `2025.10`) | Semantic (`1.0.0`, `1.1.0`, `2.0.0`) |
| Install model | Monolithic | Host + per-surface tool plugins (see [Tools](./concepts-tools.md)) |
| Default output | Text logs to stdout + exit code | JSON envelope on stdout, logs on stderr |
| Primary auth flows | user/pass, refresh token, external app | external app (CI), interactive OAuth (dev), env-token (container) |
| Configuration | CLI flags only | Flags + environment variables (see [Configuration](./configuration.md)) |

See [What's new](./whats-new.md) for the rewrite summary.

## Which CLI version am I on?

Run `uipcli --version` (or `dotnet uipcli.dll --version`). The output looks like `23.10.8817.35919`, `24.10.9248.xxxxx`, or `25.10.xxxx.xxxxx`. The migration paths below cover all three.

| You are running | Where to go |
|---|---|
| `uipcli 23.10.*` | Read this whole page, then [Command map](./migration-command-map.md) + [Flag renames](./migration-flag-renames.md). `deploy` and `asset deploy` verbs you use are all mapped. |
| `uipcli 24.10.*` | Same as 23.10 — the command surface barely changed. If you adopted the `solution` verb added in 24.10, every subcommand is mapped. |
| `uipcli 25.10.*` | Same as above. `test parallel` and the multi-entry-point `--processNames <csv>` deploy form have specific migration notes in [Command map](./migration-command-map.md). |
| Using `uipcli run <args.json>` | See [Command map — run](./migration-command-map.md#run) — the new CLI has no direct equivalent; the recommended pattern is a shell script with one `uip` invocation per step. |

## Decision table — pick your starting point

| Your use case on `uipcli` | Migration target | Detail page |
|---|---|---|
| Pack a Studio project → upload to Orchestrator → create a process | `uip rpa pack` → `uip or packages upload` → `uip or processes create` | [Command map — package](./migration-command-map.md#package) |
| Pack and deploy a **Solution** (`.uipx`) | `uip solution pack` → `uip solution publish` → `uip solution deploy run` | [Command map — solution](./migration-command-map.md#solution), [first pipeline](./first-pipeline.md) |
| Start an Orchestrator job | `uip or jobs start <process-key> [--wait-for-completion]` | [Command map — job](./migration-command-map.md#job) |
| Run a Test Manager test set | `uip tm testsets run` → `uip tm wait` → `uip tm report get` | [Command map — test](./migration-command-map.md#test) |
| Deploy CSV-declared assets | `uip resource assets create` in a loop (no one-shot CSV deploy today) | [Command map — asset](./migration-command-map.md#asset) |
| Run the workflow analyzer | `uip rpa analyze <project> --governance-file-path <policy>` | [Command map — analyze](./migration-command-map.md#package-analyze) |
| Authenticate a CI pipeline | `uip login --client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET --tenant <name>` | [Flag renames — auth](./migration-flag-renames.md#authentication) |
| Port an Azure DevOps / Jenkins pipeline | Replace `UiPathCLI` task blocks with `uip` shell steps | [Pipeline examples](./migration-pipelines.md) |

## Most common breaking changes

These three appear in nearly every migration. See [Breaking changes](./migration-breaking-changes.md) for the full list.

1. **Basic (`-u`/`-p`) and refresh-token (`-t`/`-a`) auth are gone.** Only External Application client credentials, interactive OAuth2, and environment-variable access tokens are supported. See [Authentication](./authentication.md).
2. **`UIPATH_CLIENT_ID` / `UIPATH_CLIENT_SECRET` are no longer read implicitly.** Pass them as `--client-id env.UIPATH_CLIENT_ID --client-secret env.UIPATH_CLIENT_SECRET` (the `env.` prefix reads the variable without exposing it on the command line).
3. **Stdout is JSON by default.** Legacy shell scripts that parsed `uipcli` text output need to use `jq` (or `--output plain` + `--output-filter`) or switch to `--output table` for human reading.

## Before you start

Complete these four steps before you start porting a pipeline.

### 1. Back up your current pipeline files

Commit a known-good copy of every `azure-pipelines.yml`, `Jenkinsfile`, `.github/workflows/*.yml`, or `.gitlab-ci.yml` on a branch (or tag). The port is easier to review as a diff.

### 2. Pin @uipath/cli to a specific version

Always install with an explicit version during migration so pipeline behavior does not change unexpectedly:

```bash
npm install -g @uipath/cli@1.0.0
```

Tools pin implicitly to the CLI's `MAJOR.MINOR` line (see [Versioning](./versioning.md)), so a pinned CLI also pins every tool to a known minor range. For strict patch-level reproducibility, pin tools too — see the "Pinning versions in CI" section of [Scripting patterns](./scripting-patterns.md).

### 3. Bookmark the legacy .NET CLI docs

Cross-reference flag behavior during the port. The 2025.10 reference lives at [docs.uipath.com — UiPath Command Line Interface (2025.10)](https://docs.uipath.com/test-suite/automation-cloud/2025.10/user-guide/uipath-command-line-interface). Keep it open in a tab.

### 4. Create an External Application in UiPath

The legacy CLI accepted several authentication modes; the new CLI collapses CI authentication to External Application client credentials. Create the app now so the port has something to point at. See [Authentication — Flow 2](./authentication.md#flow-2-external-application-client-credentials).

:::tip
Grant the external app the same scopes your legacy CLI used — `OR.Folders`, `OR.Jobs`, `OR.Execution`, `OR.Assets`, `OR.Users.Read`, `OR.Machines.Read`, `OR.TestSets`, `OR.TestSetExecutions` covers the common CI case. See the `--applicationScope` value from your existing `uipcli` calls for the exact list you need.
:::

## The four detail pages

Each page below is focused enough to review in one sitting. Work through them in order if you're porting a full pipeline; jump straight to the one you need if you only want a specific answer.

### [Command map](./migration-command-map.md)

Every legacy verb — `package pack`, `package analyze`, `package deploy`, `package restore`, `job run`, `test run`, `test parallel`, `asset deploy`, `asset delete`, `solution pack`, `solution deploy`, `run` — with its `uip` equivalent, a 1:1 / multi-step / removed classification, and a before/after shell snippet for every non-trivial row.

### [Flag renames](./migration-flag-renames.md)

Flag-level mapping with the auth block at the top. Legacy `-u`/`-p`/`-t`/`-a`/`-A`/`-I`/`-S`/`-o`/`--applicationScope`/`--identityUrl`/`--outputType`/`--traceLevel` mapped to their `uip` counterparts (or called out as removed, with the replacement). Read this alongside the Command map — the Command map shows the verb, Flag renames shows the flag.

### [Breaking changes](./migration-breaking-changes.md)

Prose coverage of the changes that break pipelines without warning. Auth mode removals, env-var auto-reading removal, exit-code contract tightening, JSON-stdout default, calendar-versioned NuGet folders gone, .NET runtime dropped. One paragraph per change with a "what to do" remediation.

### [Pipelines](./migration-pipelines.md)

Before/after snippets for Azure DevOps and Jenkins (required), with shorter GitHub Actions and GitLab CI snippets. Cross-linked to the full [CI/CD recipes](./recipes-azure-devops.md) for complete pipelines.

## See also

- [What's new](./whats-new.md) — headline summary of the rewrite.
- [Your first pipeline](./first-pipeline.md) — hands-on walkthrough of `pack → publish → deploy run` with the new CLI.
- [Authentication](./authentication.md) — the three supported auth flows in 1.x.
- [Exit codes](./exit-codes.md) — the tightened five-tier contract.
- [Tools (plugins)](./concepts-tools.md) — why the command surface is split across npm packages and what auto-installs on first use.