# uip rpa run, debug & execution

> Syntax and options for `uip rpa run`, the `debug` group, and `execution cancel` — the current primary surface for running and debugging a workflow or coded file, replacing the older `run-file`/`stop-execution` verbs.

`uip rpa run`, `uip rpa debug *`, and `uip rpa execution cancel` run and debug a workflow or coded file through Studio. All 17 verbs on this page dispatch into the same two underlying tools that [`uip rpa run-file`](./uip-rpa-run-file.md) and `uip rpa stop-execution` expose as one wide `--command` enum — this is the current, primary, discoverable form of that same functionality, split into one verb per behavior instead of one flag with 19 values. `run-file`/`stop-execution` still work (they're kept as hidden compatibility aliases for installed skills), but this page is what `--help` actually shows.

Execution happens through Studio, so these commands work only on Windows runners (Studio is Windows-only). If Studio is not already running, it's brought up automatically — run [`uip rpa start-studio`](./uip-rpa-start-studio.md) first if you want the startup cost paid in a dedicated setup step.

## Synopsis

```text
uip rpa run --file-path <path> [--input-arguments <json>] [--log-level <level>] [--skip-build] [--profiling] [--profiling-mode endOfRun|stream] [--remote]

uip rpa debug start --file-path <path> [same options as run] [--breakpoints <json>]
uip rpa debug start-from-here [--input-arguments <json>] [--input-variables <json>] [--log-level <level>] [--profiling] [--profiling-mode <mode>]
uip rpa debug test-activity [--input-arguments <json>] [--input-variables <json>] [--log-level <level>] [--profiling] [--profiling-mode <mode>]
uip rpa debug break [--wait-timeout-seconds <n>]
uip rpa debug continue [--wait-timeout-seconds <n>]
uip rpa debug resume [--wait-timeout-seconds <n>]
uip rpa debug continue-retry [--wait-timeout-seconds <n>]
uip rpa debug continue-ignore [--wait-timeout-seconds <n>]
uip rpa debug step-into [--wait-timeout-seconds <n>]
uip rpa debug step-over [--wait-timeout-seconds <n>]
uip rpa debug step-out [--wait-timeout-seconds <n>]
uip rpa debug state [--wait-timeout-seconds <n>]
uip rpa debug set-breakpoints --breakpoints <json>
uip rpa debug apply-file-changes --file-changes <json>
uip rpa debug toggle-breakpoint
uip rpa debug restart-from-top

uip rpa execution cancel
```

## Concepts

- **One of two backends.** Studio Desktop and the headless Helm backend both implement these; several options (`--profiling-mode stream`, `debug set-breakpoints`, `debug apply-file-changes`, and long-poll `--wait-timeout-seconds`) are Helm-only and are ignored or unavailable on the Studio backend — noted per-verb below.
- **`--remote`** (on `run`/`debug start`/`debug start-from-here`/`debug test-activity` only) runs on the configured remote agent (an Orchestrator unattended robot) instead of locally — see [`uip rpa remote`](./uip-rpa-remote.md) for how to configure the target first.
- **Every mid-session command returns at the next stable state.** `continue`/`resume`/`continue-retry`/`continue-ignore`/the step verbs/`break`/`state` all wait for the session to reach a stable state (`Paused`, `Suspended`, or `Completed`) before returning; if none is reached within `--wait-timeout-seconds` they return `DebugState: "Running"` instead of hanging.

## uip rpa run

Run a workflow or coded file via Studio, with no debugger attached.

### Options

| Long | Value | Description |
|---|---|---|
| `--file-path <path>` | string | **Required.** Path to the `.xaml` workflow or `.cs` coded file. |
| `--input-arguments <json>` | JSON object | Project-level input arguments as plain JSON, e.g. `{"customerId":"ACME-1234"}`. |
| `--log-level <level>` | `Verbose`\|`Trace`\|`Information`\|`Warning`\|`Error`\|`Critical` | Minimum log level in the output stream. Default `Trace`. |
| `--skip-build` | flag | Skip validation/build, assuming the project already built. Use for rapid re-execution when nothing changed. |
| `--profiling` | flag | Collect per-activity profiling data, returned as a `Profiling` field. Requires a Studio Develop profile with `EnableProfiling` set — if unavailable, the run still completes and `Profiling` is simply omitted. Default `false`. |
| `--profiling-mode <mode>` | `endOfRun`\|`stream` | Delivery timing for profiling data. `endOfRun` (default) returns the summary once at completion; `stream` also turns collection on by itself and additionally forwards each per-activity entry live as a `[Profiling]` line, plus writes the exhaustive data to the run's `.uistat` file. Helm backend only; ignored when running remote. |
| `--remote` | flag | Run on the configured remote agent instead of locally. Configure the target first with [`uip rpa remote configure`](./uip-rpa-remote.md). Default `false`. |

### Example

```bash
uip rpa run --file-path ./Main.xaml --input-arguments '{"customerId": "ACME-1234"}'
```

### Data shape (--output json)

```json
{ "Code": "RunResult", "Data": { "DebugState": "Completed", "Result": {} } }
```

Exact `Data` shape is the underlying tool's run-result payload — see [`uip rpa run-file`](./uip-rpa-run-file.md) for the full result contract (both verbs return the same shape).

## uip rpa debug start

Start a debug session for a workflow or coded file. Same options as `run`, plus `--breakpoints`.

### Options

All of `run`'s options, plus:

| Long | Value | Description |
|---|---|---|
| `--breakpoints <json>` | JSON array | Initial breakpoint set. Each entry: `workflowFile` (required, path relative to project root), `activityIdRef` (the activity's `sap2010:WorkflowViewState.IdRef` from the XAML — the stable way to address it) or `activityId` (runtime id), plus optional `condition` (VB/C# expression; breaks only when true), `hitCount` (break only on the Nth hit), `enabled` (default `true`). Repeatable comma-separated `key=value` items, one array entry per occurrence, or a JSON file via `@breakpoints.json` / `--breakpoints-file`. |

### Example

```bash
uip rpa debug start --file-path ./Main.xaml \
  --breakpoints 'workflowFile=Main.xaml,activityIdRef=Assign_1'
```

### Data shape (--output json)

Same shape as `run`; a session that hits a breakpoint reports `DebugState: "Paused"` with the activity and locals in `DebugDetails`.

## uip rpa debug start-from-here

Start debugging from the currently-focused activity, skipping everything before it. No `--file-path` — it operates on whatever's focused in the open project.

### Options

| Long | Value | Description |
|---|---|---|
| `--input-arguments <json>` | JSON | Project-level inputs. Unlike `run`/`debug start`, values here are VB.NET or C# expressions, not plain JSON literals. |
| `--input-variables <json>` | JSON | Workflow-level variable values to seed in-scope state (expressions, not literals). |
| `--log-level <level>` | same enum as `run` | Minimum log level. |
| `--profiling` / `--profiling-mode <mode>` | — | Same as `run`. |

### Example

```bash
uip rpa debug start-from-here --input-variables '{"greeting": "\"Hello World\""}'
```

## uip rpa debug test-activity

Isolate and execute the currently-focused activity, using `--input-arguments`/`--input-variables` (expressions, same convention as `start-from-here`) to seed in-scope state.

### Options

Same as `debug start-from-here`.

### Example

```bash
uip rpa debug test-activity --input-variables '{"greeting": "\"Hello World\""}'
```

## uip rpa debug break

Pause execution at the next executed activity in the active session.

### Options

| Long | Value | Description |
|---|---|---|
| `--wait-timeout-seconds <n>` | number | Max seconds to wait for the next stable state before returning `DebugState: "Running"`. Default `120`. Helm backend only — the Studio backend applies its own fixed 120s bound and ignores an explicit value. |

## uip rpa debug continue / resume / continue-retry / continue-ignore

Resume execution in the active session. `continue` resumes from paused; `resume` resumes from suspended; `continue-retry` resumes and retries the activity that just threw; `continue-ignore` resumes and swallows the exception from the activity that just threw.

### Options

Same `--wait-timeout-seconds` as `debug break`.

## uip rpa debug step-into / step-over / step-out

Standard debugger stepping in the active session. `step-out`, called with no active session, starts one paused before the first activity.

### Options

Same `--wait-timeout-seconds` as `debug break`.

## uip rpa debug state

Report the active debug session's state (`Running`/`Paused`/`Suspended`/`Completed`/`None`) with no side effects.

### Options

| Long | Value | Description |
|---|---|---|
| `--wait-timeout-seconds <n>` | number | Long-poll a running session for its next stable state. Default `0` (an instant probe). Helm backend only — on the Studio backend this is always an instant probe. |

## uip rpa debug set-breakpoints

Replace the active debug session's whole breakpoint set. Helm backend only — on the Studio backend, use `debug toggle-breakpoint`, or pass breakpoints to `debug start` instead.

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--breakpoints <json>` | JSON array | **yes** | Same shape as `debug start`'s `--breakpoints`. Replaces the whole set, not a merge. |

## uip rpa debug apply-file-changes

While paused/suspended in a debug session, reconcile on-disk activity-property edits into the running session via hot-reload, so it picks them up without a restart. Edit the workflow file first, then call this naming what changed.

### Options

| Long | Value | Required | Description |
|---|---|---|---|
| `--file-changes <json>` | JSON array | **yes** | One object per edited property: `workflowFile` (required), `activityIdRef`, plus the changed property name/value. Repeatable `key=value` form or `@changes.json` / `--file-changes-file`. |

### Data shape (--output json)

```json
{ "Code": "ApplyFileChanges", "Data": { "applied": [], "rejected": [], "debugState": "Paused" } }
```

`applied` edits are live in the session (e.g. `continue-retry` re-runs a faulted activity with the fix); `rejected` edits (each with a reason) are structural changes that need a session restart to take effect.

## uip rpa debug toggle-breakpoint

Toggle a breakpoint at the currently focused activity (`.xaml`) or line (`.cs`). No options. XAML cycles enabled → disabled → none; coded workflows cycle on/off.

## uip rpa debug restart-from-top

Restart the active debug session from the beginning. No options.

## uip rpa execution cancel

Cancel the currently active execution or debug session — works uniformly for both `run` and `debug start`. No options.

### Example

```bash
uip rpa execution cancel
```

## Related

- [`uip rpa run-file`](./uip-rpa-run-file.md) / `uip rpa stop-execution` — the hidden legacy aliases these verbs replaced; same underlying tools.
- [`uip rpa start-studio`](./uip-rpa-start-studio.md) — pay the Studio startup cost in a dedicated setup step.
- [`uip rpa remote`](./uip-rpa-remote.md) — configure the target for `--remote`.
- [`uip rpa get-errors`](./uip-rpa-get-errors.md) — inspect diagnostics after a run.

## See also

- [RPA tool overview](./uip-rpa.md)
- [Global options](./global-options.md)
- [Exit codes](./exit-codes.md)