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

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](#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:

| Field | Stability | Meaning |
|---|---|---|
| `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](./output-formats.md) for the envelope in detail.

### Exit codes

The [five-tier exit-code contract](./exit-codes.md) (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.

```bash
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:

```bash
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.

### Channels

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.

```bash
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.

| Label | Meaning |
|---|---|
| **GA** *(default; unlabeled)* | The command is covered by the semver contract above. It will not be renamed or removed within a MAJOR release. |
| **Preview** | 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. |
| **Deprecated** | 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:

```bash
# 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](../release-notes/overview.md) for known `Data`-shape changes.

For developer workstations:

```bash
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](../release-notes/overview.md)** — 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.

## See also

- [Output formats](./output-formats.md) — the envelope shape the contract describes.
- [Exit codes](./exit-codes.md) — the five-tier contract.
- [Tools (plugins)](./concepts-tools.md) — the host-tool model that version pinning supports.
- [Release notes](../release-notes/overview.md) — what changed and when.
- [Migration from the legacy .NET CLI](./migration-from-dotnet-cli.md) — if you are coming from `2025.10` or earlier.