npm - @uipath/skills - Versions diffs - 1.195.0 → 1.196.0 - Mend

@uipath/skills 1.195.0 → 1.196.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (380) hide show

package/skills/uipath-rpa/references/cli-reference.md CHANGED Viewed

@@ -1,668 +1,222 @@
-# UiPath CLI (`uip rpa`) Reference
+# UiPath CLI (`uip`) Reference
-CLI reference for `uip rpa` -- communicates with UiPath Studio over named pipes (IPC).
+`uip rpa` and sibling tools (`uip is`, `uip tm`, …) talk to UiPath Studio over named pipes (IPC). This file teaches **how to discover** commands, arguments, and flags — plus the non-obvious behaviors that `--help` won't tell you (auth, headless vs Desktop Studio, how to read run results, error recovery).
-> **Installation is automatic.** Do NOT attempt to install `uip` manually or instruct the user to install it.
+> **Do not treat any command/flag list here as exhaustive or current.** The CLI is the source of truth and it drifts. Discover the live surface with `--help` (below); this file carries only the HOW that `--help` omits.
-## Studio Desktop vs headless Studio (Helm)
-`uip rpa` connects to one of two flavors of Studio behind the same IPC contract:
-- **Headless Studio (Helm) — default.** Ships as a NuGet package (`UiPath.Studio.Helm.{Platform}`) and auto-launches on first use. **No Studio Desktop install needed.** First call on a cold NuGet cache may sit near-silent for 30–90 s while `dotnet restore` runs; raise `--timeout` to ≥ 180 for that call.
-- **Studio Desktop.** The interactive UI. Used automatically only by commands with UI side effects.
-### Which commands need Studio Desktop
-Only these two — they do not work headless:
-| Command | Why |
-|---------|-----|
-| `uip rpa files diff` | Opens an interactive diff window in Studio's UI |
-| `uip rpa focus-activity` | Highlights an activity in Studio's active workflow designer (hidden from `--help` — agent → user UI cue) |
-For these, run `uip rpa studio start --project-dir "<PROJECT_DIR>"` first if Studio Desktop is not already up.
-Everything else — `init`, `run`, `debug start`, `execution cancel`, `validate`, `build`, `analyzer-rules list`, `activities find`, `activities get-default-xaml`, `packages versions`, `packages inspect`, `packages install`, `data-fabric-entities list`, `data-fabric-entities install`, `templates search`, `workflow-examples list`, `workflow-examples get`, `indicate-application`, `indicate-element`, all `uia` subcommands, all `uip is` subcommands — runs headless with no Studio Desktop required.
-To force Studio Desktop for any command, set `UIPATH_RPA_TOOL_USE_STUDIO=1`. Not recommended for the standard authoring loop.
-> **This guide may not list every available command.** The CLI is self-documenting -- append `--help` at any level to progressively discover commands, subcommands, and parameters:
-```bash
-uip --help                              # top-level command groups
-uip rpa --help                          # all rpa subcommands (canonical, grouped)
-uip rpa packages --help                 # verbs inside a group
-uip rpa validate --help                 # parameters for a specific command
-```
-> **Run `--help` standalone — never combine it with other flags.** `uip rpa <subcommand> --help --project-dir "<path>"` parses `--project-dir` as a positional command and exits with `unknown command '<path>'`. Drop every other flag when probing help.
----
-## Global Options
-Every `uip rpa` invocation accepts these flags:
-| Option | Description | Default |
-|--------|-------------|---------|
-| `--project-dir <path>` | Project directory to match against running Studio instances | Current working directory |
-| `--studio-dir <path>` | Path to Studio Desktop installation (only used when Studio Desktop is in use) | Auto-detected (see below) |
-| `--timeout <seconds>` | Timeout in seconds for Studio resolution (raise to ≥ 180 on a cold Helm NuGet cache) | `300` |
-| `--verbose` | Enable verbose/debug logging | Off |
-| `--output <format>` | Output format: `json`, `table`, `yaml`, `plain` | `table` |
-> **Always use `--output json`** when calling `uip rpa` commands programmatically. The `table` format pads columns and can produce extremely large output (100KB+). JSON is compact and machine-readable.
-### STUDIO_DIR Resolution
-`--studio-dir` is **only consulted when Studio Desktop is in use** (i.e. you ran `studio start`, called `files diff`/`focus-activity`, or set `UIPATH_RPA_TOOL_USE_STUDIO=1`). Headless Studio (Helm) ignores it. When Studio Desktop is needed and auto-detection fails, the resolution waterfall is:
-1. Environment variable `UIPATH_STUDIO_DIR` if set.
-2. Default install: `C:\Program Files\UiPath\Studio` (or `x86` variant) if `UiPathStudio.exe` exists there.
-3. Dev build: Studio source tree build output (e.g. `<repo-root>\Output\bin\Debug`).
-> **Error `"Studio X.X.X does not have interop support"` or `"Requires Studio 26.2+"`** means the detected Studio Desktop is too old. This affects only the two Studio-only tools (`diff`, `focus-activity`) and any explicitly forced Studio runs. Inform the user to update Studio Desktop.
-### PROJECT_DIR Resolution
-`--project-dir` defaults to the current working directory. When the project is elsewhere, pass the absolute path to the folder containing `project.json`.
----
-## Installed Package Activity Documentation
-Located at `{projectRoot}/.local/docs/packages/{PackageId}/`.
-| Action | How | Key Parameters |
-|--------|-----|----------------|
-| **Read activity doc directly** | `Read` tool on `{projectRoot}/.local/docs/packages/{PackageId}/activities/{ActivityName}.md` | Package ID + activity simple class name. **Preferred when you know both.** |
-| **Read coded API doc** | `Read` tool on `{projectRoot}/.local/docs/packages/{PackageId}/coded/coded-api.md` | Package ID. **Use for coded workflows** — contains service API signatures and usage. |
-| **Read package overview** | `Read` tool on `{projectRoot}/.local/docs/packages/{PackageId}/overview.md` | Package ID (e.g., `UiPath.WebAPI.Activities`) |
-| **List documented packages** | `Bash`: `ls {projectRoot}/.local/docs/packages/` | Project root directory |
-| **List documented activities** | `Bash`: `ls {projectRoot}/.local/docs/packages/{PackageId}/activities/` | Package ID |
-| **Search activity docs by keyword** | `Glob` with `**/*.md` in `{projectRoot}/.local/docs/packages/` to list files, then `Read` matches. **Do not use `Grep`** -- `.local/` is gitignored and `Grep` skips it. | Glob pattern + Read |
----
-## Commands -- Studio Desktop Management (edge cases only)
-> Skip this section unless you need to invoke `diff` or `focus-activity`. Every other command auto-launches headless Studio (Helm) when needed.
-### instances list
-List running Studio Desktop instances and their IPC status. Hidden diagnostic command — does **not** report the auto-launched headless Studio (Helm) instances.
-```bash
-uip rpa instances list --output json
-```
-No command-specific options. An empty `Data` array does NOT mean `uip rpa` won't work — headless Studio starts on demand.
----
-### studio start
-Ensure a **Studio Desktop** instance is running. Only required before invoking `files diff` or `focus-activity`, or when forcing Studio Desktop with `UIPATH_RPA_TOOL_USE_STUDIO=1`. Resolution waterfall:
-1. Match by `--project-dir` -- reuse if available, wait if busy
-2. Use an idle instance (no project loaded)
-3. Start a new instance via `--studio-dir` -- poll until available
-```bash
-uip rpa studio start --project-dir "<PROJECT_DIR>" --output json
-```
----
-## Commands -- Project Lifecycle
-### init
-Create a new UiPath project from a template.
-```bash
-uip rpa init --name "<NAME>" --location "<PARENT_DIR>" --target-framework <Windows|Portable> --expression-language <VisualBasic|CSharp> --output json
-```
-> **Always pass `--target-framework` and `--expression-language`.** Both are fixed at creation and immutable afterward; omitting `--target-framework` silently produces a **Windows** project. The example shows the two new-project options (`Windows`, `Portable`). Windows - Legacy is a last resort (explicit ask or hard .NET 4.6.1 need) and is created/authored in **Legacy mode**, not via this command. Decide each per SKILL.md Common Rule 2a before running `init`.
-> **Flag names are non-standard.** Most `uip rpa` commands take `--project-dir` to identify the project. `init` instead uses `--name` (project name) + `--location` (parent directory). Do NOT use `--project-name` or `--project-dir` here — both fail with `error: required option '--name <string>' not specified`.
-| Parameter | Required | Default | Description |
-|-----------|----------|---------|-------------|
-| `--name` | Yes | -- | Name of the project |
-| `--location` | Yes | -- | Parent directory where the project folder will be created |
-| `--template-id` | No | `BlankTemplate` | `BlankTemplate`, `LibraryProcessTemplate`, `TestAutomationProjectTemplate` |
-| `--template-package-id` | No | -- | NuGet template package ID from `templates search`. Overrides `--template-id` when set |
-| `--template-package-version` | No | (latest) | Version of the template package |
-| `--allow-prerelease-packages` | No | false | Allow prerelease activity package versions |
-| `--description` | No | -- | Project description |
-| `--expression-language` | No (decide explicitly — Rule 2a) | none | `VisualBasic` or `CSharp`. Immutable after creation |
-| `--target-framework` | No (decide explicitly — Rule 2a) | none → **Windows** | `Windows` or `Portable` (Cross-platform) for new projects. The flag accepts `Legacy`, but Windows - Legacy projects are created/authored in **Legacy mode**, not via this command (last resort — explicit ask or hard .NET 4.6.1 need). Immutable after creation; omitting it yields a Windows project |
-For template selection logic (when to use `--template-package-id` vs `--template-id`), see [environment-setup.md § Template selection](environment-setup.md#template-selection).
----
-### templates search
-Search NuGet feeds for available project templates. Use before `init` when the user names a template or asks for a domain-specific starter.
-```bash
-uip rpa templates search --query "<TERM>" --output json
-```
-| Parameter | Required | Default | Description |
-|-----------|----------|---------|-------------|
-| `--query` | No | -- | Filter by name/description. Omit to list all |
-| `--limit` | No | 20 | Maximum results |
-| `--include-prerelease` | No | false | Include prerelease template versions |
-Returns `Data[*]` with `packageId`, `version`, `title`, `description`, `authors`, `source` (`"Official"` / `"Marketplace"` / feed URL), `tags`. Pass `packageId` and `version` to `init --template-package-id` / `--template-package-version`.
+> **Installation is automatic.** Do NOT install `uip` manually or instruct the user to install it.
 ---
-### project open / project close (hidden)
-Open or close a project explicitly in Studio. The `project` group and both verbs are hidden from `--help` because the standard authoring loop (`validate`, `run`, etc.) auto-resolves a Studio instance and opens the project on its own. Use only when you need to force open/close (e.g. immediately after `init` before any other command, or when releasing a project lock).
-```bash
-uip rpa project open  --project-dir "<PROJECT_DIR>" --output json
-uip rpa project close --output json
-```
----
-## Commands -- Validation and Execution
-### run
-Run a workflow file via Studio (no debugging — closes app on completion or error).
-```bash
-uip rpa run --file-path "<FILE>" --project-dir "<PROJECT_DIR>" --output json
-```
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `--file-path` | Yes | Path to the workflow file to run |
-| `--input-arguments` | No | JSON string of input arguments |
-| `--log-level` | No | Logging verbosity level |
-| `--skip-build` | No | Skip the pre-run build step (use only when you have just built) |
-| `--profiling` | No | Collect per-activity timings and runtime screenshots for the run — verifies UI automation correctness and workflow performance. Boolean flag (no value needed). Also accepted on `debug start`, `debug test-activity`, `debug start-from-here`; silently ignored on stepping/breakpoint verbs. Response carries `Profiling.OutputDirectory` when collection succeeds. See [debugging.md § Profiling Workflow Performance](debugging.md#profiling-workflow-performance). |
+## Discover the live CLI with `--help`
-For debugging — breakpoints, stepping, exception-handling lifecycle — use the `debug` group (see [debugging.md](debugging.md)). For UI automation workflows in particular, prefer `debug start` over `run` so the app is preserved for selector repair on error.
+The CLI is self-documenting. Append `--help` at **any** level to drill from tools → groups → verbs → parameters. Each level lists the next.
 ```bash
-uip rpa debug start --file-path "<FILE>" --project-dir "<PROJECT_DIR>" --output json
-uip rpa execution cancel --project-dir "<PROJECT_DIR>" --output json
+uip --help                    # top-level commands + installed tools (rpa, is, tm, ...)
+uip tools list                # installed tools, machine-readable
+uip rpa --help                # all rpa command groups and verbs
+uip rpa packages --help       # verbs inside a group
+uip rpa validate --help       # parameters, accepted values, defaults for one verb
+uip is --help                 # Integration Service surface
+uip skills --help             # skill install/search/update
 ```
-Both `run` and `debug start` return the same envelope: `{Result: "Success"|"Failure", Code, Data: {runResult: "<json-string>"}, Message?, Instructions?}`. `Data.runResult` is a **JSON string** (not an object) — parse it separately to read the run result, which has exactly three fields:
+The same pattern works for every tool and depth (`uip rpa uia <verb> --help`, `uip login --help`, etc.). When unsure whether a verb, flag, or accepted value exists, **run `--help` rather than guessing** — guessed flags fail with `unknown command`/`unknown option`.
-- `Output` — the workflow's own serialized output arguments JSON (`""` for non-`Start*` commands and on debug-command responses). **`Output` carries the workflow's data, not a verdict.**
-- `HasErrors` — `true` iff execution did not complete successfully (compile failure, validation failure, unhandled exception, cancellation, or timeout); `false` otherwise.
-- `ErrorMessage` — formatted error chain when `HasErrors: true`; `null` otherwise.
-- `Profiling` — present only when `--profiling` was passed on a start verb **and** profiling collection succeeded. Single field `OutputDirectory` is the absolute path to `%LOCALAPPDATA%\UiPath\ProfiledRuns\HHmmss_yyyy-MM-dd_<entryPoint>_<projectName>\` containing the `*.uistat` files and runtime screenshots for that run — used to verify UI automation correctness and workflow performance. `null` / omitted otherwise (profiling not requested, run did not reach the executor, or the active Studio profile does not support profiling).
-Workflow log output (`Log Message` activity, system traces) does NOT appear in `runResult`. Logs are streamed in real time during execution on a separate channel; the result envelope only carries the verdict and the workflow's output data.
-> **Single source of truth for success/failure: outer `Result` (and equivalently `HasErrors` inside `runResult`).** `Result: "Success"` already accounts for compile failures, validation failures, and unhandled runtime exceptions — the CLI propagates them. **DO NOT infer failure from streamed log entries' `Level`.** A successful workflow may emit `Log Message` at `Error` or `Warning` level as observability — those are workflow-emitted data, not CLI failures. Treating log levels as a verdict flips green runs to "failed" and burns retries on healthy workflows.
----
-### validate
-Return validation errors for a file or project. By default, forces Studio to re-validate before returning errors.
+> **Run `--help` standalone — never combine it with other flags.** `uip rpa <verb> --help --project-dir "<path>"` parses `--project-dir`'s value as a positional command and exits with `unknown command '<value>'`. Drop every other flag when probing help.
-```bash
-uip rpa validate [--file-path "<FILE>"] [--skip-validation] --output json
-```
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `--file-path` | No | File to check, **relative to the project directory**. Omit to check the whole project. |
-| `--skip-validation` | No | Return cached errors without re-validating (faster, but may be stale) |
-> **Known issue: absolute `--file-path` + absolute `--project-dir` falsely fails with `The targeted project file <X> is not in the project folder <Y>`.** The CLI normalizes `--file-path` to forward slashes (`C:/.../Main.xaml`) but leaves `--project-dir` as backslashes (`C:\...\Project`), then string-compares them — same path, different separator, comparison fails. Pass `--file-path` **relative** to the project directory (e.g. `--file-path "Main.xaml"`) to sidestep the normalization mismatch. If you need a project-level compile gate that doesn't have this quirk, use `uip rpa build "<PROJECT_DIR>"` (positional arg, no slash compare).
+> A verb may be **hidden from `--help`** yet still callable by exact name (e.g. diagnostic or UI-cue verbs). Absence from `--help` means "not part of the standard loop," not "does not exist."
 ---
-### build
+## Output format
-Build (compile) a UiPath project. Compiles all XAML expressions — catches runtime-compile failures that `validate` misses. Required before returning a project to the user (see [validation-guide.md § Project Build Verification](validation-guide.md#project-build-verification-required-before-returning-a-project)). Runs independently of Studio IPC; takes the project directory as a positional argument.
+`--output` defaults to **`json`**. Accepted: `json`, `table`, `yaml`, `plain`. Keep `json` for anything parsed programmatically — `table` pads columns and can balloon to 100 KB+.
-```bash
-uip rpa build "<PROJECT_DIR>" --log-level Warn --output json```
+`--output-filter "<JMESPath>"` applies a JMESPath expression to the response envelope's `Data` field — use it to slice large responses instead of post-processing in the shell.
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `<projectDir>` | Yes | Path to the project directory (positional — not `--project-dir`) |
-| `--log-level` | No | `Debug` / `Info` / `Warn` / `Error`. Default `Warn`. |
-| `--skip-analyze` | No | Skip the static analysis step (faster, less thorough) |
-| `--exclude-configured-sources` | No | Exclude user/machine-configured NuGet sources |
-| `--nuget-sources-config-path` | No | Path to a custom NuGet sources config file |
-| `--governance-file-path` | No | Path to a governance/policy rules file |
-| `--governance-file-type` | No | Type of the governance file |
-| `--detailed-log-path` | No | Path to write a detailed log file |
+`--log-level <debug|info|warn|error>` and `--log-file <path>` are global. Raise log level or add `--verbose` when diagnosing a failure.
-**Relationship to `run`:** `run` (and `debug start`) compile internally, so a successful smoke test implies `build` would pass. When no smoke test is run (side effects, interactive workflow, no test input), `build` is the required end-goal check for compilability — including attribute-form expression failures (`JIT compilation is disabled for non-Legacy projects`) in XAML projects with `expressionLanguage: CSharp` that don't surface during static `validate`.
+Most response envelopes share the shape `{Result: "Success"|"Failure", Code, Data, Message?, Instructions?}`. Branch on `Result`, not on stdout text.
 ---
-### analyzer-rules list
+## Authentication
-List the Workflow Analyzer rules currently **enabled** for the project — the best-practice rules that `validate` and `uip rpa build` will enforce. Reports rules only, not violations.
+Cloud features (templates/packages from feeds, Integration Service, Data Service entities, publishing) need a logged-in session.
 ```bash
-uip rpa analyzer-rules list --project-dir "<PROJECT_DIR>" --output json
+uip login              # interactive browser login to UiPath Cloud
+uip login status       # current session: org, tenant, expiry
+uip login which        # which auth source uip resolves for this cwd
 ```
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `--project-dir` | No | Project directory. Defaults to CWD. |
-| `--scope` | No | Narrow results: `Activity`, `Workflow`, `Project`, or `Coded Workflow`. |
-Each rule returns `severity` (`error` / `warning` / `info`), rule ID (e.g. `ST-DBP-010`, `MA-DBP-028`), scope (`Activity` / `Workflow` / `Coded Workflow` / `Project`), title, and — when available — `recommendation` and `docs` URL. Prefix convention: `ST-*` = built-in Studio rule, `MA-*` = package-shipped rule.
-> **Performance:** the unscoped call enumerates every rule across every package and can take a minute or more on projects with many activities packages. If the default 60 s shell timeout fires, retry with `--scope <ScopeYouNeed>` (e.g. `Activity` for single-activity generation, `Coded Workflow` for `.cs` authoring) — scoped calls return in seconds.
+If a command fails with `not authenticated` / `401` / `403`, run `uip login` and retry. Discover non-interactive/CI login options (credentials folder, client id/secret, authority) via `uip login --help`.
 ---
-## Commands -- Package Management
+## Project context: `--project-dir`
-### packages install
+Most `uip rpa` verbs identify the project via `--project-dir`, defaulting to the current working directory. When the project is elsewhere, pass the absolute path to the folder containing `project.json`. A few verbs deviate (e.g. `init` takes `--name` + `--location`; `build`/`pack` take the project dir as a positional) — confirm with that verb's `--help`.
-Install or update NuGet packages in the project.
-```bash
-uip rpa packages install --packages '[{"id": "UiPath.Excel.Activities"}]' --output json
-```
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `--packages` | Yes | JSON array of objects with `id` and optional `version` |
-Omit `version` to automatically resolve the latest compatible version (preferred). Only pin a specific version when there is a known compatibility constraint.
-**Error recovery:**
-- **Package not found** -- verify the exact package ID; use `--help` or activity docs to discover the correct name.
-- **Network/feed error** -- check NuGet feed configuration in Studio settings.
+To create a project, see [environment-setup.md](environment-setup.md); `--target-framework` and `--expression-language` are immutable after creation, so decide them per SKILL.md before running `init`.
 ---
-### packages versions
-Get available versions for a NuGet package.
-```bash
-uip rpa packages versions --package-id <PackageId> --include-prerelease --output json
-```
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `--package-id` | Yes | NuGet package ID to query |
-| `--include-prerelease` | No | Include prerelease versions (default false) |
-> **Default to `--include-prerelease`.** UiPath activity packages frequently ship as `-preview` between stable releases, and previews carry the freshest activity surface and `.local/docs` content. Omitting the flag hides them and the agent picks a stale stable. When the user already has a stable version installed and a newer (stable or preview) is available, inform them and offer the upgrade — never force.
----
+## Headless Studio (Helm) vs Studio Desktop
-## Commands -- Data Fabric Entities
+`uip rpa` connects to one of two Studio flavors behind the same IPC contract:
-UiPath Data Fabric entities live in the Orchestrator tenant's Data Service. To use them in an RPA project -- as typed arguments (e.g. `UiPath.DataService.Activities`, `test-data add-entity`) or anywhere else that binds to generated entity types -- they must first be **installed** into the project. Installation writes a manifest at `.entities/EntitiesStore.json` and compiles a strongly-typed assembly; all entity-aware activities, coded service calls, and test-data bindings resolve against it.
+- **Headless Studio (Helm) — default.** Ships as a NuGet package and auto-launches on first use. **No Studio Desktop install needed.** First call on a cold NuGet cache may sit near-silent for 30–90 s while `dotnet restore` runs — the default shell timeout covers this; raise `timeoutSeconds` only behind a slow feed.
+- **Studio Desktop.** The interactive UI. Used automatically only by verbs with **UI side effects** — those that open a window or highlight something in the designer (discover them via `--help`; they don't work headless). For such a verb, ensure Desktop is up first (`uip rpa studio start --project-dir "<PROJECT_DIR>"`), then run it. Force Desktop for any command with `UIPATH_RPA_TOOL_USE_STUDIO=1` (not recommended for the standard authoring loop).
-Typical flow: `data-fabric-entities list` (discover) → `data-fabric-entities install --add ...` (install) → reference the generated entity types from your workflow or test case.
+`--studio-dir` is consulted **only when Studio Desktop is in use**; headless ignores it. When Desktop auto-detection fails, resolution falls back to `UIPATH_STUDIO_DIR`, then the default install path, then a dev build output. Errors like `"does not have interop support"` / `"Requires Studio 26.2+"` mean the detected Desktop is too old — tell the user to update it; this affects only the Desktop-only verbs.
 ---
-### data-fabric-entities list
-List Data Fabric entities relevant to the active project. Returns a unified view of entities currently installed in the project **and** entities available in the connected tenant, each tagged with an `installed` flag.
-```bash
-uip rpa data-fabric-entities list --project-dir "<PROJECT_DIR>" --output json
-uip rpa data-fabric-entities list --service-document "<PATH>" --project-dir "<PROJECT_DIR>" --output json
-```
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `--service-document` | No | Project-relative path to a specific entities manifest (e.g. `.entities/Custom.json`). Omit to use the project's default. |
+## Installed package activity documentation
-Each returned entry includes: `name`, `displayName`, `namespace` (if installed), `serviceDocument` (if installed), `storeUrl` (if cloud-available), and `installed: true | false`.
+When a package is installed, its activity docs land under `{PROJECT_DIR}/.local/docs/packages/{PackageId}/`. Read these directly — they carry the per-activity property surface and coded API signatures that no `--help` exposes.
-Use this before `data-fabric-entities install` to pick names from the tenant, or to verify what is already bound to the project.
+| Action | How |
+|--------|-----|
+| **Read an activity doc** | `Read` `…/{PackageId}/activities/{ActivityName}.md` — preferred when you know package + class |
+| **Read coded API doc** | `Read` `…/{PackageId}/coded/coded-api.md` — service API signatures for coded workflows |
+| **Read package overview** | `Read` `…/{PackageId}/overview.md` |
+| **List documented packages / activities** | `Bash`: `ls …/.local/docs/packages/` then `ls …/{PackageId}/activities/` |
+| **Search activity docs** | `Glob` `**/*.md` under `…/.local/docs/packages/`, then `Read` matches. **Not `Grep`** — `.local/` is gitignored and `Grep` skips it. |
 ---
-### data-fabric-entities install
-Install, update, or remove Data Fabric entity bindings by applying an add/remove delta to the project's currently installed set. Dependency expansion is automatic -- adding `E1` pulls in any entity `E1` references.
-```bash
-uip rpa data-fabric-entities install --add "Invoice" --add "Customer" --project-dir "<PROJECT_DIR>" --output json
-uip rpa data-fabric-entities install --remove "LegacyOrder" --project-dir "<PROJECT_DIR>" --output json
-uip rpa data-fabric-entities install --add "Invoice" --remove "LegacyOrder" --namespace "My.App.Entities" --project-dir "<PROJECT_DIR>" --output json
-```
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `--add` | One of `--add`/`--remove` | Entity name to add. Pass the flag multiple times for multiple entities (e.g. `--add Invoice --add Customer`). |
-| `--remove` | One of `--add`/`--remove` | Entity name to remove. Pass the flag multiple times for multiple entities (e.g. `--remove LegacyOrder --remove StaleCustomer`). |
-| `--service-document` | No | Project-relative manifest path. Omit to use the project's default. |
-| `--namespace` | No | .NET namespace for the generated entity types. Omit to keep the previously-used namespace, or derive one from the project name on a first install. |
+## Reading run / debug results
-Behavior notes:
+`uip rpa run` runs a workflow with no debugging; the `debug` group drives breakpoints, stepping, and exception handling (see [debugging.md](debugging.md)). For UI automation, prefer `debug start` over `run` so the app is preserved for selector repair on error. Cancel an active run or session with `uip rpa execution cancel`. Pass workflow inputs as repeatable `--input-arguments key=value` pairs (see [Passing structured inputs](#passing-structured-inputs)); discover the remaining flags (log level, skip-build, profiling) via `--help`.
-- **Semantics:** final selection = `(currently installed ∪ add) − remove`. If the same name appears in both `--add` and `--remove`, remove wins.
-- **Dependencies:** pulled in automatically; the returned `entities` array is the full set actually installed.
-- **Server-deleted entities:** silently filtered before install -- they can't be compiled against. The diff between request and returned `entities` tells you what was dropped.
-- **Empty resulting selection:** uninstalls everything for the target service document (removes the manifest + generated assembly).
-- **At least one of `--add` / `--remove` must be non-empty.** To fully uninstall, pass every currently-installed name in `--remove`.
+Both `run` and `debug start` return the same envelope: `{Result, Code, Data: {runResult: "<json-string>"}, ...}`. `Data.runResult` is a **JSON string** — parse it separately. It has three fields (plus optional `Profiling`):
-Returns JSON:
-```json
-{ "serviceDocument": ".entities/EntitiesStore.json", "namespace": "My.App.Entities", "entities": ["Invoice", "Customer", "Address"] }
-```
-**Use this before** invoking any workflow or test case that references the entity types, and before `test-data add-entity` -- the test-data command requires its target entity to already be managed in the project.
----
+- `Output` — the workflow's own serialized output arguments JSON (`""` for non-`Start*` commands). **Carries the workflow's data, not a verdict.**
+- `HasErrors` — `true` iff execution did not complete successfully (compile/validation failure, unhandled exception, cancellation, or timeout); `false` otherwise.
+- `ErrorMessage` — formatted error chain when `HasErrors: true`; `null` otherwise.
+- `Profiling.OutputDirectory` — present only when `--profiling` was passed on a start verb and collection succeeded; absolute path to the per-run `*.uistat` files and runtime screenshots. See [debugging.md § Profiling Workflow Performance](debugging.md#profiling-workflow-performance).
-## Commands -- Test Manager
+Workflow log output (`Log Message`, system traces) does **not** appear in `runResult` — logs stream in real time on a separate channel; the envelope carries only the verdict and output data.
-Test Manager integration has moved to the dedicated `uip tm` tool — see `uip tm --help`. The two read-only verbs previously exposed under `uip rpa` (`get-manual-test-cases`, `get-manual-test-steps`) are no longer documented here and should not appear in new skill content.
+> **Single source of truth for success/failure: outer `Result` (equivalently `HasErrors` inside `runResult`).** `Result: "Success"` already accounts for compile failures, validation failures, and unhandled exceptions — the CLI propagates them. **DO NOT infer failure from a streamed log entry's `Level`.** A successful workflow may emit `Log Message` at `Error`/`Warning` level as observability — that is workflow data, not a CLI failure. Treating log levels as a verdict flips green runs to "failed" and burns retries.
 ---
-## Commands -- Integration Service (IS)
-All IS commands support `--output json`. The CLI is self-documenting: `uip is --help`, `uip is connections --help`, etc.
-### connectors list
+## Passing structured inputs
-List available connectors, optionally filtered by name or key.
+`--input-arguments` and `--input-variables` may be supplied as repeatable `key=value` pairs (`key:=value` for raw JSON, `key=@file` to read a value from a file), as an inline JSON string, or from a JSON file using `'@file'` or `--<flag>-file`. `--packages` takes one item per occurrence as comma-joined fields.
 ```bash
-uip is connectors list --output json
-uip is connectors list --filter "<NAME_OR_KEY>" --output json
+uip rpa run --file-path Main.xaml --input-arguments name=John --input-arguments retries:=3
+uip rpa run --file-path Main.xaml --input-arguments 'message=Hello, world!'
+uip rpa debug test-activity --input-variables greeting=@expression.txt
+uip rpa run --file-path Main.xaml --input-arguments '@args.json'      # or: --input-arguments-file args.json
+uip rpa packages install --packages 'id=UiPath.System.Activities,version=23.10.1' --packages id=UiPath.Excel.Activities
 ```
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `--filter` | No | Filter by connector name or key |
----
-### connectors get
-Get details for a specific connector.
-```bash
-uip is connectors get <CONNECTOR_KEY> --output json
-```
+Rules:
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `<connector-key>` | Yes | Connector key (positional) |
+- **`=` vs `:=`**: `count=42` sends the string `"42"`; `count:=42` sends the number `42`. For `debug test-activity` / `debug start-from-here`, values are VB/C# expression **strings** — always `=`.
+- **Quoting**: single-quote any token containing spaces, commas, or a leading `@`; bare identifiers and numbers need no quotes. Values containing double quotes cannot be passed inline on Windows PowerShell 5.1 (it strips them) — write them to a UTF-8 file (`Set-Content -Encoding UTF8`) and use `key=@file`, `'@file'`, or `--<flag>-file`.
+- **Inline JSON**: a single JSON blob (`--input-arguments '{"k":"v"}'`) remains accepted for backward compatibility, but is unreliable on PowerShell 5.1 — prefer pairs or files.
 ---
-### connections list
-List connections, optionally filtered by connector.
+## validate
-```bash
-uip is connections list --output json
-uip is connections list <CONNECTOR_KEY> --output json
-uip is connections list --connection-id "<ID>" --output json
-```
+`uip rpa validate` returns diagnostics for a file or the whole project, re-validating first by default (`--skip-validation` reads cached, possibly stale, results; `--min-severity` filters). Confirm flags via `uip rpa validate --help`.
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `<connector-key>` | No | Filter by connector key (positional) |
-| `--connection-id` | No | Filter by specific connection ID |
-| `--folder-key` | No | Filter by folder key |
+> **Known issue: an absolute `--file-path` with an absolute `--project-dir` falsely fails** with `The targeted project file <X> is not in the project folder <Y>`. The CLI normalizes `--file-path` to forward slashes but leaves `--project-dir` with backslashes, then string-compares — same path, different separators. Pass `--file-path` **relative** to the project directory (e.g. `--file-path "Main.xaml"`) to sidestep it. For a project-level compile gate without this quirk, use `build`.
 ---
-### connections create
+## build
-Create a new connection via OAuth flow. Opens a browser for authentication.
-```bash
-uip is connections create <CONNECTOR_KEY>
-uip is connections create <CONNECTOR_KEY> --no-browser
-```
+`uip rpa build` compiles the project — catching runtime-compile failures `validate` misses (including attribute-form expression failures like `JIT compilation is disabled for non-Legacy projects` in C#-expression XAML projects). Required before returning a project to the user (see [validation-guide.md § Project Build Verification](validation-guide.md#project-build-verification-required-before-returning-a-project)). Takes the project directory as a **positional** argument and runs independently of Studio IPC. Discover flags (log level, skip-analyze, governance, NuGet sources) via `uip rpa build --help`.
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `<connector-key>` | Yes | Connector key (positional) |
-| `--no-browser` | No | Print the OAuth URL instead of opening a browser |
+`run` and `debug start` compile internally, so a successful smoke test implies `build` would pass. When no smoke test runs (side effects, interactive workflow, no test input), `build` is the required compilability check.
 ---
-### connections ping
+## analyzer-rules list
-Verify a connection is alive and authenticated.
+`uip rpa analyzer-rules list` reports the Workflow Analyzer rules **enabled** for the project — the best-practice rules `validate` and `build` enforce. Reports rules, not violations. Each rule returns `severity` (`error`/`warning`/`info`), rule ID, scope, title, and (when available) `recommendation` and `docs` URL. Prefix convention: `ST-*` = built-in Studio rule, `MA-*` = package-shipped rule.
-```bash
-uip is connections ping <CONNECTION_ID>
-```
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `<connection-id>` | Yes | Connection ID (positional) |
+> **Performance:** the unscoped call enumerates every rule across every package and can take a minute or more. Narrow with `--scope` (`Activity`, `Workflow`, `Project`, or `Coded Workflow`) — scoped calls return in seconds. See `--help` for accepted scope values.
 ---
-### connections edit
+## packages install
-Re-authenticate or edit an existing connection. Opens OAuth flow.
+`uip rpa packages install` installs or updates NuGet packages (canonical way to add dependencies — **do not hand-edit `project.json`**; there is no `add-dependency` verb). Repeat `--packages` once per package with comma-joined `key=value` fields — `--packages 'id=<PackageId>,version=<Version>'` or just `--packages id=<PackageId>` (see [Passing structured inputs](#passing-structured-inputs)); discover the remaining flags via `uip rpa packages install --help`.
-```bash
-uip is connections edit <CONNECTION_ID>
-```
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `<connection-id>` | Yes | Connection ID (positional) |
+- **Omit the version** to resolve the latest compatible automatically (preferred). Pin only for a known compatibility constraint.
+- **Discover available versions** with `uip rpa packages versions --package-id <Id> --include-prerelease`. **Default to `--include-prerelease`** — activity packages frequently ship `-preview` between stable releases, carrying the freshest activity surface and `.local/docs`. When a newer stable or preview exists over the installed version, inform the user and offer the upgrade — never force.
+- **Package not found** → verify the exact ID (use `activities find` or the package's `.local/docs`). **Feed/network error** → check NuGet feed config in Studio settings.
 ---
-### activities list
-List activities available for a connector.
+## Commands -- Data Fabric Entities
-```bash
-uip is activities list <CONNECTOR_KEY> --output json
-```
+UiPath Data Fabric entities live in the Orchestrator tenant's Data Service. To use them in an RPA project — as typed arguments (`UiPath.DataService.Activities`, test-data bindings) or any generated entity type — they must first be **installed** into the project, which writes a manifest under `.entities/` and compiles a strongly-typed assembly.
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `<connector-key>` | Yes | Connector key (positional) |
+Typical flow, all under `uip rpa data-fabric-entities` (discover exact flags via `--help`):
----
+1. **List** — returns a unified view of entities installed in the project **and** available in the connected tenant, each with an `installed` flag. Run before installing to pick names or verify bindings.
+2. **Install** — applies an add/remove delta to the installed set. Dependency expansion is automatic (adding an entity pulls in everything it references); server-deleted entities are silently dropped. Final selection = `(installed ∪ add) − remove`; an empty result uninstalls everything for that manifest.
-### resources list
-List resources available for a connector, optionally filtered by operation.
-```bash
-uip is resources list <CONNECTOR_KEY> --output json
-uip is resources list <CONNECTOR_KEY> --operation List --output json
-```
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `<connector-key>` | Yes | Connector key (positional) |
-| `--operation` | No | Filter by operation: `List`, `Retrieve`, `Create`, `Update`, `Delete`, `Replace` |
+**Install entities before** invoking any workflow or test case that references their generated types, and before any test-data command that binds to an entity.
 ---
-### resources describe
-Get the schema for a specific resource object.
+## Integration Service (`uip is`)
-```bash
-uip is resources describe <CONNECTOR_KEY> <OBJECT_NAME> --output json
-uip is resources describe <CONNECTOR_KEY> <OBJECT_NAME> --operation Create --output json
-```
+`uip is` manages connectors, connections, resources, triggers, and webhooks. Discover the full surface via `uip is --help`, then drill in (`uip is connections --help`, `uip is resources describe --help`, …). All verbs support `--output json`.
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `<connector-key>` | Yes | Connector key (positional) |
-| `<object-name>` | Yes | Resource object name (positional) |
-| `--operation` | No | Schema for a specific operation |
+The verbs you'll reach for: list/describe **connectors** and their **activities**/**resources**, list/create/ping/edit **connections** (OAuth opens a browser; `--no-browser` prints the URL), and run CRUD **resource** operations. For RPA-specific connector workflow patterns (activity/resource discovery, connection management, schema inspection), see [connector-capabilities.md](connector-capabilities.md).
 ---
-### resources run
-Run a CRUD operation on a connector resource.
+## Test Manager (`uip tm`)
-```bash
-uip is resources run <OPERATION> <CONNECTOR_KEY> <OBJECT_NAME> --output json
-```
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `<operation>` | Yes | One of: `create`, `list`, `get`, `update`, `replace`, `delete` |
-| `<connector-key>` | Yes | Connector key (positional) |
-| `<object-name>` | Yes | Resource object name (positional) |
+Test Manager integration lives in the dedicated `uip tm` tool — `uip tm --help`. Do not document or invoke Test Manager verbs from `uip rpa`.
 ---
 ## CLI Error Recovery
-When `uip` commands fail, diagnose by error category:
+Diagnose by error category, apply the recovery, retry **once** — do not loop the same failing command.
-| Error Pattern | Cause | Recovery |
+| Error pattern | Cause | Recovery |
 |---------------|-------|----------|
-| `"connection refused"`, `"EPIPE"`, `"pipe not found"` | Studio IPC not available. Headless Studio (Helm): NuGet restore failed or process exited. Studio Desktop: not running. | Re-run the command — headless Studio relaunches automatically. If it persists, raise `--timeout` and check the Helm restore output for NuGet errors. Only run `uip rpa studio start` if the failing command is `files diff`/`focus-activity` or `UIPATH_RPA_TOOL_USE_STUDIO=1` is set. |
-| `"timeout"`, `"ETIMEDOUT"` | Command took too long. Cold Helm NuGet restore can take 30–90 s. | Raise the timeout: `uip rpa --timeout 600 <command>`. For `validate`, also try `--skip-validation`. |
-| `"not authenticated"`, `401`, `403` | Auth required for cloud features | Run `uip login` and re-try |
-| `"package not found"`, `"version not available"` | Wrong package ID or version | Verify package name via `uip rpa activities find`; omit `version` to auto-resolve latest |
-| `"project not found"`, `"no project open"` | Wrong project-dir or project not open in Studio | Verify `--project-dir` path, run `uip rpa project open` |
-| `"file not found"` in `validate` | Wrong `--file-path` (must be relative to project) | Use path relative to project root, not absolute |
-| `"Studio is busy"`, `"operation in progress"` | Studio is processing a previous request | Wait a few seconds and retry the command |
-| Any unrecognized error | Unknown | Check `--verbose` flag: `uip rpa --verbose <command>` for debug details, inform the user |
-**General strategy:** Do NOT retry the same failing command in a loop. Diagnose the root cause, apply the recovery action, then retry once. If it fails again, inform the user.
----
-## RPA-Specific Commands
-### activities find
-Search for activities by keyword. Global search -- not limited to installed packages.
-```bash
-uip rpa activities find --query "<KEYWORD>" --output json
-uip rpa activities find --query "<KEYWORD>" --tags "<TAGS>" --limit 20 --output json
-```
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `--query` | Yes | Search keyword |
-| `--tags` | No | Filter by tags |
-| `--limit` | No | Max results (default 10) |
----
-### activities get-default-xaml
-Get the default XAML template for an activity. Two modes depending on whether the activity is dynamic (connector-backed) or not.
-```bash
-# Non-dynamic activity:
-uip rpa activities get-default-xaml --activity-class-name "<FULLY_QUALIFIED_CLASS>" --output json
-# Dynamic activity (connector-backed):
-uip rpa activities get-default-xaml --activity-type-id "<TYPE_ID>" --connection-id "<CONN_ID>" --output json
-```
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `--activity-class-name` | One mode | Fully qualified class name (non-dynamic) |
-| `--activity-type-id` | One mode | Activity type ID (dynamic) |
-| `--connection-id` | No | Connection ID for dynamic activities |
----
-### workflow-examples list
-Search example workflows by service tags.
-```bash
-uip rpa workflow-examples list --tags "service1,service2" --output json
-uip rpa workflow-examples list --tags "service1" --prefix "<PREFIX>" --limit 20 --output json
-```
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `--tags` | Yes | Comma-separated service tags |
-| `--prefix` | No | Filter by name prefix |
-| `--limit` | No | Max results (default 10) |
----
-### workflow-examples get
-Retrieve the full XAML content of an example workflow.
-```bash
-uip rpa workflow-examples get --key "<BLOB_PATH>" --output json
-```
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `--key` | Yes | Blob path from `workflow-examples list` results |
+| `connection refused`, `EPIPE`, `pipe not found` | Studio IPC unavailable. Headless: NuGet restore failed or process exited. Desktop: not running. | Re-run — headless relaunches automatically. If persistent, raise `--timeout` and check Helm restore output for NuGet errors. Run `uip rpa studio start` only for Desktop-only verbs or when `UIPATH_RPA_TOOL_USE_STUDIO=1`. |
+| `timeout`, `ETIMEDOUT` | Cold Helm NuGet restore (30–90 s) or long operation. | Raise both limits together: shell `timeoutSeconds` toward its documented max, and `uip rpa --timeout <timeoutSeconds − 30> <command>` — the shell timeout must exceed `--timeout` by ≥ 30 s or the shell kills the CLI before it can cancel cleanly. For `validate`, also try `--skip-validation`. |
+| `not authenticated`, `401`, `403` | Auth required for cloud features. | `uip login`, then retry. |
+| `package not found`, `version not available` | Wrong package ID or version. | Verify via `uip rpa activities find`; omit `version` to auto-resolve latest. |
+| `project not found`, `no project open` | Wrong `--project-dir` or project not open. | Verify the path points at the `project.json` folder. |
+| `not in the project folder` (in `validate`) | Absolute `--file-path` + separator mismatch. | Pass `--file-path` relative to the project root (see [validate](#validate)). |
+| `Studio is busy`, `operation in progress` | Studio processing a prior request. | Wait a few seconds, retry. |
+| Unrecognized error | Unknown | Re-run with `--verbose` for debug detail, then inform the user. |
 ---
-### focus-activity (hidden)
-Focus an activity in the Studio Desktop designer view. **Requires a running Studio Desktop instance** — does not work against headless Studio. Hidden from `--help` (agent → user UI cue), but reachable directly by name. Run `uip rpa studio start --project-dir "<PROJECT_DIR>"` first if Studio Desktop is not already up.
-```bash
-uip rpa focus-activity --activity-id "<IDREF>" --output json
-uip rpa focus-activity --output json
-```
-| Parameter | Required | Description |
-|-----------|----------|-------------|
-| `--activity-id` | No | Activity IdRef. Omit to focus all activities sequentially. |
----
-### RPA Discovery Tools
+## RPA discovery tools (non-CLI)
 | Action | How |
 |--------|-----|
-| **Explore project files** | `Glob` with `**/*.xaml` pattern |
-| **Search XAML content** | `Grep` with regex across `.xaml` files |
-| **Explore object repository** | `Glob` `**/*` in `{projectRoot}/.objects/` + `Read` metadata |
-| **Get JIT type definitions** | `Read` `{projectRoot}/.project/JitCustomTypesSchema.json` |
-| **Activity docs** | See the Installed Package Activity Documentation section above |
-## Debugging — the `debug` group
-The `uip rpa debug` group exposes full interactive debugging: breakpoints, step-by-step execution, isolated activity testing, exception handling, and runtime state inspection. Cancel a run or debug session with `uip rpa execution cancel`. For the complete debug verb reference and common debugging workflows, see **[debugging.md](debugging.md)**.
-### Connector Capabilities
-For RPA-specific connector workflow patterns (activity/resource discovery, connection management, schema inspection), see [connector-capabilities.md](connector-capabilities.md).
----
-## Coded-Specific Commands
-### packages inspect
-Inspect a NuGet package to discover its API surface (classes, methods, properties). See [coded/inspect-package-guide.md](coded/inspect-package-guide.md) for full usage.
+| **Explore project files** | `Glob` `**/*.xaml` |
+| **Search XAML content** | `Grep` regex across `.xaml` |
+| **Explore Object Repository** | `Glob` `**/*` under `{PROJECT_DIR}/.objects/` + `Read` metadata |
+| **Get JIT type definitions** | `Read` `{PROJECT_DIR}/.project/JitCustomTypesSchema.json` |
+| **Activity docs** | See [Installed package activity documentation](#installed-package-activity-documentation) above |
+| **Inspect a NuGet package's API** | `uip rpa packages inspect` — see [coded/inspect-package-guide.md](coded/inspect-package-guide.md) |
 ---
-## UI Automation Commands (`uip rpa uia ...`)
+## UI Automation (`uip rpa uia ...`)
-UIA subcommands and flags are documented in the `UiPath.UIAutomation.Activities` package. See `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/references/cli-reference.md`.
+`uip rpa uia --help` deliberately exposes no standard subcommands — the UIA CLI surface is owned and co-versioned by the `UiPath.UIAutomation.Activities` package. Subcommands, flags, accepted values, and artifact filenames live in `{PROJECT_DIR}/.local/docs/packages/UiPath.UIAutomation.Activities/references/cli-reference.md`. Read that file rather than improvising from `--help`.