UiPath CLI - uip maestro flow debug

uipath-cli

latest

false

UiPath CLI user guide

uip maestro flow debug

Syntax and options for `uip maestro flow debug`, which uploads a local Flow project to Studio Web and runs a server-side debug session with streamed status updates.

uip maestro flow debug uploads a local Flow project to Studio Web and runs a server-side debug session, streaming per-element status updates back to the console and returning a final status.

Synopsis

uip maestro flow debug <project-path>
               [--folder-id <id> | --folder-key <key> | --folder-path <path>]
               [--poll-interval <ms>]
               [-i, --inputs <json>]
               [--attachment <name=path>]...
               [--open-in-browser]
               [--login-validity <minutes>]
uip maestro flow debug <project-path>
               [--folder-id <id> | --folder-key <key> | --folder-path <path>]
               [--poll-interval <ms>]
               [-i, --inputs <json>]
               [--attachment <name=path>]...
               [--open-in-browser]
               [--login-validity <minutes>]

Requires uip login. Honors global options. Exit codes follow the standard contract.

Arguments

<project-path> (required) — path to the Flow project directory. Must contain a project.uiproj.

Options

Option	Default	Description
`--folder-id <id>`	auto-detected	Orchestrator folder (`OrganizationUnitId`), a positive integer. Mutually exclusive with `--folder-key`/`--folder-path`. If none of the three are given, the folder on the current login session is used.
`--folder-key <key>`	—	Orchestrator folder key (UUID) — resolved to the folder ID by the CLI. Mutually exclusive with `--folder-id`/`--folder-path`.
`--folder-path <path>`	—	Orchestrator folder path, e.g. `Shared/Sub` — resolved to the folder ID by the CLI. Mutually exclusive with `--folder-id`/`--folder-key`. Use `uip or folders list` to discover valid keys/paths.
`--poll-interval <ms>`	`2000`	Polling interval in milliseconds while waiting for Studio Web to advance the session.
`-i, --inputs <json>`	—	Input arguments as a JSON string, or `@path/to/file.json` to read from a file.
`--attachment <name=path>`	—	Upload a local file to Orchestrator and bind it as a file-type input variable. Repeatable, e.g. `--attachment file1=./resume.pdf`. Overrides the same variable name if also present in `--inputs`.
`--open-in-browser`	—	Open the Studio Web session URL in a browser once available.
`--login-validity <minutes>`	`10`	Minimum minutes before token expiration to trigger an automatic refresh.

Behavior

Validates login and pulls the organization, tenant, base URL, organization name, and auth token from the session.
Uploads the project to Studio Web under the target folder.

Polls for a final status, emitting per-element status lines like:

Status: InProgress (2/5 elements completed)
  v Node_1 [Completed]
  > Node_2 [InProgress]
  - Node_3 [NotStarted]
Status: InProgress (2/5 elements completed)
  v Node_1 [Completed]
  > Node_2 [InProgress]
  - Node_3 [NotStarted]

On incidents during the run, emits a warning line.
Exits 0 if finalStatus is Completed or Successful; 1 otherwise.

Examples

# Debug a local project, auto-detect folder, default poll interval
uip maestro flow debug ./invoice-flow

# Debug against a specific folder with inline JSON inputs
uip maestro flow debug ./invoice-flow --folder-id 2553016 \
  --inputs '{"amount":100,"customer":"Acme"}'

# Debug with inputs from a file
uip maestro flow debug ./invoice-flow --inputs @inputs.json

# Slower polling for long-running flows
uip maestro flow debug ./invoice-flow --poll-interval 5000
# Debug a local project, auto-detect folder, default poll interval
uip maestro flow debug ./invoice-flow

# Debug against a specific folder with inline JSON inputs
uip maestro flow debug ./invoice-flow --folder-id 2553016 \
  --inputs '{"amount":100,"customer":"Acme"}'

# Debug with inputs from a file
uip maestro flow debug ./invoice-flow --inputs @inputs.json

# Slower polling for long-running flows
uip maestro flow debug ./invoice-flow --poll-interval 5000

Data shape (--output json)

{
  "Code": "FlowDebug",
  "Data": {
    "jobKey": "b2c3d4e5-0000-0000-0000-000000000001",
    "instanceId": "c3d4e5f6-0000-0000-0000-000000000001",
    "runId": "d4e5f6a7-0000-0000-0000-000000000001",
    "finalStatus": "Completed",
    "solutionId": "e5f6a7b8-0000-0000-0000-000000000001",
    "studioWebUrl": "https://cloud.uipath.com/org/tenant/studio_/debug/e5f6a7b8",
    "elementExecutions": [
      { "elementId": "Node_1", "status": "Completed" }
    ],
    "variables": {}
  }
}
{
  "Code": "FlowDebug",
  "Data": {
    "jobKey": "b2c3d4e5-0000-0000-0000-000000000001",
    "instanceId": "c3d4e5f6-0000-0000-0000-000000000001",
    "runId": "d4e5f6a7-0000-0000-0000-000000000001",
    "finalStatus": "Completed",
    "solutionId": "e5f6a7b8-0000-0000-0000-000000000001",
    "studioWebUrl": "https://cloud.uipath.com/org/tenant/studio_/debug/e5f6a7b8",
    "elementExecutions": [
      { "elementId": "Node_1", "status": "Completed" }
    ],
    "variables": {}
  }
}

Open studioWebUrl in a browser to inspect the session interactively.

Conversational-trigger handoff

A Flow whose entry point is core.trigger.conversation can only be driven by a chat UI — the CLI cannot start a debug session for it. Instead, it uploads the project to Studio Web and hands off:

{
  "Code": "FlowDebugStudioWebHandoff",
  "Data": {
    "solutionId": "e5f6a7b8-0000-0000-0000-000000000001",
    "studioWebUrl": "https://cloud.uipath.com/org/studio_/designer/a1b2c3d4?solutionId=e5f6a7b8",
    "handedOff": true
  }
}
{
  "Code": "FlowDebugStudioWebHandoff",
  "Data": {
    "solutionId": "e5f6a7b8-0000-0000-0000-000000000001",
    "studioWebUrl": "https://cloud.uipath.com/org/studio_/designer/a1b2c3d4?solutionId=e5f6a7b8",
    "handedOff": true
  }
}

No elementExecutions/finalStatus fields are present — nothing was run, so there's nothing to poll. Pass --open-in-browser to have the CLI open studioWebUrl automatically.

Faulted run — inline incidents

A faulted run is returned as a Result: "Failure" envelope (exit code 1), with incident details already inline on Data.incidents — no follow-up command is needed to see what broke:

{
  "Code": "FlowDebug",
  "Data": {
    "jobKey": "b2c3d4e5-0000-0000-0000-000000000001",
    "instanceId": "c3d4e5f6-0000-0000-0000-000000000001",
    "runId": "d4e5f6a7-0000-0000-0000-000000000001",
    "finalStatus": "Faulted",
    "incidents": [
      {
        "incidentId": "inc-1",
        "elementId": "Node_3",
        "errorCode": "Process.UnhandledException",
        "errorMessage": "Object reference not set to an instance of an object."
      }
    ]
  }
}
{
  "Code": "FlowDebug",
  "Data": {
    "jobKey": "b2c3d4e5-0000-0000-0000-000000000001",
    "instanceId": "c3d4e5f6-0000-0000-0000-000000000001",
    "runId": "d4e5f6a7-0000-0000-0000-000000000001",
    "finalStatus": "Faulted",
    "incidents": [
      {
        "incidentId": "inc-1",
        "elementId": "Node_3",
        "errorCode": "Process.UnhandledException",
        "errorMessage": "Object reference not set to an instance of an object."
      }
    ]
  }
}

On a faulted run, the error Instructions point you at uip maestro flow debug-instance incidents <instanceId> to inspect the raw backend payload — see debug-instance for that lower-level control surface.

Was this page helpful?

PREVIOUSpublish

NEXTdebug-instance

Synopsis​

Arguments​

Options​

Behavior​

Examples​

Data shape (--output json)​

Conversational-trigger handoff​

Faulted run — inline incidents​

See also​