# uip maestro flow hitl and uip maestro flow migrate

> Syntax and options for `uip maestro flow hitl` (add a Human-in-the-Loop node) and `uip maestro flow migrate` (upgrade a `.flow` file to the current schema).

This page covers two small, unrelated command groups that both edit a `.flow` file directly:

- **`uip maestro flow hitl`** — add a Human-in-the-Loop (HITL) node, which pauses execution and waits for a person to complete a task in Action Center.
- **`uip maestro flow migrate`** — upgrade a `.flow` file's workflow and node schema versions.

## Synopsis

```
uip maestro flow hitl add <file> [--schema <json>] [--priority <Low|Medium|High>] [--position <x,y>] [--label <label>] [--assignee <email-or-group>]

uip maestro flow migrate <file> [--dry-run] [--no-include-optional]
```

Honors [global options](./global-options.md). Exit codes follow the [standard contract](./exit-codes.md). Neither command requires `uip login`.

## uip maestro flow hitl add

Add a HITL node to a `.flow` file.

### Arguments

- `<file>` *(required)* — path to the `.flow` file.

### Options

| Option | Description |
|---|---|
| `--schema <json>` | Task schema JSON object. `inputs[]` entries pre-fill from flow variables (add `"binding":"varName"`); `outputs[]` entries write back to a flow variable (add `"variable":"varName"`); `outcomes[]` lists the possible decisions (e.g. Approve/Reject). |
| `--priority <level>` | `Low`, `Medium`, or `High`. Default `Low`. |
| `--position <x,y>` | Canvas position, e.g. `250,300`. |
| `--label <label>` | Display label for the node. |
| `--assignee <email-or-group>` | Assignment target: a user email or a group name. |

### Examples

```bash
# Bare HITL node, no schema
uip maestro flow hitl add workflow.flow

# With label, priority, and a group assignee
uip maestro flow hitl add workflow.flow --label "Invoice Review" --priority High --assignee finance-approvers

# Full schema: pre-filled input, a required output written back to a variable, two outcomes
uip maestro flow hitl add workflow.flow --label "Approval" \
  --schema '{"inputs":[{"name":"invoiceId","binding":"fetchInvoice1.result.invoiceId"}],"outputs":[{"name":"decision","variable":"approvalDecision","required":true}],"outcomes":[{"name":"Approve"},{"name":"Reject"}]}'
```

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

```json
{
  "Code": "HitlNodeAdded",
  "Data": {
    "NodeId": "approval1",
    "NodeType": "uipath.human-in-the-loop",
    "Label": "Approval",
    "DefinitionAdded": true
  }
}
```

## uip maestro flow migrate

Upgrade a `.flow` file's workflow schema version and, optionally, its node `typeVersion`s, to current. Idempotent — running it against an already-current file reports no changes.

### Arguments

- `<file>` *(required)* — path to the `.flow` file.

### Options

| Option | Description |
|---|---|
| `--dry-run` | Show what would change without writing the file. |
| `--no-include-optional` | Skip optional node migrations (for example `typeVersion` normalization). Default: optional migrations are applied. |

### Examples

```bash
# Migrate to the current schema version
uip maestro flow migrate ./my-flow/my-flow.flow

# Preview only
uip maestro flow migrate ./my-flow/my-flow.flow --dry-run

# Skip optional node migrations
uip maestro flow migrate ./my-flow/my-flow.flow --no-include-optional
```

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

```json
{
  "Code": "FlowMigrate",
  "Data": {
    "File": "./my-flow/my-flow.flow",
    "Migrated": true,
    "DryRun": false,
    "FromVersion": "1.0.0",
    "ToVersion": "1.0",
    "WorkflowSteps": ["1.0.0 -> 1.0"],
    "NodeMigrations": {
      "ForcedAvailable": 0,
      "OptionalAvailable": 2,
      "OptionalApplied": 2,
      "Failed": 0
    }
  }
}
```

`Migrated` is `false` and `WorkflowSteps` is empty when the file is already at the current version. With `--dry-run`, `Data.DryRun` is `true` and the file is left untouched.

## See also

- [`uip maestro flow validate`](./uip-maestro-flow-validate.md) — validate after migrating
- [`uip maestro flow node`](./uip-maestro-flow-node-edge.md), [`uip maestro flow variable`](./uip-maestro-flow-node-edge.md#variables)
- [Flow overview](./uip-maestro-flow.md)
- [Global options](./global-options.md), [Exit codes](./exit-codes.md)