# uip flow

> `uip 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.

`uip 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 the `@uipath/flow-tool` plugin (command prefix `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 flow init invoice-flow

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

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

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

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

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

### Authoring commands

| Command | Purpose |
|---|---|
| [`uip flow init`](./uip-flow-init.md) | Scaffold a new Flow project |
| [`uip flow node`](./uip-flow-node-edge.md) | Add, configure, list, and delete nodes in a `.flow` file |
| [`uip flow edge`](./uip-flow-node-edge.md) | Add, list, and delete edges between nodes |
| [`uip flow validate`](./uip-flow-validate.md) | Validate a `.flow` file against the schema (and governance policy) |
| [`uip flow debug`](./uip-flow-debug.md) | Upload the project to Studio Web and run a debug session |
| [`uip flow pack`](./uip-flow-pack.md) | Produce a deployable `.nupkg` |
| [`uip flow registry`](./uip-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 flow variable`** — add / list / delete top-level workflow variables (`in`, `out`, `inout`). See [node-edge.md](./uip-flow-node-edge.md#variables-and-variable-updates).
- **`uip flow variable-update`** — attach a JS assignment expression to a node (`=js:ctx.output`) that runs on completion.
- **`uip flow binding`** — add / list / delete resource bindings (process, agent, connection, etc.) that are resolved at publish time.
- **`uip flow tidy`** — 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 flow process`](./uip-flow-process.md) | List and run deployed Flow processes (`list`, `get`, `run`) |
| [`uip flow processes`](./uip-flow-process.md) | Process summaries across folders, and per-process incidents |
| [`uip flow instances`](./uip-flow-instances.md) | Inspect and steer running instances (`list`, `get`, `pause`, `resume`, `cancel`, `retry`, `migrate`, `goto`, `variables`, …) |
| [`uip flow incidents`](./uip-flow-incidents.md) | Read incident summaries and details |
| [`uip flow job`](./uip-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 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)