# uip maestro flow instance

> Syntax and options for `uip maestro flow instance`, which inspects and steers individual Flow process instances.

`uip maestro flow instance` inspects and steers individual **process instances** — one execution of a published Flow process. The command name is singular (`instance`) even though the sidebar entry says `instances`.

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

This page shares its implementation with [`uip maestro bpmn instance`](./uip-maestro-bpmn-instances.md) — the same defects and fixes apply to both pages.

## Synopsis

```
uip maestro flow instance list                <instance-id>             -f <folder-key> [-l <limit>] [--next-page <cursor>] [--process-key <k>] [--package-id <id>] [--error-code <code>] [--status <status>]... [--from-date <iso-8601>] [--to-date <iso-8601>]
uip maestro flow instance get                 <instance-id>             -f <folder-key>
uip maestro flow instance pause               <instance-id>             -f <folder-key> [--comment <text>]
uip maestro flow instance resume              <instance-id>             -f <folder-key> [--comment <text>]
uip maestro flow instance cancel              <instance-id>             -f <folder-key> [--comment <text>]
uip maestro flow instance retry               <instance-id>             -f <folder-key> [--comment <text>]
uip maestro flow instance migrate             <instance-id> <new-version> -f <folder-key> [--comment <text>]
uip maestro flow instance variables           <instance-id>             -f <folder-key> [--parent-element-id <id>]
uip maestro flow instance variables-set       <instance-id>             -f <folder-key> --inputs <json|@file>
uip maestro flow instance variables-all       <instance-id>             -f <folder-key>
uip maestro flow instance global-variables    <instance-id>             -f <folder-key>
uip maestro flow instance incidents           <instance-id>             -f <folder-key>
uip maestro flow instance asset               <instance-id>             -f <folder-key>
uip maestro flow instance cursors             <instance-id>             -f <folder-key>
uip maestro flow instance goto                <instance-id> <transitions> -f <folder-key>
uip maestro flow instance element-executions  <instance-id>             -f <folder-key>
uip maestro flow instance element cancel      <instance-id> <element-id> -f <folder-key> [--comment <text>]
uip maestro flow instance element retry       <instance-id> <element-id> -f <folder-key> [--comment <text>]
uip maestro flow instance message send        -f <folder-key> [--inputs <json|@file>]
```

**`-f, --folder-key <key>`** is required on every subcommand.

## Common options

- `-f, --folder-key <key>` *(required)* — folder key (GUID).
- `--comment <text>` *(operation commands only)* — optional comment recorded with the operation. Sent as an empty string if omitted.

## Subcommands

### uip maestro flow instance list

List instances in a folder, scoped to Flow processes (`processType=Flow`).

#### Options

| Option | Default | Description |
|---|---|---|
| `-l, --limit <n>` | `DEFAULT_PAGE_SIZE` | Number of items to return. Bounded at **1-500** — stricter than this CLI's usual 1-10000 convention, because the instances API pages by cursor rather than offset. |
| `--next-page <cursor>` | — | Cursor from a previous response's `Pagination.NextPage`. This API does not support `--offset` at all — a non-zero `--offset` fails fast with an error telling you to use `--next-page` instead. |
| `--process-key <k>` | — | Filter by process key (GUID). For the dotted package identifier, use `--package-id`. |
| `--package-id <id>` | — | Filter by package ID. |
| `--error-code <code>` | — | Filter by error code. |
| `--status <status>` | — | Filter by instance status. Repeatable (OR-semantics). Values: `Canceling`, `Cancelled`, `Completed`, `Faulted`, `Paused`, `Pausing`, `Pending`, `Resuming`, `Retrying`, `Running`, `Upgrading`. |
| `--from-date <iso-8601>` | — | Only include instances started at or after this timestamp, e.g. `2026-01-01T00:00:00Z`. |
| `--to-date <iso-8601>` | — | Only include instances started at or before this timestamp. |

#### Data shape

`Code: "InstanceList"`, `Data` is an array of process-instance objects.

### uip maestro flow instance get

Fetch a single instance by ID.

**Data shape**: `Code: "InstanceGet"`, `Data` is the process-instance object.

### uip maestro flow instance pause

Pause a running instance. **Data shape**: `Code: "InstancePaused"`.

### uip maestro flow instance resume

Resume a paused instance. **Data shape**: `Code: "InstanceResumed"`.

### uip maestro flow instance cancel

Cancel a running instance. **Data shape**: `Code: "InstanceCanceled"`.

### uip maestro flow instance retry

Retry a faulted instance. **Data shape**: `Code: "InstanceRetried"`.

### uip maestro flow instance migrate

Migrate an instance to a different package version.

**Arguments**: `<instance-id>`, `<new-version>` (target package version).

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

### uip maestro flow instance variables

Get variables for an instance.

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

**Data shape**: `Code: "InstanceVariables"`, `Data` carries the instance variables payload.

### uip maestro flow instance variables-set

Patch (partially update) variables for an instance.

#### Options

| Option | Description |
|---|---|
| `--inputs <value>` | Patch-variables payload as a JSON string, an `@file` path, or piped via stdin. |

#### Data shape

`Code: "InstanceVariablesSet"`.

### uip maestro flow instance variables-all

Get all variables for an instance, including subprocess variables (unlike `variables`, which is scoped to the top-level process unless `--parent-element-id` is passed).

#### Data shape

`Code: "InstanceVariablesAll"`.

### uip maestro flow instance global-variables

Get an instance's global variables (shared across the whole process, not scoped to any element).

#### Data shape

`Code: "InstanceGlobalVariables"`.

### uip maestro flow instance element cancel

Cancel a specific element within a running instance, rather than the whole instance.

#### Arguments

- `<instance-id>` *(required)*
- `<element-id>` *(required)*

#### Options

- `--comment <text>` — optional comment recorded with the operation.

#### Data shape

`Code: "ElementCanceled"`.

### uip maestro flow instance element retry

Retry a specific faulted element within an instance, rather than retrying the whole instance.

#### Arguments

- `<instance-id>` *(required)*
- `<element-id>` *(required)*

#### Options

- `--comment <text>` — optional comment recorded with the operation.

#### Data shape

`Code: "ElementRetried"`.

### uip maestro flow instance message send

Send a message to workflow subscriptions listening on this folder — used to deliver an external event into a running Flow (for example, a webhook payload the process is waiting on).

#### Options

| Option | Description |
|---|---|
| `-f, --folder-key <key>` | *(required)* Folder key (GUID). |
| `--inputs <value>` | Message payload as a JSON string, an `@file` path, or piped via stdin. |

#### Data shape

`Code: "MessageSent"`.

### uip maestro flow instance incidents

Get incidents for a specific instance.

**Data shape**: `Code: "InstanceIncidents"`, `Data` is an array of incident objects.

### uip maestro flow instance asset

Fetch the Flow definition (the `.flow` asset) attached to this instance's release — useful when debugging to see the exact graph the instance ran.

**Data shape**: `Code: "InstanceAsset"`, `Data` is the Flow JSON.

### uip maestro flow instance cursors

Get current execution cursor positions — which element(s) the instance is paused at.

**Data shape**: `Code: "InstanceCursors"`, `Data` lists the current cursor positions.

### uip maestro flow instance goto

Move an execution cursor from one element to another. Useful for recovering a faulted instance by skipping or retrying specific nodes.

#### Arguments

- `<instance-id>` *(required)*
- `<transitions>` *(required)* — JSON array of transitions, each with `sourceElementId` and `targetElementId`.

```bash
uip maestro flow instance goto c3d4e5f6-… \
  '[{"sourceElementId":"Node_1","targetElementId":"Node_3"}]' \
  --folder-key c3d4e5f6-…
```

The CLI validates the JSON parses and each entry has both IDs before calling the API.

#### Data shape

`Code: "InstanceGoto"`.

### uip maestro flow instance element-executions

Get the per-element execution history for an instance (what ran, when, and with what outcome).

#### Data shape

`Code: "InstanceElementExecutions"`, `Data` is the per-element execution history.

## Examples

```bash
# Paginate through instances for a specific process
uip maestro flow instance list --folder-key <k> --process-key "InvoiceFlow.flow.Flow:1.0.0" --limit 50

# Pause, fix, resume
uip maestro flow instance pause   <id> --folder-key <k> --comment "Investigating"
uip maestro flow instance resume  <id> --folder-key <k>

# Skip a faulted node by moving the cursor forward, then retry
uip maestro flow instance cursors <id> --folder-key <k>
uip maestro flow instance goto    <id> '[{"sourceElementId":"A","targetElementId":"C"}]' --folder-key <k>
uip maestro flow instance retry   <id> --folder-key <k>

# Upgrade a long-running instance to a new package version
uip maestro flow instance migrate <id> "1.2.0" --folder-key <k> --comment "Patch release"
```

## See also

- [`uip maestro flow incident`](./uip-maestro-flow-incidents.md) — read incidents detached from a specific instance
- [`uip maestro flow job`](./uip-maestro-flow-job.md) — the job view of an instance run
- [`uip maestro flow process`](./uip-maestro-flow-process.md) — start new instances
- [Orchestrator jobs](./uip-or-jobs.md)
- [Flow overview](./uip-maestro-flow.md)