# uip maestro bpmn instances > Syntax and options for `uip maestro bpmn instance`, which inspects and steers individual Maestro BPMN process instances. `uip maestro bpmn instance` inspects and steers individual **process instances** — one execution of a published Maestro BPMN process. The command name is singular (`instance`) even though the sidebar entry says `instances`. Every verb here is registered under the `bpmn` branch — there is no bare `uip maestro bpmn instance`. All subcommands require `uip login` and honor [global options](./global-options.md). Exit codes follow the [standard contract](./exit-codes.md). ## Synopsis ``` uip maestro bpmn instance list -f [-l ] [--next-page ] [--process-key ] [--package-id ] [--error-code ] [--status ]... [--from-date ] [--to-date ] uip maestro bpmn instance get -f uip maestro bpmn instance pause -f [--comment ] uip maestro bpmn instance resume -f [--comment ] uip maestro bpmn instance cancel -f [--comment ] uip maestro bpmn instance retry -f [--comment ] uip maestro bpmn instance migrate -f [--comment ] uip maestro bpmn instance variables -f [--parent-element-id ] uip maestro bpmn instance variables-set -f --inputs uip maestro bpmn instance variables-all -f uip maestro bpmn instance global-variables -f uip maestro bpmn instance incidents -f uip maestro bpmn instance asset -f uip maestro bpmn instance cursors -f uip maestro bpmn instance goto -f uip maestro bpmn instance element-executions -f uip maestro bpmn instance message send -f --inputs uip maestro bpmn instance element cancel -f [--comment ] uip maestro bpmn instance element retry -f [--comment ] ``` **`-f, --folder-key `** is required on every subcommand. ## Common options - `-f, --folder-key ` *(required)* — folder key (GUID). - `--comment ` *(operation commands only)* — optional comment recorded with the operation. Sent as an empty string if omitted. ## Subcommands ### uip maestro bpmn instance list List instances in a folder, scoped to `processType=ProcessOrchestration`. Filters are applied server-side. Results page by cursor, not offset — read `Pagination.NextPage` from a response and pass it back via `--next-page`. #### Options | Option | Default | Description | |---|---|---| | `-l, --limit ` | `DEFAULT_PAGE_SIZE` | Number of items to return (1-500). | | `--next-page ` | — | Cursor from a previous response's `Pagination.NextPage`. | | `--offset ` | — | **Not supported by this API.** `--offset 0` is silently accepted as a no-op (equivalent to no cursor); any other value fails with an error telling you to use `--next-page` instead. | | `--process-key ` | — | Filter by process key — must be a GUID. For the dotted package identifier (e.g. `InvoiceOrchestration:1.0.0`) that `uip or processes list` prints as `ProcessKey`, use `--package-id` instead. | | `--package-id ` | — | Filter by package ID (the dotted package identifier). | | `--error-code ` | — | Filter by error code. | | `--status ` | — | Filter by instance status. Repeatable, OR-semantics. An invalid value fails fast listing the accepted set. | | `--from-date ` | — | Only include instances started at or after this timestamp, e.g. `2026-01-01T00:00:00Z`. | | `--to-date ` | — | Only include instances started at or before this timestamp. | #### Data shape `Code: "InstanceList"`, `Data` is an array of process-instance objects, plus a `Pagination` block (`returned`, `limit`, `hasMore`, `nextPage`). ### uip maestro bpmn instance get Fetch a single instance by ID. **Data shape**: `Code: "InstanceGet"`, `Data` is the process-instance object. ### uip maestro bpmn instance pause Pause a running instance. **Data shape**: `Code: "InstancePaused"`. ### uip maestro bpmn instance resume Resume a paused instance. **Data shape**: `Code: "InstanceResumed"`. ### uip maestro bpmn instance cancel Cancel a running instance. **Data shape**: `Code: "InstanceCanceled"`. ### uip maestro bpmn instance retry Retry a faulted instance. **Data shape**: `Code: "InstanceRetried"`. ### uip maestro bpmn instance migrate Migrate an instance to a different package version. **Arguments**: ``, `` (target package version). **Data shape**: `Code: "InstanceMigrated"`. ### uip maestro bpmn instance variables Get variables for an instance. **Options**: `--parent-element-id ` — filter variables by parent element. **Data shape**: `Code: "InstanceVariables"`, `Data` carries the instance variables payload. ### uip maestro bpmn instance variables-set Patch (update) variables for a running instance. #### Options | Option | Description | |---|---| | `--inputs ` | Patch-variables payload as a JSON string, `@file` path, or piped via stdin. Required (the command fails if no payload resolves). | #### Data shape `Code: "InstanceVariablesSet"`. ### uip maestro bpmn instance variables-all Get every variable for an instance, including subprocess variables. **Data shape**: `Code: "InstanceVariablesAll"`. ### uip maestro bpmn instance global-variables Get an instance's global variables. **Data shape**: `Code: "InstanceGlobalVariables"`. ### uip maestro bpmn instance incidents **Data shape**: `Code: "InstanceIncidents"`, `Data` is an array of incident objects. ### uip maestro bpmn instance asset Fetch the BPMN asset attached to this instance's release. **Data shape**: `Code: "InstanceAsset"`, `Data` is the BPMN asset payload. ### uip maestro bpmn 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 bpmn instance goto Move an execution cursor from one element to another. #### Arguments - `` *(required)* - `` *(required)* — JSON array of transitions, each with `sourceElementId` and `targetElementId`. ```bash uip maestro bpmn instance goto c3d4e5f6-… \ '[{"sourceElementId":"Activity_1","targetElementId":"Activity_3"}]' \ --folder-key c3d4e5f6-… ``` #### Data shape `Code: "InstanceGoto"`. ### uip maestro bpmn instance element-executions Get the per-element execution history for an instance. #### Data shape `Code: "InstanceElementExecutions"`, `Data` is the per-element execution history. ### uip maestro bpmn instance message send Send a message to workflow subscriptions listening on this process — not scoped to a single instance ID; the vendor payload determines which instance(s) the message reaches. #### Options | Option | Required | Description | |---|---|---| | `-f, --folder-key ` | yes | Folder key (GUID). | | `--inputs ` | — | Message payload as a JSON string, `@file` path, or piped via stdin. Fails if no payload resolves. | #### Data shape `Code: "MessageSent"`. ### uip maestro bpmn instance element cancel Cancel one element within a running instance, without canceling the whole instance. #### Arguments - `` *(required)* - `` *(required)* #### Options | Option | Description | |---|---| | `-f, --folder-key ` | Folder key (GUID). Required. | | `--comment ` | Optional comment for the operation. | #### Data shape `Code: "ElementCanceled"`. ### uip maestro bpmn instance element retry Retry one faulted element within an instance. #### Arguments - `` *(required)* - `` *(required)* #### Options | Option | Description | |---|---| | `-f, --folder-key ` | Folder key (GUID). Required. | | `--comment ` | Optional comment for the operation. | #### Data shape `Code: "ElementRetried"`. ## Examples ```bash # Paginate through instances for a specific process, filtered by status uip maestro bpmn instance list --folder-key \ --status Faulted --status Paused --limit 50 # Page through with the cursor from a previous response uip maestro bpmn instance list --folder-key --next-page # Pause, fix, resume uip maestro bpmn instance pause --folder-key --comment "Investigating" uip maestro bpmn instance resume --folder-key # Inspect cursors, jump a faulted node, retry uip maestro bpmn instance cursors --folder-key uip maestro bpmn instance goto '[{"sourceElementId":"A","targetElementId":"C"}]' --folder-key uip maestro bpmn instance retry --folder-key # Upgrade a long-running instance to a new package version uip maestro bpmn instance migrate "1.2.0" --folder-key --comment "Patch release" # Retry a single faulted element instead of the whole instance uip maestro bpmn instance element retry Activity_2 --folder-key # Patch a variable on a running instance uip maestro bpmn instance variables-set --folder-key --inputs '{"amount": 250}' ``` ## See also - [`uip maestro bpmn incidents`](./uip-maestro-bpmn-incidents.md) — incidents detached from a specific instance - [`uip maestro bpmn job`](./uip-maestro-bpmn-job.md) — the job view of an instance run - [`uip maestro bpmn process`](./uip-maestro-bpmn-process.md) — start new instances - [Orchestrator jobs](./uip-or-jobs.md) - [Maestro overview](./uip-maestro-bpmn.md)