# uip maestro process and uip maestro processes

> Once a Maestro package is published to Orchestrator it becomes a **process** of type `ProcessOrchestration`. This page covers two related command groups:

Once a Maestro package is published to Orchestrator it becomes a **process** of type `ProcessOrchestration`. This page covers two related command groups:

- **`uip maestro process`** — per-folder operations on a single process definition (list in a folder, get its schema, run it).
- **`uip maestro processes`** *(plural)* — tenant-wide summaries and per-process incident lookup.

## Synopsis

```
# Singular — per-folder, operational
uip maestro process list -f <folder-key> [-t <tenant>] [--filter <odata>] [--login-validity <minutes>]
uip maestro process get  <process-key> <feed-id> -f <folder-key> [-t <tenant>] [--login-validity <minutes>]
uip maestro process run  <process-key> <folder-key>
                          [-i, --inputs <json>] [-t, --tenant <name>]
                          [--release-key <key>] [--feed-id <id>] [--robot-ids <ids>]
                          [--validate] [--login-validity <minutes>]

# Plural — tenant-wide summary and incident surface
uip maestro processes list
uip maestro processes incidents <process-key> [--folder-key <key>]
```

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

---

## uip maestro process list

List available Maestro processes (releases) in a specific folder.

### Options

| Option | Required | Description |
|---|---|---|
| `-f, --folder-key <key>` | yes | Folder key (GUID). |
| `-t, --tenant <name>` | no | Tenant name. Defaults to the authenticated tenant. |
| `--filter <odata>` | no | Additional OData filter applied server-side. |
| `--login-validity <minutes>` | no | Token-refresh threshold (default `10`). |

### Data shape (`--output json`)

```json
{
  "Code": "MaestroProcessList",
  "Data": [
    {
      "name":       "InvoiceOrchestration",
      "processKey": "a1b2c3d4-0000-0000-0000-000000000001:1.0.0",
      "releaseKey": "e5f6a7b8-0000-0000-0000-000000000001",
      "folderKey":  "c3d4e5f6-0000-0000-0000-000000000001",
      "feedId":     "default",
      "folderId":   42,
      "active":     "Yes",
      "latest":     "Yes"
    }
  ]
}
```

---

## uip maestro process get

Fetch the entry-point schema (input/output JSON schemas) for a Maestro process.

### Arguments

- `<process-key>` *(required)* — process key.
- `<feed-id>` *(required)* — feed ID (from `list`).

### Options

- `-f, --folder-key <key>` *(required)*
- `-t, --tenant`
- `--login-validity`

### Data shape

```json
{
  "Code": "MaestroProcessGet",
  "Data": [
    {
      "Path":         "/content/main.bpmn#Event_start",
      "DisplayName":  "Manual trigger",
      "Type":         "processorchestration",
      "InputSchema":  "{\"type\":\"object\",\"properties\":{}}",
      "OutputSchema": "{\"type\":\"object\",\"properties\":{}}"
    }
  ]
}
```

`InputSchema` and `OutputSchema` are re-stringified JSON Schema strings.

---

## uip maestro process run

Start a Maestro job for a published process.

### Arguments

- `<process-key>` *(required)* — process key.
- `<folder-key>` *(required)* — folder key (GUID).

### Options

| Option | Description |
|---|---|
| `-i, --inputs <json>` | Inputs as a JSON string or `@path/to/file.json`. If omitted and stdin is piped, stdin is parsed. |
| `-t, --tenant <name>` | Tenant name (defaults to authenticated tenant). |
| `--release-key <key>` | Release key (GUID) — from `process list`. |
| `--feed-id <id>` | Feed ID for package lookup (optional). |
| `--robot-ids <ids>` | Comma-separated robot IDs (integers). Invalid values fail fast. |
| `--validate` | Validate inputs against the process schema before running. Basic checks only — required fields + primitive types. |
| `--login-validity <minutes>` | Token-refresh threshold (default `10`). |

**Input precedence**: `--inputs <json>` / `--inputs @file.json` > stdin > empty object `{}`.

### Examples

```bash
# Inline JSON
uip maestro process run "InvoiceOrchestration:1.0.0" "<folder-key>" \
  --inputs '{"amount":100}'

# From a file
uip maestro process run "InvoiceOrchestration:1.0.0" "<folder-key>" --inputs @inputs.json

# Piped stdin
echo '{"amount":100}' | uip maestro process run "InvoiceOrchestration:1.0.0" "<folder-key>"

# Validate before running
uip maestro process run "InvoiceOrchestration:1.0.0" "<folder-key>" \
  --inputs '{"amount":100}' --validate
```

### Data shape

```json
{
  "Code": "MaestroJobStarted",
  "Data": {
    "jobKey":  "b2c3d4e5-0000-0000-0000-000000000001",
    "state":   "Pending",
    "traceId": "d4e5f6a7-0000-0000-0000-000000000001"
  }
}
```

Next step: `uip maestro job traces <jobKey>` to stream execution or `uip maestro job status <jobKey>` to poll.

---

## uip maestro processes list

Tenant-wide summary of Maestro processes (no `processType` filter applied at this layer — the plural command is shared across tools and does not scope to `ProcessOrchestration` server-side).

### Arguments

None.

### Data shape

```json
{
  "Code": "ProcessList",
  "Data": [ /* array of Maestro process summaries */ ]
}
```

:::note
The exact field set of each process summary is specified by the Maestro runtime and may evolve; run the command once with `--output json` against a tenant with data to see the fields you will be consuming, and pin `@uipath/cli` in CI if you parse specific fields.
:::

---

## uip maestro processes incidents

Get all incidents for a specific Maestro process definition.

### Arguments

- `<process-key>` *(required)* — process definition key.

### Options

- `--folder-key <key>` *(optional)* — folder key to scope the lookup.

### Data shape

```json
{
  "Code": "ProcessIncidents",
  "Data": [ /* array of process incidents */ ]
}
```

## See also

- [`uip maestro instances`](./uip-maestro-instances.md) — inspect and steer running executions
- [`uip maestro job`](./uip-maestro-job.md) — traces and status for a single job
- [`uip maestro incidents`](./uip-maestro-incidents.md) — incident summaries and details
- [Orchestrator jobs](./uip-orchestrator-jobs.md), [Orchestrator processes](./uip-orchestrator-processes.md)
- [Maestro overview](./uip-maestro.md)