@uipath/flow-tool

CLI tool for managing UiPath Flow processes and jobs. This is a uip plugin that provides Flow-related commands.

Commands

flow init

Create a new Flow project with boilerplate files.

uip flow init <projectName> [--force]

flow validate

Validate a .flow file against the Flow schema (Zod-based) with structural cross-field checks.

uip flow validate <flowFile>

flow pack

Pack a Flow project into a NuGet package (.nupkg).

uip flow pack <projectPath> <outputPath> [-n <name>] [-v <version>]

Known Issues

Solution integration with Flow projects is currently broken.

The flow init, flow validate, and flow pack commands work correctly on their own. However, when a Flow project is added to a solution via uip solution project add and then packed with uip solution pack, the resulting .nupkg inside the solution zip is missing critical files (.bpmn, .flow, entry-points.json, bindings_v2.json).

Root cause: The published @uipath/tool-flow npm package has a non-recursive copyFiles() method that only copies top-level files from the project directory, silently skipping the content/ and flow_files/ subdirectories. The local flow-pack-service.ts correctly uses copyDirectory() for recursive copies, but the npm-published tool does not.

Workaround: Use uip flow pack directly to produce a correct .nupkg for deployment.

Flow Process Commands

flow process list

List available Flow processes.

uip flow process list

flow process get

Get Flow process schema and details.

uip flow process get "<process-key>" "<feed-id>"

# Example
uip flow process get "MyFlow.flow.Flow:1.0.0" "6d98ceb8-becb-46ec-80d7-df213fbec06c"

flow process run

Run a Flow process.

Syntax:

uip flow process run "<process-key>" "<folder-key>" [options]

Arguments:

• <process-key> - Process package key with version (e.g., MyFlow.flow.Flow:1.0.0)
• <folder-key> - Folder key (GUID)

Options:

• -i, --inputs <json> - Input parameters as JSON string or @file.json
• -t, --tenant <name> - Tenant name (defaults to authenticated tenant)
• --release-key <key> - Release key (GUID, from list command)
• --folder-id <id> - Folder ID (from list command)
• --feed-id <id> - Feed ID for package lookup (optional)
• --robot-ids <ids> - Comma-separated robot IDs (optional)
• --validate - Validate inputs against project schema before running

Examples:

# Run with JSON inputs
uip flow process run "TestFlow.flow.Flow:1.0.0" "folder-guid-here" \
  --release-key "release-guid" \
  --folder-id "2553016" \
  --inputs '{"name": "John", "age": 30}'

# Run with inputs from file
uip flow process run "TestFlow.flow.Flow:1.0.0" "folder-guid-here" \
  --release-key "release-guid" \
  --folder-id "2553016" \
  --inputs @inputs.json

# Run with piped inputs
echo '{"name": "John", "age": 30}' | \
  uip flow process run "TestFlow.flow.Flow:1.0.0" "folder-guid-here" \
  --release-key "release-guid" \
  --folder-id "2553016"

Flow Job Commands

flow job traces

Stream execution traces for a running job.

uip flow job traces "<job-key>" [options]

# Options:
# --poll-interval <ms>  - Polling interval in milliseconds (default: 2000)
# --traces-service <name> - Traces service name (default: llmopstenant_)

# Example
uip flow job traces "06478292-f9cf-4234-9d1b-03f4bcd95fed"

flow job status

Get detailed status of a Flow job.

uip flow job status "<job-key>" --folder-id "<id>" [options]

# Options:
# --detailed  - Show full response with all fields

# Example
uip flow job status "06478292-f9cf-4234-9d1b-03f4bcd95fed" --folder-id "2553016"

Complete Workflow

# 1. List available processes
uip flow process list

# 2. Get process schema (to see required inputs)
uip flow process get "MyFlow.flow.Flow:1.0.0" "feed-id-from-list"

# 3. Run the process
JOB_KEY=$(uip flow process run "MyFlow.flow.Flow:1.0.0" "folder-key" \
  --release-key "release-key" \
  --folder-id "2553016" \
  --inputs '{}' 2>/dev/null)

# 4. Watch execution traces
uip flow job traces "$JOB_KEY"

# 5. Check final status
uip flow job status "$JOB_KEY" --folder-id "2553016"

Output

Process list: JSON array with process metadata Process get: JSON with entry points and schemas Process run: Job key on stdout, next steps on stderr Job traces: JSON trace events (one per line) on stdout Job status: JSON with job details (14 fields default, full with --detailed)

Exit codes:

• 0 - Success
• 1 - Failure or error

Flow Registry Commands

flow registry commands let you browse, search, and inspect the Flow node registry — the building blocks used inside UiPath Flow processes. Nodes include OOTB activities (uipath.agent, uipath.http, etc.) and connector nodes that call third-party APIs (Slack, Salesforce, etc.). When logged in, the registry also includes connector nodes installed in your tenant.

| Command | Description | | --------------------------------- | ------------------------------------------------------------------------------ | | flow registry pull | Fetch and cache all available nodes from the Flow registry | | flow registry list | List all locally cached nodes | | flow registry search [keyword] | Find nodes by keyword and/or structured filters | | flow registry get <nodeType> | Get full node schema; auto-enriches connector nodes with input/output fields |

flow registry pull

Fetches the node registry and writes it to local cache. Subsequent commands (list, search, get) read from this cache.

uip flow registry pull
uip flow registry pull --force   # bypass 30-minute cache, always refresh

Output fields:

| Field | Description | | ------------- | ------------------------------------------------------- | | NodesCount | Number of nodes cached | | FromCache | true if the cached copy was used without fetching | | AgeMinutes | Cache age in minutes (only when FromCache: true) | | Source | "ootb" (unauthenticated) or "authenticated" (tenant-specific) | | CacheWritten | true if cache was updated on this run | | Message | Human-readable status |

Cache behaviour:

• Cache expires after 30 minutes. Expired or missing cache triggers a live fetch.
• When not logged in, OOTB nodes are returned without updating the cache.
• On authenticated fetch failure, falls back to OOTB nodes without updating the cache.

flow registry list

Lists all nodes in the local cache. If no cache exists, fetches live data first.

uip flow registry list

Output fields: NodesCount, Nodes[]

flow registry search

Searches for nodes by keyword and/or structured filters.

uip flow registry search slack
uip flow registry search slack --filter "displayname:contains=send message"
uip flow registry search --filter "category=connector"

Options:

| Option | Description | | ----------------- | -------------------------------------------------------------- | | [keyword] | Searches across nodeType, category, tags, display.label | | --filter <expr> | Structured filter (see filter syntax below) |

At least one of keyword or --filter is required.

Output fields: Keyword, Filters, ResultCount, Nodes[]

Filter syntax:

field=value                           # equality
field:operator=value                  # operator variant
field1=value1,field2=value2           # AND conditions

| Field aliases | Operators | | ------------------------------------------------ | --------------------------------------------------------------- | | category, cat | equals (default), contains, startsWith, endsWith, in | | type, nodetype | | | tags, tag | | | displayname, display_name, name, label | |

Examples:

# Connector nodes only
--filter "category=connector"

# Display name contains "slack"
--filter "displayname:contains=slack"

# Tagged with "ai" or "automation"
--filter "tags:in=ai,automation"

# Combined: connector AND display name contains "invite"
--filter "category=connector,displayname:contains=invite"

flow registry get

Returns full details for a single node, looked up by nodeType (case-insensitive).

uip flow registry get "uipath.agent"
uip flow registry get "uipath.connector.slack.send-message"

Output fields: Node (enriched FlowNode object)

Connector enrichment:

For nodes tagged "connector", registry get automatically calls the Integration Service API to fetch input and output field definitions and attach them to the result:

• inputDefinition.fields[] — fields for the request body
• outputDefinition.fields[] — fields returned by the action

Each field contains:

| Property | Description | | ------------- | ------------------------------------------------------------------------ | | name | JSON key for the request/response | | displayName | Human-readable label | | type | Data type (string, boolean, integer, etc.) | | required | true if mandatory (input fields only) | | description | What the field does | | enum | Allowed values (if restricted) | | reference | Object reference metadata — field expects an ID, not a plain name | | responseOnly | true on all output fields |

Enrichment requires login. If the IS call fails or the node is not a connector, the node is returned unchanged.

JMESPath output filtering

All commands support --output-filter <expression> (global option) to extract specific values from the output. The expression is a JMESPath query evaluated against the Data field of the JSON response, so top-level keys are the output fields listed above.

# List all nodeTypes from a search
uip flow registry search slack --output-filter "Nodes[*].nodeType"

# Get the full enriched node
uip flow registry get "uipath.connector.slack.send-message" \
  --output-filter "Node"

# Extract only the input fields
uip flow registry get "uipath.connector.slack.send-message" \
  --output-filter "Node.inputDefinition.fields"

# Get the node count after a pull
uip flow registry pull --output-filter "NodesCount"

Combine with --format json to get clean JSON output:

uip flow registry get "uipath.connector.slack.send-message" \
  --output-filter "Node.inputDefinition.fields" --format json

Registry command workflow

# 1. Pull the registry (once per session)
uip flow registry pull

# 2. Search for candidates
uip flow registry search slack --filter "displayname:contains=send" \
  --output-filter "Nodes[*].nodeType"
# → uipath.connector.slack.send-message
#   uipath.agent.resource.tool.connector.slack.send-message
# Pick the uipath.connector.* variant for direct flow use.

# 3. Inspect the full schema (with IS enrichment if logged in)
uip flow registry get "uipath.connector.slack.send-message" --format json

# 4. Extract just the input fields to build a request body
uip flow registry get "uipath.connector.slack.send-message" \
  --output-filter "Node.inputDefinition.fields" --format json

Development

# Build
bun run build

# Test
bun test

# Lint
bun run lint