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. Exit codes follow the standard contract.

Synopsis

uip maestro flow instance list                <instance-id>             -f <folder-key> [-l <limit>] [--offset <n>] [--process-key <k>] [--package-id <id>] [--error-code <code>]
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 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>

-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 (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 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 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.

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

# 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 — read incidents detached from a specific instance
• uip maestro flow job — the job view of an instance run
• uip maestro flow process — start new instances
• Orchestrator jobs
• Flow overview