Skip to main content
The pflow registry command group manages the node registry - a catalog of all nodes available for building workflows. This includes core nodes, MCP tools, and custom user nodes.
Agent commands. These commands are primarily used by your AI agent to discover and test nodes when building workflows. The scan command is the exception - you run that to add custom nodes.

​
Commands

CommandDescription
listList all registered nodes
describeShow detailed node information
discoverFind nodes using natural language
scanAdd custom nodes from a directory
runRun a single node for testing

​
pflow registry list

List all registered nodes, optionally filtered by pattern. 
pflow registry list [FILTER_PATTERN] [--json]
Arguments:
  • FILTER_PATTERN - Optional keywords to filter (space-separated, AND logic)
Options:
  • --json - Output as JSON
Examples: 
# List all nodes grouped by package
pflow registry list

# Filter by keyword
pflow registry list github

# Filter by multiple keywords (AND logic)
pflow registry list "github api"

# JSON output
pflow registry list --json
Output: Nodes are grouped by package (core, MCP, user): 
Core nodes:

  file (5 nodes):
    - read-file: Read file contents
    - write-file: Write content to file
    - copy-file: Copy a file
    - move-file: Move or rename a file
    - delete-file: Delete a file

  llm (1 node):
    - llm: Send prompts to LLM

MCP tools:

  github (15 tools):
    - mcp-github-create-issue: Create a new GitHub issue
    - mcp-github-list-issues: List issues from a repository
    ...

​
pflow registry describe

Show detailed information about one or more nodes including parameters, inputs, and outputs. 
pflow registry describe <NODE>...
Arguments:
  • NODE - One or more node names/IDs to describe (required)
Examples: 
# Single node
pflow registry describe llm

# Multiple nodes at once
pflow registry describe read-file write-file llm

# MCP tool (multiple name formats work)
pflow registry describe mcp-github-create-issue
pflow registry describe github-create-issue
pflow registry describe create-issue
Output: 
Node: llm
Type: core

Description: Send prompts to an LLM and get responses

Parameters:
  - prompt (string, required): The prompt to send
  - system (string): System prompt for context
  - model (string): Model to use (default: auto-detect)
  - temperature (float): Response randomness (0-1)

Inputs:
  - context (string): Optional context from shared store

Outputs:
  - response (string): LLM response text

Example usage:
  pflow registry run llm prompt="Hello world"
For MCP tools, pflow handles name variations automatically. create-issue, github-create-issue, and mcp-github-create-issue all resolve to the same tool (if unique).

​
pflow registry discover

Use AI to find nodes relevant to a natural language task description. 
pflow registry discover "<QUERY>"
Arguments:
  • QUERY - Natural language description of what you need (max 500 characters)
Example: 
pflow registry discover "I need to read files and call APIs"
Output: Returns formatted markdown with relevant node specifications: 
Based on your task, these nodes are relevant:

read-file
  Read file contents from the filesystem
  Parameters: file_path (required), encoding

http
  Make HTTP requests to APIs
  Parameters: url (required), method, headers, body

Use 'pflow registry describe <node>' for full details.
Requires an API key to be configured. See Quickstart for setup.

​
pflow registry scan

Scan a directory for custom user nodes and add them to the registry. 
pflow registry scan [PATH] [--force] [--json]
Arguments:
  • PATH - Directory to scan (default: ~/.pflow/nodes/)
Options:
  • --force, -f - Skip confirmation prompt
  • --json - Output as JSON
Example: 
# Scan default location
pflow registry scan

# Scan custom directory
pflow registry scan ./my-nodes/

# Skip confirmation
pflow registry scan --force
Output: 
Found 3 Python files to scan...

Valid nodes:
  ✓ my-custom-node: Custom processing logic
  ✓ data-transformer: Transform data formats

Invalid (skipped):
  ⚠ broken-node.py: Missing exec() method

Add 2 nodes to registry? [y/N]: y

✓ Added 2 nodes to registry
Custom nodes run with your user privileges. Only add nodes from sources you trust.

​
pflow registry run

Run a single node independently for testing. 
pflow registry run <NODE> [PARAMS...] [OPTIONS]
Arguments:
  • NODE - Node name/ID to run (required)
  • PARAMS - Parameter key=value pairs
Options:
  • --output-format json - Raw JSON output, bypasses structure mode
  • --timeout INT - Execution timeout in seconds (default: 60)
  • -v, --verbose - Show detailed execution information
Examples: 
# Test file reading
pflow registry run read-file file_path=/tmp/test.txt

# Test LLM node
pflow registry run llm prompt="Hello world"

# Test with JSON output
pflow registry run read-file file_path=/tmp/test.txt --output-format json

# Test MCP tool
pflow registry run mcp-github-list-issues repo=owner/repo state=open

# With timeout
pflow registry run http url="https://api.example.com" --timeout 30
Parameter type inference: 
count=10              # integer
rate=0.5              # float
enabled=true          # boolean
tags='["a","b"]'      # JSON array
config='{"key":"val"}'# JSON object
name=example          # string

​
Output modes

The output display is controlled by the registry.output_mode setting. There are three modes:
ModeDescriptionWhen to use
smart (default)Shows template paths with values. Filters large outputs (>30 fields) using LLM.General debugging and AI agent workflows
structureShows template paths only, no values. No filtering - fast, no LLM overhead.Sensitive data, quick exploration
fullShows all fields with full values, no truncation or filteringManual inspection only (not recommended for agents)
Change the mode with: 
pflow settings registry output-mode smart     # Default
pflow settings registry output-mode structure # Paths only
pflow settings registry output-mode full      # Everything
Smart mode (default): Shows template paths with actual values. Large values are truncated to keep output readable. For outputs with more than 30 fields, uses an LLM to intelligently filter to the most relevant fields: 
✓ Node executed successfully

Execution ID: exec-1234567890-abc123

Output:
  ✓ ${content} (str) = "Hello world..."
  ✓ ${metadata.size} (int) = 123
  ✓ ${metadata.created} (str) = "2024-01-15"

Execution time: 45ms
Truncation rules:
  • Strings over 200 characters show "first 197 chars..." (truncated)
  • Dicts with more than 5 keys show {...N keys}
  • Lists with more than 5 items show [...N items]
When values are truncated, use pflow read-fields <execution-id> <path> to retrieve the full value. Structure mode: Shows only template paths without values - useful when outputs contain sensitive data or when you want fast output without LLM overhead. Unlike smart mode, structure mode shows all fields without filtering: 
✓ Node executed successfully

Execution ID: exec-1234567890-abc123

Available template paths:
  ✓ ${content} (str)
  ✓ ${metadata.size} (int)
  ✓ ${metadata.created} (str)

Use these paths in workflow templates.

Execution time: 45ms

​
Raw JSON output

Use --output-format json to bypass structure mode and get raw, machine-parseable output: 
pflow registry run read-file file_path=/tmp/test.txt --output-format json

{
  "success": true,
  "node_type": "read-file",
  "outputs": {
    "content": "Hello world...",
    "metadata": {"size": 123}
  },
  "execution_time_ms": 45
}
Agents use registry run to test node parameters before building workflows. The execution ID lets you retrieve full values later with pflow read-fields.
Agents use structure mode for template path discovery — they see types and paths, not your actual data. Data only flows at runtime, when the agent isn’t involved. The --output-format json flag is for debugging and scripting when you need raw output values.

​
Retrieving full values

When output is truncated in smart mode, use pflow read-fields to retrieve complete values: 
pflow read-fields <EXECUTION_ID> <FIELD_PATHS...>
Examples: 
# Single field
pflow read-fields exec-1234567890-abc123 content

# Multiple fields
pflow read-fields exec-1234567890-abc123 result.title result.body

# Array access
pflow read-fields exec-1234567890-abc123 items[0].name items[0].id

# JSON output
pflow read-fields exec-1234567890-abc123 result --output-format json
Execution results are cached in ~/.pflow/cache/registry-run/ and available for retrieval until manually cleared.

​
Node types

TypeDescriptionExample
CoreBuilt-in pflow nodesread-file, llm, http
MCPTools from MCP serversmcp-github-create-issue
UserCustom user-defined nodesScanned from ~/.pflow/nodes/

​
MCP tool naming

MCP tools follow the pattern mcp-{server}-{tool}. Multiple name formats work:
FormatExample
Fullmcp-github-create-issue
Server-qualifiedgithub-create-issue
Short (if unique)create-issue
pflow automatically resolves the shortest unambiguous name.

​
File locations

PathPurpose
~/.pflow/registry.jsonRegistry data
~/.pflow/nodes/Default custom node location