# uip rpa run-file

> `uip rpa run-file` runs or debugs a workflow or coded file. The same verb covers the full execution lifecycle — start, pause, resume, step, restart, stop, toggle a breakpoint — selected by the `--command` flag. It is the bridge from a script or AI agent to Studio's debugger.

`uip rpa run-file` runs or debugs a workflow or coded file. The same verb covers the full execution lifecycle — start, pause, resume, step, restart, stop, toggle a breakpoint — selected by the `--command` flag. It is the bridge from a script or AI agent to Studio's debugger.

Execution happens through Studio, so the command works only on Windows runners (Studio is Windows-only). If Studio is not already running, the tool brings it up automatically — running [`uip rpa start-studio`](./uip-rpa-start-studio.md) first is optional, but useful when you want the startup cost paid in a dedicated setup step.

## Synopsis

```
uip rpa run-file --file-path <path> [--command <verb>] [options]
```

## Options

| Flag | Description |
|---|---|
| `--file-path <string>` | **Required.** Path to the file to run — `.xaml` workflow or `.cs` coded workflow. |
| `--command <verb>` | What to do. Defaults to `StartExecution`. See [Command verbs](#command-verbs) below. |
| `--input-arguments <json>` | JSON object with project-level input arguments. Used by all commands. For `StartExecution` / `StartDebugging`, values are plain JSON (`{"name":"John","age":30}`). For `TestActivity` / `StartDebuggingFromHere`, values are VB.NET or C# expressions. |
| `--input-variables <json>` | JSON object with workflow-level variable values. Applies only to `TestActivity` and `StartDebuggingFromHere`. Values are language expressions, not literal JSON. |
| `--log-level <level>` | Minimum log level included in the output stream — `Verbose`, `Trace`, `Information`, `Warning`, `Error`, `Critical`. Defaults to `Trace`. |
| `--skip-build` | Skip validation and build for `StartExecution` / `StartDebugging`. Assumes the project was already built — use for rapid re-execution when the project hasn't changed. |

For the complete option list on your installed tool version, run:

```bash
uip rpa run-file --help
```

## Command verbs

The `--command` flag covers two execution modes: **non-debug execution**, and **debugger control**. Verbs are case-sensitive and pass through to Studio.

### Execution

| Verb | Effect |
|---|---|
| `StartExecution` *(default)* | Run the workflow at `--file-path`. No debugger attached. |
| `StartDebugging` | Start a debugging session for the workflow. |
| `Stop` | Stop the current execution or debugging session. |
| `ForceSessionEnded` | Force-end the current session if the graceful stop hangs. |

### Debugger control

| Verb | Effect |
|---|---|
| `Break` | Pause execution. |
| `Continue` | Resume from a paused state. |
| `Resume` | Resume from a suspended state. |
| `ContinueRetry` | Resume; if paused on an exception, retry the current activity. |
| `ContinueIgnore` | Resume; if paused on an exception, swallow the exception. |
| `StepInto` / `StepOver` / `StepOut` | Step in the standard debugger sense. |
| `RestartFromTop` | Restart debugging from the beginning. |
| `ToggleBreakpoint` | Toggle a breakpoint at the focused activity (`.xaml`) or line (`.cs`). XAML cycles enabled → disabled → none; coded workflows cycle on / off. |
| `TestActivity` | Isolate and execute the focused activity, with `--input-variables` / `--input-arguments` providing in-scope expressions. |
| `StartDebuggingFromHere` | Start debugging from the focused activity, skipping everything before it. |

## Examples

```bash
# Run a workflow with input arguments
uip rpa run-file \
  --file-path ./Main.xaml \
  --input-arguments '{"customerId": "ACME-1234"}'

# Start a debug session
uip rpa run-file \
  --file-path ./Main.xaml \
  --command StartDebugging

# Toggle a breakpoint at the focused activity, then start debugging
uip rpa run-file --file-path ./Main.xaml --command ToggleBreakpoint
uip rpa run-file --file-path ./Main.xaml --command StartDebugging

# Test a single activity with a custom variable expression (VB.NET project)
uip rpa run-file \
  --file-path ./Main.xaml \
  --command TestActivity \
  --input-variables '{"greeting": "\"Hello World\""}'

# Stop a runaway session
uip rpa run-file --file-path ./Main.xaml --command Stop
```

## Related

- [`uip rpa start-studio`](./uip-rpa-start-studio.md) — pay the Studio startup cost in a dedicated setup step.
- `uip rpa stop-execution` — equivalent of `--command Stop` as a standalone verb.
- `uip rpa get-errors` — inspect diagnostics after a run.

## See also

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