CLI overview

pflow provides a CLI for running workflows, managing MCP servers, and configuring settings.

Who runs these commands? Most pflow commands are run by your AI agent, not by you directly. You handle setup (installation, API keys, MCP servers), then your agent uses pflow to build and run workflows. This reference documents all commands so you understand what your agent is doing. See Using pflow for what to expect day-to-day.

Command structure

pflow [command] [options] [arguments]

Command groups

pflow (default)

Run workflows by name or file

pflow workflow

List, describe, discover, and save workflows

pflow skill

Publish workflows as AI agent skills

pflow registry

Browse and test available nodes

pflow mcp

Manage MCP server connections

pflow settings

Configure API keys and node filtering

pflow instructions

Get AI agent usage guidance

Main command

The default pflow command runs workflows. Your agent uses this to run saved workflows or workflow files it has created.

Run a saved workflow

pflow my-workflow input=data.txt threshold=0.5

Run from a file

pflow ./workflow.pflow.md
pflow ~/workflows/analysis.pflow.md param=value

Natural language mode (experimental)

pflow can generate workflows from natural language, but this feature is experimental. For production use, let your AI agent build workflows directly.

pflow "read data.txt and summarize the content"

Natural language requests must be quoted. The planner generates a workflow, which you can save for reuse. Requires an LLM to be configured.

Global options

Option	Description
`--version`	Show pflow version
`-v, --verbose`	Show detailed execution output
`-o, --output-key KEY`	Specific shared store key to output
`--output-format text\|json`	Output format (default: text)
`-p, --print`	Force non-interactive output
`--no-trace`	Disable workflow trace saving
`--validate-only`	Validate workflow without running
`--help`	Show help message

Planner options (experimental)

These options apply when using natural language mode to generate workflows:

Option	Description
`--trace-planner`	Save planner execution trace
`--auto-repair`	Enable automatic workflow repair on failure
`--planner-timeout INT`	Timeout for planner in seconds (default: 60)
`--save / --no-save`	Save generated workflow (default: save)
`--cache-planner`	Enable cross-session LLM caching to reduce costs
`--planner-model TEXT`	LLM model for planning (default: auto-detect)
`--no-update`	Save repairs to separate file instead of updating original

This is not the recommended way to use pflow. It may be deprecated in favor of using pflow through AI agents via the CLI or MCP server.

Parameter syntax

Pass parameters to workflows using key=value syntax:

pflow my-workflow input=data.txt count=10 enabled=true

Type inference:

true / false → boolean
10 → integer
3.14 → float
'["a","b"]' → JSON array
'{"key":"val"}' → JSON object
Everything else → string

Stdin input

Pipe data into workflows that declare an input with stdin: true:

echo "test content" | pflow my-workflow
cat data.csv | pflow csv-analyzer

The workflow must have an input marked to receive stdin:

## Inputs

### data

Data input from stdin pipe.

- type: string
- required: true
- stdin: true

Piped data routes to this input automatically. CLI parameters override stdin if both are provided:

# CLI parameter wins - "override" is used, not piped content
echo "piped" | pflow my-workflow data="override"

For workflow chaining, use the -p flag to output results for the next workflow:

pflow -p step1 | pflow -p step2 | pflow step3

Output modes

Text mode (default)

Human-readable output with progress indicators in interactive terminals:

pflow my-workflow

JSON mode

Structured output for parsing:

pflow --output-format json my-workflow | jq '.result'

Show JSON output structure

Success response:

{
  "success": true,
  "result": {
    "summary": "Analysis complete",
    "count": 42
  },
  "duration_ms": 456.78,
  "total_cost_usd": 0.02,
  "nodes_executed": 3,
  "execution": {
    "duration_ms": 456.78,
    "nodes_executed": 3,
    "nodes_total": 3,
    "steps": [
      {
        "node_id": "read-data",
        "status": "completed",
        "duration_ms": 50.12,
        "cached": false
      }
    ]
  },
  "metrics": {
    "workflow": {
      "duration_ms": 456.78,
      "nodes_executed": 3,
      "nodes_cached": 0
    },
    "total": {
      "duration_ms": 456.78,
      "total_cost_usd": 0.02,
      "total_tokens": 1500,
      "llm_calls": 1
    }
  }
}

Error response:

{
  "success": false,
  "error": "Workflow failed with action: error",
  "errors": [
    {
      "source": "runtime",
      "category": "api_validation",
      "message": "Missing required parameter: 'repo'",
      "node_id": "fetch-issues",
      "fixable": true,
      "available_fields": ["user_input", "stdin"]
    }
  ],
  "execution": {
    "steps": [
      {"node_id": "fetch-issues", "status": "failed", "duration_ms": 120.5}
    ]
  }
}

Key fields:

Field	Description
`success`	`true` if workflow completed, `false` if failed
`result`	Workflow output (object, string, or array based on declared outputs)
`duration_ms`	Total execution time in milliseconds
`total_cost_usd`	LLM API cost (0.0 if no LLM calls)
`errors[].available_fields`	Valid fields for template variables - helps agents fix errors

Print mode

Clean output for piping (no progress indicators):

pflow -p my-workflow > output.txt

Validation mode

Validate a workflow without running it:

pflow --validate-only workflow.pflow.md
pflow --validate-only my-saved-workflow

Agents use this to check workflows before running them — pflow catches template errors, type mismatches, and missing inputs during validation, so problems surface immediately instead of after step 5 fails. Exit code 0 means valid.

Traces

By default, pflow saves execution traces to ~/.pflow/debug/:

Workflow traces: workflow-trace-{name}-{timestamp}.json

Disable traces with --no-trace for faster execution.

Instructions command

The pflow instructions command provides guidance for AI agents using pflow.

pflow instructions <SUBCOMMAND>

Subcommand	Description
`usage`	Basic usage guide for AI agents (~100 lines)
`create`	Comprehensive workflow creation guide (~1600 lines)

Example:

# Get usage instructions (AI agents should run this first)
pflow instructions usage

# Get detailed workflow creation guide
pflow instructions create

AI agents should run pflow instructions usage when first connecting to pflow. This provides optimized guidance for agent-driven workflow building.

Workflow commands - Manage saved workflows
Skill commands - Publish workflows as AI agent skills
Registry commands - Browse available nodes
MCP commands - Manage MCP servers
Settings commands - Configure pflow

CLI commands

Nodes

Configuration

Experimental

CLI overview

Command structure

Command groups

pflow (default)

pflow workflow

pflow skill

pflow registry

pflow mcp

pflow settings

pflow instructions

Main command

Run a saved workflow

Run from a file

Global options

Parameter syntax

Stdin input

Output modes

Text mode (default)

JSON mode

Print mode

Validation mode

Traces

Instructions command

CLI commands

Nodes

Configuration

Experimental

​Command structure

​Command groups

pflow (default)

pflow workflow

pflow skill

pflow registry

pflow mcp

pflow settings

pflow instructions

​Main command

​Run a saved workflow

​Run from a file

​Global options

​Parameter syntax

​Stdin input

​Output modes

​Text mode (default)

​JSON mode

​Print mode

​Validation mode

​Traces

​Instructions command

​Related

Command structure

Command groups

Main command

Run a saved workflow

Run from a file

Global options

Parameter syntax

Stdin input

Output modes

Text mode (default)

JSON mode

Print mode

Validation mode

Traces

Instructions command

Related