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

No built-in natural language mode. pflow executes workflow files and saved workflows. Your AI agent builds workflows using pflow’s MCP tools or CLI primitives — pflow doesn’t have its own natural language interface.

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
`--cache/--no-cache`	Enable/disable memoization cache reads (default: enabled)
`--only NODE`	Run workflow through this node then stop
`--validate-only`	Validate workflow without running
`--help`	Show help message

Older natural-language workflow generation flags have been removed. Use the current global options shown above, or let your AI agent build .pflow.md workflows directly.

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,
    "cache_hits": 2,
    "steps": [
      {
        "node_id": "fetch-data",
        "status": "completed",
        "duration_ms": 0,
        "cached": true
      },
      {
        "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)
`execution.cache_hits`	Number of nodes served from memoization cache
`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.

Iteration and caching

pflow caches node outputs automatically. When your agent re-runs a workflow file, unchanged nodes return instantly from a persistent cache — only nodes whose configuration or inputs changed will re-execute.

# First run: all nodes execute
pflow ./workflow.pflow.md title=hello

# Second run (same inputs): all nodes served from cache
pflow ./workflow.pflow.md title=hello

# Changed input: only affected nodes re-execute
pflow ./workflow.pflow.md title=different

The cache is content-addressed — same node config plus same resolved inputs produces the same cache key, regardless of when or how the workflow was run. Cache entries expire after 24 hours. The cache lives at ~/.pflow/cache/cache.db.

Run a single node

The --only flag runs the workflow through the named node and stops. Upstream nodes are served from cache if available, downstream nodes don’t execute:

pflow ./workflow.pflow.md --only process-data

This is how agents iterate on a specific node without re-running the full workflow.

Bypass caching

Use --no-cache to force fresh execution. Cache writes still happen, so the next run without --no-cache benefits from the results:

pflow ./workflow.pflow.md --no-cache

Use this when a node has external side effects (API calls, file writes) that should always run, or when cached results seem stale.

Traces and reports

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

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

Generate a structured execution report (one markdown file per node):

# During execution
pflow my-workflow --report

# Custom output directory
pflow my-workflow --report-dir ./my-report/

# From an existing trace (most recent)
pflow trace report

# From a specific trace
pflow trace report ~/.pflow/debug/workflow-trace-my-workflow-20260323-160000.json

Reports include rendered prompts, responses, cost data, error summaries with fix suggestions, and anomaly warnings. Disable traces with --no-trace for faster execution (the --report flag overrides --no-trace).

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

Iteration and caching

Run a single node

Bypass caching

Traces and reports

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

​Iteration and caching

​Run a single node

​Bypass caching

​Traces and reports

​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

Iteration and caching

Run a single node

Bypass caching

Traces and reports

Instructions command

Related