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 execute 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 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 runs this to execute 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.json
pflow ~/workflows/analysis.json param=value

Natural language mode (experimental)

pflow can generate workflows from natural language, but this feature is experimental. For production use, we recommend letting 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 Anthropic API key.

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
`--trace-planner`	Save planner execution trace
`--validate-only`	Validate workflow without executing
`--auto-repair`	Enable automatic workflow repair on failure
`--help`	Show help message

Planner options (experimental)

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

Option	Description
`--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

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:

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

Stdin data is available in the workflow as ${stdin}.

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 executing it:

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

Agents use this to check workflows before running them. Exit code 0 means valid.

Traces

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

Workflow traces: workflow-trace-{name}-{timestamp}.json
Planner traces: planner-trace-{timestamp}.json (with --trace-planner)

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
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 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 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