uip rpa run-file

Syntax and options for `uip rpa run-file`, which runs or debugs a workflow or coded file, with support for start, pause, step, and breakpoints.

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 first is optional, but useful when you want the startup cost paid in a dedicated setup step.

Note:

run-file is now a hidden legacy alias — it still works, but current source (tool-names.ts, CLI_DERIVED_COMMANDS) splits this same underlying operation into a discoverable family of top-level verbs: uip rpa run (start execution), uip rpa debug start / start-from-here / test-activity / break / continue / resume / continue-retry / continue-ignore / step-into / step-over / step-out / state / set-breakpoints / apply-file-changes / toggle-breakpoint / restart-from-top, and uip rpa execution cancel (replaces stop-execution). Each derived verb takes only the flags relevant to it, rather than one --command enum with the full 19-value list. This page's own examples still work today via the hidden alias — see uip rpa run, debug & execution for the current primary surface.

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

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.
GetDebugState	Report the current debug session state with no side effects (None when no session is active). Always an instant probe on the Studio backend; on the Helm backend it can long-poll for the next stable state.
SetBreakpoints	Replace the active debug session's whole breakpoint set with --breakpoints. Helm backend only — on the Studio backend, set breakpoints via ToggleBreakpoint or by passing them to StartDebugging instead.
ApplyFileChanges	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 file first, then call this naming what changed. Returns { applied, rejected, debugState } instead of a run result — structural (non-hot-reloadable) edits are rejected and need a session restart.

Examples

# 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 — 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
• Global options
• Exit codes