# uip maestro bpmn debug-instance

> Syntax and options for `uip maestro bpmn debug-instance`, which drives an interactive, breakpoint-capable debug session against an already-uploaded Studio Web solution.

`uip maestro bpmn debug-instance` drives a low-level, interactive debug session — create the instance, inspect its status/variables/incidents, set breakpoints, and step it forward. It's registered under the `bpmn` branch.

This is a different, lower-level surface than [`uip maestro bpmn debug`](./uip-maestro-bpmn-debug.md): `debug` is a one-shot "upload and run to completion" command. `debug-instance` assumes the solution is already uploaded to Studio Web and gives you manual control over one debug run — pausing at breakpoints, inspecting variables mid-run, and stepping forward — the interactive counterpart, referenced by `debug`'s own error instructions when a debug session needs step-level control.

## Synopsis

```
uip maestro bpmn 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 bpmn debug-instance status         <instance-id>
uip maestro bpmn debug-instance breakpoints    <instance-id> --inputs <json|@file>
uip maestro bpmn debug-instance cancel         <instance-id>
uip maestro bpmn debug-instance continue       <instance-id> [--inputs <json|@file>]
uip maestro bpmn debug-instance incidents      <instance-id>
uip maestro bpmn debug-instance variables      <instance-id> [--parent-element-id <id>]
uip maestro bpmn debug-instance variables-set  <instance-id> --inputs <json|@file> [--parent-element-id <id>]
uip maestro bpmn debug-instance variables-all  <instance-id>
```

All subcommands require `uip login`, honor [global options](./global-options.md), and follow the [standard exit-code contract](./exit-codes.md).

## uip maestro bpmn debug-instance create

Create a debug instance from a solution already uploaded to Studio Web, and begin a debug session in Orchestrator's personal workspace folder.

### Options

| Option | Required | 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 | Process type. Default `processOrchestration`. |
| `--debug-mode <mode>` | no | One of `None`, `Default` (pause at breakpoints), `StepByStep` (pause at every step), `SingleStep` (one step only). Default `Default`. An invalid value fails fast listing the accepted set. |
| `--simulation-mode <mode>` | no | One of `None`, `All` (simulate all elements), `Selective` (simulate except opt-outs). Default `None`. An invalid value fails fast listing the accepted set. |
| `-i, --inputs <json>` | no | Input arguments as a JSON string. Default `{}`. |

### Data shape

```json
{
  "Code": "DebugInstanceCreated",
  "Data": {
    "instanceId": "c3d4e5f6-...",
    "runId": "d4e5f6a7-...",
    "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 bpmn debug-instance status

Get the current per-element execution status of a debug instance.

**Arguments**: `<instance-id>` *(required)*. **Data shape**: `Code: "DebugInstanceStatus"`.

## uip maestro bpmn debug-instance breakpoints

Replace the breakpoint set on a debug instance.

**Arguments**: `<instance-id>` *(required)*.

**Options**: `--inputs <value>` — breakpoints payload as a JSON string, `@file` path, or piped via stdin. If omitted, an empty breakpoint list (`{"breakpoints": []}`) is sent, clearing all breakpoints.

**Data shape**: `Code: "DebugInstanceBreakpointsUpdated"`.

## uip maestro bpmn debug-instance cancel

Cancel a debug instance.

**Arguments**: `<instance-id>` *(required)*. **Data shape**: `Code: "DebugInstanceCanceled"`.

## uip maestro bpmn debug-instance continue

Resume execution on a paused debug instance.

**Arguments**: `<instance-id>` *(required)*.

**Options**: `--inputs <value>` — continue payload as a JSON string, `@file` path, or piped via stdin. If omitted, `{"nextStep": false}` is sent (run to the next breakpoint rather than a single step).

**Data shape**: `Code: "DebugInstanceContinued"`.

## uip maestro bpmn debug-instance incidents

Get incidents raised during a debug instance's run.

**Arguments**: `<instance-id>` *(required)*. **Data shape**: `Code: "DebugInstanceIncidents"`, `Data` is an array (empty when there are none).

## uip maestro bpmn debug-instance variables

Get a debug instance's current variable values.

**Arguments**: `<instance-id>` *(required)*.

**Options**: `--parent-element-id <id>` — filter variables by parent element ID.

**Data shape**: `Code: "DebugInstanceVariables"`.

## uip maestro bpmn debug-instance variables-set

Patch (update) a debug instance's variables mid-run.

**Arguments**: `<instance-id>` *(required)*.

**Options**:

| Option | Required | Description |
|---|---|---|
| `--inputs <value>` | **yes** | Patch-variables payload as a JSON string, `@file` path, or piped via stdin. Fails if no payload resolves. |
| `--parent-element-id <id>` | no | Scope the patch to a parent element ID. |

**Data shape**: `Code: "DebugInstanceVariablesSet"`.

## uip maestro bpmn debug-instance variables-all

Get every variable for a debug instance, including subprocess variables.

**Arguments**: `<instance-id>` *(required)*. **Data shape**: `Code: "DebugInstanceVariablesAll"`.

## Examples

```bash
# Create a debug session, stepping through one element at a time
uip maestro bpmn debug-instance create \
  --solution-id <solution-id> --project-id <project-id> \
  --entry-point "/Main.bpmn#start" --debug-mode StepByStep

# Check status, then step forward
uip maestro bpmn debug-instance status <instance-id>
uip maestro bpmn debug-instance continue <instance-id>

# Inspect and patch a variable mid-run
uip maestro bpmn debug-instance variables <instance-id>
uip maestro bpmn debug-instance variables-set <instance-id> --inputs '{"amount": 250}'

# Clean up
uip maestro bpmn debug-instance cancel <instance-id>
```

## See also

- [`uip maestro bpmn debug`](./uip-maestro-bpmn-debug.md) — one-shot upload-and-run debug session
- [`uip maestro bpmn instance`](./uip-maestro-bpmn-instances.md) — the equivalent operations on a *published* process instance, rather than a debug session
- [Maestro overview](./uip-maestro-bpmn.md)