# uip maestro

> `uip maestro` authors, packs, debugs, and operates **UiPath Maestro** projects — BPMN 2.0 business-process orchestrations with long-running, human-in-the-loop semantics. Maestro is the sibling of Flow ([`uip flow`](./uip-flow.md)) in the UiPath orchestration surface; pick Maestro when you need standard BPMN semantics (user tasks, boundary events, timers, sub-processes), pick Flow when you need a node-and-edge graph of agentic or connector-heavy steps.

`uip maestro` authors, packs, debugs, and operates **UiPath Maestro** projects — BPMN 2.0 business-process orchestrations with long-running, human-in-the-loop semantics. Maestro is the sibling of Flow ([`uip flow`](./uip-flow.md)) in the UiPath orchestration surface; pick Maestro when you need standard BPMN semantics (user tasks, boundary events, timers, sub-processes), pick Flow when you need a node-and-edge graph of agentic or connector-heavy steps.

The tool is shipped as the `@uipath/maestro-tool` plugin. Maestro commands are registered under `uip maestro` (or, for BPMN-specific subsurfaces, `uip maestro bpmn`). See [Tools (plugins)](./concepts-tools.md) for the plugin model.

## Authoring flow

A Maestro project is a directory with a `project.uiproj`, a `.bpmn` file, and supporting metadata files (`operate.json`, `entry-points.json`, `bindings_v2.json`, `package-descriptor.json`).

```bash
# 1. Scaffold
uip maestro init invoice-orchestration

# 2. Edit the .bpmn in Studio Web or your IDE
#    (BPMN is validated at init time via bpmn-moddle)

# 3. Smoke-test via Studio Web
uip maestro debug ./invoice-orchestration

# 4. Pack for deployment
uip maestro pack ./invoice-orchestration ./dist --version 1.0.0
```

### Authoring commands

| Command | Purpose |
|---|---|
| [`uip maestro init`](./uip-maestro-init.md) | Scaffold a new Maestro project (BPMN starter) |
| [`uip maestro debug`](./uip-maestro-debug.md) | Upload to Studio Web and run a debug session |
| [`uip maestro pack`](./uip-maestro-pack.md) | Produce a deployable `.nupkg` |

## Runtime

At runtime a published Maestro package becomes a **process** of type `ProcessOrchestration` on Orchestrator. Starting one creates an **instance**; each execution attempt is a **job**; failures surface as **incidents**.

| Command | Purpose |
|---|---|
| [`uip maestro process`](./uip-maestro-process.md) | List and run deployed Maestro processes (`list`, `get`, `run`) |
| [`uip maestro processes`](./uip-maestro-process.md) | Process summaries across folders, and per-process incidents |
| [`uip maestro instances`](./uip-maestro-instances.md) | Inspect and steer running instances (`list`, `get`, `pause`, `resume`, `cancel`, `retry`, `migrate`, `goto`, `variables`, …) |
| [`uip maestro incidents`](./uip-maestro-incidents.md) | Read incident summaries and details |
| [`uip maestro job`](./uip-maestro-job.md) | Stream traces (`traces`) and inspect job status |

Orchestrator-level jobs and processes are manipulated through the Orchestrator tool — see [Orchestrator jobs](./uip-orchestrator-jobs.md) and [Orchestrator processes](./uip-orchestrator-processes.md).

### Registry (BPMN)

Maestro also ships a BPMN registry — **`uip maestro bpmn registry`** — for browsing the extension types, connectors, and processes usable inside a `.bpmn`. It is not yet in the sidebar but is callable today:

```
uip maestro bpmn registry pull   [-f, --force]
uip maestro bpmn registry list   [-l, --limit <n>]
uip maestro bpmn registry search <keyword>
uip maestro bpmn registry get    <extensionType> [--connection-id <id>] [--object-name <name>]
```

Data shapes: `RegistryPullSuccess` (counts: `ExtensionTypeCount`, `ConnectorCount`, `ProcessCount`), `RegistryListSuccess` / `RegistrySearchSuccess` (`Data.ExtensionTypes[]`, `Data.Connectors[]`, `Data.Processes[]`), `RegistryGetSuccess` (`Data.ExtensionType`, optional `Data.ISEnrichment` when both `--connection-id` and `--object-name` are provided).

## Conventions

- Every `uip maestro` subcommand honors the [global options](./global-options.md) (`--output`, `--output-filter`, `--log-level`, `--log-file`).
- Default output is **JSON**.
- Exit codes follow the [standard contract](./exit-codes.md).
- Most runtime commands require `uip login` first — see [Authentication](./authentication.md).

## See also

- [`uip flow`](./uip-flow.md) — graph-shaped workflow sibling
- [Tools (plugins)](./concepts-tools.md)
- [Authentication](./authentication.md)
- [Global options](./global-options.md), [Exit codes](./exit-codes.md)