# uip maestro flow debug-instance

> Syntax and options for `uip maestro flow debug-instance`, a low-level debugger control surface for stepping through, inspecting, and steering a Studio Web debug session.

`uip maestro flow debug-instance` is a low-level debugger control surface — create a debug instance, then step through it, inspect its variables and incidents, and cancel or continue it. This is a different, more granular layer than [`uip maestro flow debug`](./uip-maestro-flow-debug.md), which uploads a project and polls to completion in one call. `debug-instance` is what you'd reach for to build a custom debugging tool (for example, an editor integration) around Studio Web's debug protocol, driving one step at a time.

## Synopsis

```
uip maestro flow debug-instance create        --solution-id <id> --project-id <id> --entry-point <path> [--process-type <type>] [--debug-mode <mode>] [--simulation-mode <mode>] [-i, --inputs <json>]
uip maestro flow debug-instance status         <instance-id>
uip maestro flow debug-instance breakpoints    <instance-id> [--inputs <json|@file>]
uip maestro flow debug-instance cancel         <instance-id>
uip maestro flow debug-instance continue       <instance-id> [--inputs <json|@file>]
uip maestro flow debug-instance incidents      <instance-id>
uip maestro flow debug-instance variables      <instance-id> [--parent-element-id <id>]
uip maestro flow debug-instance variables-set  <instance-id> [--inputs <json|@file>]
uip maestro flow debug-instance variables-all  <instance-id>
```

Honors [global options](./global-options.md). Exit codes follow the [standard contract](./exit-codes.md). Requires `uip login`.

## uip maestro flow debug-instance create

Begin a debug session in Orchestrator and create the corresponding debug instance for an already-uploaded solution.

### Options

| Option | Required | Default | Description |
|---|---|---|---|
| `--solution-id <id>` | yes | — | Solution ID from a previous upload or Studio Web. |
| `--project-id <id>` | yes | — | Studio Web project ID within the solution. |
| `--entry-point <path>` | yes | — | Entry point path, e.g. `/Main.bpmn#start`. |
| `--process-type <type>` | no | `processOrchestration` | Process type. |
| `--debug-mode <mode>` | no | `Default` | `Default` (pause at breakpoints), `StepByStep` (pause at every step), or `SingleStep` (execute exactly one step). |
| `--simulation-mode <mode>` | no | `None` | `None`, `All` (simulate every element), or `Selective` (simulate except opt-outs). |
| `-i, --inputs <json>` | no | `{}` | Input arguments as a JSON string. |

Invalid `--debug-mode`/`--simulation-mode` values fail fast, listing the valid set.

### Data shape

```json
{
  "Code": "DebugInstanceCreated",
  "Data": {
    "instanceId": "…",
    "runId": "…",
    "jobKey": "b2c3d4e5-…"
  },
  "Instructions": "Use 'debug-instance status <instance-id>' to check the run. Use 'debug-instance incidents <instance-id>' or 'debug-instance variables <instance-id>' to inspect it."
}
```

## uip maestro flow debug-instance status

Get per-element execution status. Argument: `<instance-id>`. Data shape: `Code: "DebugInstanceStatus"`.

## uip maestro flow debug-instance breakpoints

Update the breakpoint set for a paused instance. Argument: `<instance-id>`. Option: `--inputs <value>` — breakpoints payload as a JSON string, an `@file` path, or piped via stdin. Data shape: `Code: "DebugInstanceBreakpointsUpdated"`.

## uip maestro flow debug-instance cancel

Cancel a debug instance. Argument: `<instance-id>`. Data shape: `Code: "DebugInstanceCanceled"`.

## uip maestro flow debug-instance continue

Resume execution on a paused instance. Argument: `<instance-id>`. Option: `--inputs <value>` — a JSON string, `@file` path, or stdin; defaults to `{"nextStep": false}` when omitted (run to the next breakpoint rather than a single step). Data shape: `Code: "DebugInstanceContinued"`.

## uip maestro flow debug-instance incidents

Get incidents raised during the debug session. Argument: `<instance-id>`. Data shape: `Code: "DebugInstanceIncidents"`, `Data` is an array (empty if none).

## uip maestro flow debug-instance variables

Get variables for the instance. Argument: `<instance-id>`. Option: `--parent-element-id <id>` — filter to variables scoped under one element. Data shape: `Code: "DebugInstanceVariables"`.

## uip maestro flow debug-instance variables-set

Patch (partially update) variables. Argument: `<instance-id>`. Option: `--inputs <value>` — patch payload as JSON string, `@file` path, or stdin. Data shape: `Code: "DebugInstanceVariablesSet"`.

## uip maestro flow debug-instance variables-all

Get all variables, including subprocess scopes. Argument: `<instance-id>`. Data shape: `Code: "DebugInstanceVariablesAll"`.

## See also

- [`uip maestro flow debug`](./uip-maestro-flow-debug.md) — the higher-level, upload-and-poll debug command most workflows should use instead
- [`uip maestro flow instance`](./uip-maestro-flow-instances.md) — the equivalent control surface for a published, running instance rather than a debug session
- [Flow overview](./uip-maestro-flow.md)
- [Global options](./global-options.md), [Exit codes](./exit-codes.md)