Migration: breaking changes

Semantic changes that break pipelines in ways that a flag-for-flag port would not catch. Read this page before you port; the Command map and Flag renames handle the mechanical rename work.

Every change below has the same structure: what changed, why it changed, what to do. Skim the bold first-lines and dig in where your pipeline is affected.

Auth modes removed

What changed. Legacy uipcli accepted three authentication modes per command: user/password (-u/-p), refresh token (-t/-a), and External Application (-A/-I/-S/--applicationScope). The new CLI accepts only External Application client credentials (for CI), interactive OAuth2 (for developers), and environment-variable access tokens (for containers). User/password and refresh-token authentication are gone — the flag letters -u, -p, -t, -a are either unassigned (-u, -p, -a) or repurposed (-t is now --tenant).

Why. Automation Cloud has deprecated the user/password and refresh-token flows for new workloads. External Application credentials are the only flow that scales cleanly across CI runners, support org-level audit, and can be revoked without rotating a human account.

What to do. Create an External Application in UiPath with the same scopes your pipeline currently lists under --applicationScope, then replace every per-command auth block with a single uip login call:

# 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"

See Authentication for the full flow catalog. The Authentication section of Flag renames lists every removed flag.

Implicit env-var auth reading removed

What changed. Legacy uipcli would implicitly read UIPATH_CLIENT_ID and UIPATH_CLIENT_SECRET from the environment when corresponding flags were absent. The new CLI does not — environment variables are read only when you explicitly reference them through the env.VAR_NAME prefix on --client-id / --client-secret, or through the UIPATH_CLI_ENABLE_ENV_AUTH=true access-token flow.

Why. Implicit reads made it impossible to tell from a pipeline step alone which secrets the command depended on. The explicit env. prefix form surfaces the dependency in the invocation itself, which makes auditing, rotation, and secret scanning reliable.

What to do. Replace any implicit reliance on the env vars with explicit env. references:

# 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"

The env. form reads the variable at runtime without expanding it onto the command line, so the secret does not appear in shell history or ps output — a safer pattern than the legacy implicit read. See Authentication — the env.VAR_NAME prefix.

Calendar-versioned releases are gone

What changed. Legacy shipped as calendar versions (2023.10, 2024.10, 2025.10) on NuGet (UiPath.CLI, UiPath.CLI.Windows), with folder layouts like .../UiPath.CLI.25.10.xxxx/tools/uipcli.dll. The new CLI is distributed on npm as @uipath/cli with semantic versioning (1.0.0, 1.0.1, 1.1.0, 2.0.0).

Why. Calendar versioning communicates release date but not compatibility. Semver communicates compatibility: 1.0.x → 1.1.x is additive, 1.x → 2.x is breaking and preceded by a deprecation cycle. Host + tool packages also coordinate on semver — tool versions pin to the CLI's MAJOR.MINOR line automatically.

What to do. Remove every reference to calendar-versioned NuGet packages, uipcli.dll paths, and yearly folder names from pipelines. Install with npm, pin with @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 ...

See Installing UiPath CLI and Versioning and stability for the full semver contract.

Runtime change: Node.js 18+ replaces .NET as the CLI runtime; rpa-tool keeps a .NET dependency

What changed. Legacy uipcli ran entirely on .NET (UiPath.CLI required .NET 6 cross-platform; UiPath.CLI.Windows used .NET Framework). The new uip host is a Node.js program — every invocation requires Node.js 18 or later on the runner, regardless of which tools are used. The host itself has no .NET dependency, and most tools (Orchestrator, Solution, Agent, Flow, Maestro, Test Manager, Integration Service, Data Fabric, Insights, Traces, DocsAI) make HTTPS calls only and add nothing further.

The RPA tool (@uipath/rpa-tool, invoked as uip rpa pack / analyze / restore) is the exception. It wraps the Studio packager and the workflow compiler, both of which are .NET-backed. Pipelines that run uip rpa … commands need a .NET runtime in addition to Node.js, not in place of it. See uip rpa reference for the current prerequisites.

Why. The core CLI moved to Node for a smaller, more portable runtime footprint, simpler cross-platform distribution, and a single-registry (npm) story. The RPA-specific surface kept its .NET backend because the Studio packager and analyzer are native .NET — rewriting them was out of scope for 1.0.

What to do.

1. Always provision Node.js 18+ on the runner. This is required for uip itself; without Node, no uip command runs.

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

2. If your pipeline calls uip rpa pack, uip rpa analyze, or uip rpa restore, also keep a .NET runtime available on the runner. You no longer install the legacy uipcli via dotnet tool install, but the .NET runtime itself still has to be present so rpa-tool can invoke the Studio packager.

3. If your pipeline does not call uip rpa …, remove the .NET / dotnet-sdk setup step. The remaining tools (Orchestrator, Solution, Agent, Flow, Maestro, Test Manager, etc.) do not need it.

See Installing UiPath CLI — CI/CD.

Exit-code contract tightened

What changed. Legacy uipcli emitted a wider range of exit codes, often mixing .NET process-level codes (1-3 digits, framework-specific) with command-level codes. The new CLI emits exactly five canonical codes (0, 1, 2, 3, 4) plus 130 for user cancellation, and the mapping from result to code is stable within a MAJOR release.

Exit code	Significado
0	Success.
1	Generic failure or configuration error.
2	Authentication error (401 / 403).
3	Validation error (bad flag, unknown option, mutually-exclusive flags).
4	Timeout error. Reserved; no command emits it in 1.x.
130	User cancelled (Ctrl+C).

One domain-specific reuse: uip tm wait returns 2 on timeout (so scripts can distinguish timeout from the authentication slot). Otherwise the contract is uniform.

Why. A small, stable set of codes makes CI retry/escalation logic straightforward: 2 means "re-auth, then retry"; 3 means "never retry, fix the command"; 1 means "retry once if transient". The legacy wide range required pipelines to handle each command's codes individually.

What to do. Replace code-specific branches with the new five. If your pipeline has logic like "retry on any non-zero code", tighten it to retry on 1 only:

# 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

Note: uip tm testset execute always exits 0 once Test Manager accepts the run request. Failures come through uip tm wait + uip tm report get with Data.Failed, not the exit code of execute. See Exit codes. The uip tm wait page documents its exit-code semantics.

Stdout is JSON by default

What changed. Legacy uipcli wrote human-readable log text to stdout; exit code and any produced files were the only machine-readable outputs. The new CLI writes a JSON envelope to stdout by default on every command:

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

Logs, progress, and human-facing errors go to stderr, regardless of --output value. Human-readable table view is opt-in with --output table.

Why. JSON-first output means every command is scriptable without parsing tricks, and the same invocation works identically in a terminal and a pipeline. Logs on stderr means a pipeline can cleanly command > payload.json 2> log.txt.

What to do. Any shell step that grepped uipcli text output must switch to one of:

• --output-filter "<JMESPath>" --output plain — extract a single field as plain text. Example: --output-filter "Data.Key" --output plain.
• jq — parse the full envelope.
• --output table — display-only; do not parse table output.

# 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)

See Output formats. The --output-filter flag itself is documented on Global options.

Tenant and Orchestrator URL are session state, not per-command flags

What changed. Legacy uipcli took <orchestrator_url> and <orchestrator_tenant> as positional arguments on every verb (job run "<name>" "<url>" "<tenant>" ...). The new CLI resolves both from the authenticated session written by uip login; no positional URL is ever needed, and the tenant is a session default that each command can override with -t, --tenant <name>.

Why. Every command in a pipeline typically targets the same Orchestrator; passing the URL and tenant on each call was repetitive and invited copy-paste errors. Session state with per-call override is the standard CLI pattern (cf. az account set, gcloud config set, kubectl config use-context).

What to do. Drop the positional URL and tenant from every command. Set the tenant at login (or override per-call with -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"

For multi-tenant scripts, pass -t TENANT on any command that needs a different tenant for that one call. See Authentication — manage tenants mid-session.

Classic-folder concepts are deprecated on the CLI surface

What changed. Legacy CLI carried several classic-folder-only flags: -e, --environments <csv> on package deploy, -r, --robots <csv> on job run, and related environment-based routing. The new CLI targets the modern folder model exclusively on its public verbs. Classic folders still exist on Orchestrator, but uip does not expose classic-specific flags.

Why. Modern folders have been the default since 2020. Keeping classic-only flags on the new CLI would have meant carrying deprecated behavior into a fresh release.

What to do. If your pipeline targets a classic folder, either (a) migrate the folder to modern (Orchestrator admin surface), or (b) keep using uipcli for those specific calls through the @uipath/rpa-legacy-tool wrapper. See uip rpa — Windows-only legacy wrapper.

Language / locale flag removed

What changed. Legacy -l, --language <locale> translated log output into the given locale. The new CLI emits logs in English only.

Why. Log messages are intended to be consumed by operators and log-shipping systems, both of which standardize on English. Localization was a cost without clear payoff for the CLI layer.

What to do. Remove -l / --language flags from the pipeline. No replacement is needed.

Capture-and-replay (--captureCommandToJsonFile + uipcli run) removed

What changed. Legacy had a hidden --captureCommandToJsonFile <path> flag that serialized the current invocation to JSON, and a uipcli run <file> verb that consumed that JSON to replay the command. Both are removed.

Why. The pattern was mostly used to debug how the GUI task in Azure DevOps mapped to CLI flags, not as a production mechanism. The new CLI's JSON-stdout default and JMESPath filtering cover the debugging use case without a separate subsystem.

What to do. Rewrite any pipeline step that used uipcli run <file> as a direct uip invocation. If you depended on --captureCommandToJsonFile for debugging, the new equivalent is uip <command> --log-level debug --log-file ./uip.log — the log file contains every HTTP call, auth refresh, and tool load.

Telemetry opt-out environment variable renamed

What changed. Both generations ship with anonymous telemetry opt-out by default — telemetry is on unless you disable it explicitly. The env var name has changed:

Generación	Variable	Value to disable
Legado uipcli	UIPATH_EXTENSIONS_CLI_TELEMETRY_ENABLED	False
Nuevo uip	UIPATH_TELEMETRY_DISABLED	1 o true

Why. The new name is shorter, follows the <SCOPE>_DISABLED pattern used elsewhere in the CLI, and drops the EXTENSIONS_ prefix (the new CLI is not an extension of anything).

What to do. Update CI runners and dev machines that already set UIPATH_EXTENSIONS_CLI_TELEMETRY_ENABLED=False to instead set UIPATH_TELEMETRY_DISABLED=1. The legacy variable is ignored by the new CLI, so a machine that sets only the old name will send telemetry again until the new one is added. See What's new — Other meaningful shifts.

Ver también

• Command map — what verb to call.
• Flag renames — flag-by-flag mapping.
• Pipeline examples — before/after YAML for the common CI platforms.
• Exit codes — the five-tier contract.
• What's new — positive summary of every rewrite highlight.