# uip maestro flow

> Commands for authoring, packing, debugging, and operating UiPath Flow graph-shaped workflow projects using the `uip maestro flow` tool.

`uip maestro flow` authors, packs, debugs, and operates **UiPath Flow** projects — graph-shaped workflows made of **nodes** (activities, triggers, connectors) connected by **edges**. Flow is one of two orchestration surfaces in UiPath; see [`uip maestro`](./uip-maestro.md) for BPMN-based business-process orchestration, its sibling.

The tool is shipped as part of the `@uipath/maestro-tool` plugin (command prefix `maestro flow`). See [Tools (plugins)](./concepts-tools.md) for how plugins are installed and versioned.

## When to use Flow vs Maestro

| Surface | Graph shape | Asset file | Primary use case |
|---|---|---|---|
| **Flow** | Visual node-and-edge graph | `.flow` (JSON) | Agentic workflows, connector automations, AI node chaining |
| **Maestro** | BPMN 2.0 diagram | `.bpmn` | Long-running, human-in-the-loop, business process orchestration |

Both tools publish `.nupkg` packages to Orchestrator and share the runtime primitives (`processes`, `instance`, `incident`, `job`, `registry`).

## Authoring flow

A Flow project is a directory with a `project.uiproj` manifest and one or more `.flow` files (plus supporting files generated at pack time).

```bash
# 1. Scaffold a new project
uip maestro flow init invoice-flow

# 2. Discover nodes in the registry
uip maestro flow registry pull
uip maestro flow registry search slack

# 3. Edit the .flow file — add nodes, edges, variables, bindings
uip maestro flow node add invoice-flow/invoice-flow.flow uipath.connector.slack.send-message --label "Notify"
uip maestro flow edge add invoice-flow/invoice-flow.flow start node_a1b2c3d4
uip maestro flow node configure invoice-flow/invoice-flow.flow node_a1b2c3d4 --detail '{"connectionId":"…","folderKey":"…","method":"POST","endpoint":"/…"}'

# 4. Validate structure (and optionally governance policy)
uip maestro flow validate invoice-flow/invoice-flow.flow

# 5. Run against Studio Web to smoke-test
uip maestro flow debug ./invoice-flow

# 6. Pack for deployment
uip maestro flow pack ./invoice-flow ./dist --version 1.0.0
```

### Authoring commands

| Command | Purpose |
|---|---|
| [`uip maestro flow init`](./uip-maestro-flow-init.md) | Scaffold a new Flow project |
| [`uip maestro flow node`](./uip-maestro-flow-node-edge.md) | Add, configure, list, and remove nodes in a `.flow` file |
| [`uip maestro flow edge`](./uip-maestro-flow-node-edge.md) | Add, list, and remove edges between nodes |
| [`uip maestro flow validate`](./uip-maestro-flow-validate.md) | Validate a `.flow` file against the schema (and governance policy) |
| [`uip maestro flow debug`](./uip-maestro-flow-debug.md) | Upload the project to Studio Web and run a debug session |
| [`uip maestro flow pack`](./uip-maestro-flow-pack.md) | Produce a deployable `.nupkg` |
| [`uip maestro flow registry`](./uip-maestro-flow-registry.md) | Browse and search available node types (OOTB + connector) |

### Variable, binding, and layout helpers

These CLI surfaces are not on the sidebar yet but are callable today — they are thin wrappers for editing the `.flow` JSON programmatically:

- **`uip maestro flow variable`** — add / list / remove top-level workflow variables (`in`, `out`, `inout`). See [node-edge.md](./uip-maestro-flow-node-edge.md#variables-and-variable-updates).
- **`uip maestro flow variable-update`** — attach a JS assignment expression to a node (`=js:ctx.output`) that runs on completion.
- **`uip maestro flow binding`** — add / list / remove resource bindings (process, agent, connection, etc.) that are resolved at publish time.
- **`uip maestro flow format`** — auto-layout: reposition nodes to remove overlaps.

## Runtime

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

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

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

## Conventions

- Every `uip maestro flow` 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 maestro`](./uip-maestro.md) — BPMN sibling for business-process orchestration
- [Tools (plugins)](./concepts-tools.md)
- [Authentication](./authentication.md)
- [Global options](./global-options.md), [Exit codes](./exit-codes.md)