Versioning and stability

UiPath CLI 1.0.0 follows semantic versioning (MAJOR.MINOR.PATCH). This replaces the calendar-based scheme (2023.10, 2024.10, 2025.10) used by the legacy .NET CLI. This page is the contract — what you can rely on from one release to the next, what can change, and how host and tool versions stay in step.

What semver means in practice

Bump	When it happens	What can change
MAJOR (1.x.x → 2.0.0)	Breaking changes to command names, flag semantics, or the JSON envelope.	Commands may be renamed or removed; flags may be renamed or have their meaning altered; the envelope's top-level fields may change shape. A full deprecation cycle precedes any MAJOR release — deprecated commands keep working in the final MINOR of the previous MAJOR.
MINOR (1.0.x → 1.1.0)	New commands, new tools, new flags, new subcommands.	Additive only on the command surface. However, the shape of Data inside the JSON envelope is command-specific and may change — new fields added, occasionally fields renamed or nested. Scripts that parse specific field names should re-validate on a MINOR bump.
PATCH (1.0.0 → 1.0.1)	Bug fixes.	No documented behavior change. A patch that changes behavior is treated as a bug report on the patch itself.

There is no --preview flag (unlike Azure CLI). Preview-status commands are labeled in their reference page and may change within a MINOR release without warning — see Per-command stability below.

The stable contract

The following do not change across MINOR or PATCH versions. Script against them freely.

Envelope fields

Every command emits an envelope on stdout with these top-level fields:

字段	Stability	意义
Result	Stable	Success, Failure, ConfigError, AuthenticationError, ValidationError, TimeoutError.
Code	Stable within MAJOR	Command-specific success identifier (FolderList, SolutionPack, etc.). New codes may appear in MINOR releases for new commands.
Data	Command-specific	Payload shape defined by each command. May add fields in MINOR releases. Rarely, fields may be renamed in MINOR — watch release notes.
Message, Instructions	Stable	Human-readable error text. Content may be improved release-to-release; presence and role do not change.
Context, Log	Stable	Optional fields. Presence conditions are stable.

See Output formats for the envelope in detail.

退出代码

The five-tier exit-code contract (0 / 1 / 2 / 3 / 4 plus 130 for user cancellation) is stable within a MAJOR release. 4 is reserved — no command emits it in 1.x today — but scripts that already handle it will keep working.

Global options

--output, --output-filter, --log-level, --log-file — these four flags are stable across MINOR bumps. New global options may be added; existing ones will not be renamed or removed without a MAJOR release.

Stdout / stderr separation

Stdout is the envelope; stderr is logs, progress, and human-facing error text. This separation holds across every command, every format, every release.

Host and tool versions

The host (@uipath/cli, the uip executable) and each tool (for example, @uipath/orchestrator-tool) are published as independent npm packages, each with its own semver. They are coordinated so that a host at version 1.0.x runs tools at 1.0.x.

Default version resolution

When you run uip tools install <alias> without an explicit version, the host selects the latest tool version whose MAJOR.MINOR matches the CLI's current MAJOR.MINOR line. Upgrading the CLI from 1.0.x to 1.1.0 and then running uip tools update brings every installed tool into the 1.1.x line.

npm install -g @uipath/cli@1.1.0
uip tools update          # all tools → latest 1.1.x

You can override the default for a specific tool:

uip tools install orchestrator-tool@1.0.2
uip tools update --name flow-tool --version 1.1.5

Why the pinning matters

Tools talk to the host through a versioned TypeScript contract (command registration, output formatting, telemetry, context). If the contract changes between MINOR versions, the host and tool must move together. The version-pinning default guarantees they do, without the user having to think about it.

频道

The host recognizes npm dist-tags on tools:

• latest — the stable line (default when no tag is passed).
• beta — preview builds ahead of the stable line.
• alpha — early-access, unstable builds.

uip tools install flow-tool@beta
uip tools update --name flow-tool --version alpha

Channels are tool-level, not host-level. You can mix a stable host with a beta tool for a specific workflow — be aware that the combination is less well-tested.

Per-command stability

Individual commands and flags carry one of three stability labels. Look for them at the top of each command's reference page.

标签	意义
GA (default; unlabeled)	The command is covered by the semver contract above. It will not be renamed or removed within a MAJOR release.
预览	The command is in active development. Flags, defaults, and output shape can change without a MAJOR bump, though breaking changes are rare and announced in release notes. Use in production only when you are prepared to re-validate on each release.
已弃用	The command is scheduled for removal in the next MAJOR release. It continues to work in 1.x and emits a warning on stderr. Use the successor listed in the deprecation note.

This is the same convention gcloud uses. UiPath CLI does not gate Preview commands behind an opt-in flag — they are visible in --help and callable.

Pinning recommendations

For CI pipelines:

# pin host version
npm install -g @uipath/cli@1.0.0

# pin each tool you use
uip tools install @uipath/orchestrator-tool@1.0.2 \
                  @uipath/solution-tool@1.0.1

This gives you a reproducible environment that survives upstream releases. Re-validate after each CLI bump using your pipeline's integration tests; consult the release notes for known Data-shape changes.

For developer workstations:

npm install -g @uipath/cli@latest
uip tools update    # after each CLI upgrade

Less reproducible, more convenient.

Deprecation cycle

When a command or flag is going away, the path is:

1. Announced deprecation — the command is marked Deprecated in its reference page, and the release notes for the MINOR release that introduced the deprecation list it. A replacement is documented.
2. Runtime warning — uip <deprecated-command> ... continues to work but emits a warning on stderr. Scripts that consume stdout are unaffected.
3. Removal in the next MAJOR — the command is removed at the next MAJOR version bump. There is at least one full MAJOR cycle between deprecation and removal — long enough for any pipeline on the supported lifecycle to migrate.

Run uip <command> --help to see whether a command is Deprecated; the label appears in the synopsis.

When the Data shape changes

Because Data is command-specific and can change in MINOR releases, pipelines that extract specific fields (--output-filter "Data.Jobs[0].Key") are the ones most exposed to MINOR churn. Two mitigations:

• Pin @uipath/cli in CI (see above). You choose when to validate new shapes.
• Query defensively — prefer JMESPath expressions that tolerate missing fields (Data.Jobs[0].Key || '') when you can; check the release notes before upgrading.

Breaking Data shape changes in MINOR are rare and flagged in release notes as [Data shape] under the changed command.

Where to watch for changes

• Release notes — per-version summary of added commands, changed flags, and shape shifts.
• uip --version and uip tools list — what is currently installed on a machine. Compare across environments to catch drift.
• Each tool's package on npm — publishers list dist-tags and release history there.

另请参阅

• Output formats — the envelope shape the contract describes.
• Exit codes — the five-tier contract.
• Tools (plugins) — the host-tool model that version pinning supports.
• Release notes — what changed and when.
• Migration from the legacy .NET CLI — if you are coming from 2025.10 or earlier.