# uip maestro instances

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

`uip maestro instance` inspects and steers individual **process instances** — one execution of a published Maestro 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).

## Synopsis

```
uip maestro instance list                                  -f <folder-key> [-l <limit>] [--offset <n>] [--process-key <k>] [--package-id <id>] [--error-code <code>]
uip maestro instance get                 <instance-id>     -f <folder-key>
uip maestro instance pause               <instance-id>     -f <folder-key> [--comment <text>]
uip maestro instance resume              <instance-id>     -f <folder-key> [--comment <text>]
uip maestro instance cancel              <instance-id>     -f <folder-key> [--comment <text>]
uip maestro instance retry               <instance-id>     -f <folder-key> [--comment <text>]
uip maestro instance migrate             <instance-id> <new-version> -f <folder-key> [--comment <text>]
uip maestro instance variables           <instance-id>     -f <folder-key> [--parent-element-id <id>]
uip maestro instance incidents           <instance-id>     -f <folder-key>
uip maestro instance asset               <instance-id>     -f <folder-key>
uip maestro instance cursors             <instance-id>     -f <folder-key>
uip maestro instance goto                <instance-id> <transitions> -f <folder-key>
uip maestro instance element-executions  <instance-id>     -f <folder-key>
```

**`-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 instance list

List instances in a folder, scoped to `processType=ProcessOrchestration`.

#### Options

| Option | Default | Description |
|---|---|---|
| `-l, --limit <n>` | `DEFAULT_PAGE_SIZE` | Number of items to return (1-10000). |
| `--offset <n>` | `0` | Number of items to skip (0-1000000). |
| `--process-key <k>` | — | Filter by process key. |
| `--package-id <id>` | — | Filter by package ID. |
| `--error-code <code>` | — | Filter by error code. |

#### Data shape

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

### uip maestro instance get

Fetch a single instance by ID. **Data shape**: `Code: "InstanceGet"`, `Data` is the process-instance object.

### uip maestro instance pause

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

### uip maestro instance resume

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

### uip maestro instance cancel

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

### uip maestro instance retry

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

### uip maestro instance migrate

Migrate an instance to a different package version.

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

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

### uip maestro 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 instance incidents

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

### uip maestro instance asset

Fetch the BPMN asset attached to this instance's release.

**Data shape**: `Code: "InstanceAsset"`, `Data` is the BPMN asset payload.

### uip maestro 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 instance goto

Move an execution cursor from one element to another.

#### Arguments

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

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

#### Data shape

`Code: "InstanceGoto"`.

### uip maestro instance element-executions

Get the per-element execution history for an instance.

#### Data shape

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

## Examples

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

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

# Inspect cursors, jump a faulted node, retry
uip maestro instance cursors <id> --folder-key <k>
uip maestro instance goto    <id> '[{"sourceElementId":"A","targetElementId":"C"}]' --folder-key <k>
uip maestro instance retry   <id> --folder-key <k>

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

## See also

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