@uipath/flow-tool

@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 maestro flow init <projectName> [--force]

flow validate

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

uip maestro flow validate <flowFile>

flow pack

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

uip maestro flow pack <project-path> <output-path> [-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 projects 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 maestro flow pack directly to produce a correct .nupkg for deployment.

Flow Process Commands

flow process list

List available Flow processes in a folder. Provide either --folder-key (GUID) or --folder-path (e.g. Shared/Invoices).

uip maestro flow process list --folder-key "<folder-key>"
uip maestro flow process list --folder-path "Shared/Invoices"

flow process get

Get Flow process schema and details.

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

# Example
uip maestro flow process get "MyFlow.flow.Flow:1.0.0" "6d98ceb8-becb-46ec-80d7-df213fbec06c" --folder-key "c3d4e5f6-0000-0000-0000-000000000001"

flow process run

Run a Flow process.

Syntax:

uip maestro 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)
• --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 maestro flow process run "TestFlow.flow.Flow:1.0.0" "folder-guid-here" \
  --release-key "release-guid" \
  --inputs '{"name": "John", "age": 30}'

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

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

Flow Job Commands

flow job traces

Stream execution traces for a running job.

uip maestro 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 maestro flow job traces "06478292-f9cf-4234-9d1b-03f4bcd95fed"

flow job status

Get detailed status of a Flow job.

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

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

# Example
uip maestro flow job status "06478292-f9cf-4234-9d1b-03f4bcd95fed" --folder-key "c3d4e5f6-0000-0000-0000-000000000001"

Complete Workflow

# 1. List available processes
uip maestro flow process list --folder-key "folder-key"

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

# 3. Run the process
JOB_KEY=$(uip maestro flow process run "MyFlow.flow.Flow:1.0.0" "folder-key" \
  --release-key "release-key" \
  --inputs '{}')

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

# 5. Check final status
uip maestro flow job status "$JOB_KEY" --folder-key "folder-key"

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 <node-type>	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 maestro flow registry pull
uip maestro 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 maestro flow registry list

Output fields: NodesCount, Nodes[]

flow registry search

Searches for nodes by keyword and/or structured filters.

uip maestro flow registry search slack
uip maestro flow registry search slack --filter "displayname:contains=send message"
uip maestro 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 maestro flow registry get "uipath.agent"
uip maestro 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 maestro flow registry search slack --output-filter "Nodes[*].nodeType"

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

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

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

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

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

Registry command workflow

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

# 2. Search for candidates
uip maestro 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 maestro flow registry get "uipath.connector.slack.send-message" --output json

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

Development

# Build
bun run build

# Test
bun test

# Lint
bun run lint