Configuration

pflow stores configuration in ~/.pflow/. This page covers the settings file structure, environment variables, node filtering, and file locations.

Settings file

pflow stores user configuration in ~/.pflow/settings.json. View current settings with:

pflow settings show

Structure

{
  "version": "1.0.0",
  "registry": {
    "nodes": {
      "allow": ["*"],
      "deny": []
    },
    "output_mode": "smart"
  },
  "runtime": {
    "template_resolution_mode": "strict",
    "trace_retention_days": 14
  },
  "llm": {
    "default_model": null,
    "discovery_model": null,
    "filtering_model": null
  },
  "env": {}
}

Fields

Field	Default	Description
`registry.nodes.allow`	`["*"]`	Patterns for nodes to include
`registry.nodes.deny`	`[]`	Patterns for nodes to exclude
`registry.output_mode`	`"smart"`	Output display mode for `registry run`: `"smart"`, `"structure"`, or `"full"`
`runtime.template_resolution_mode`	`"strict"`	`"strict"` or `"permissive"`
`runtime.trace_retention_days`	`14`	Days a trace is kept in `~/.pflow/debug/`; `0` keeps every trace. See trace retention
`llm.default_model`	`null`	Default model for all pflow LLM usage
`llm.discovery_model`	`null`	Model for discovery commands (overrides default)
`llm.filtering_model`	`null`	Model for smart filtering (overrides default)
`llm.tts_model`	`"gemini-3.1-flash-tts-preview"`	TTS model for `pflow ui --say` narration
`llm.tts_voice`	`"Kore"`	TTS voice for `pflow ui --say` narration
`env`	`{}`	API keys and environment variables

Commands

# Initialize settings file
pflow settings init

# Show current settings
pflow settings show

# Reset to defaults
pflow settings reset

LLM model configuration

pflow uses LLMs for discovery features, smart filtering, and the LLM node in workflows. Set up an API key, and pflow auto-detects which model to use.

API key setup

# Set an API key (any llm-supported provider works)
pflow settings set-env OPENAI_API_KEY "sk-..."

pflow auto-detects available providers based on configured API keys.

Override the model (optional)

To use a specific model instead of auto-detection:

# Set a default model for all pflow features
pflow settings llm set-default openai/gpt-5.2

# Or configure specific features
pflow settings llm set-discovery anthropic/claude-haiku-4-5
pflow settings llm set-filtering gemini/gemini-3-flash-preview

# View current configuration
pflow settings llm show

Resolution order

pflow auto-detects a model based on your configured API keys. To override this or see the full resolution order and default models, see LLM model settings.

Environment variables

API keys

Store API keys in the settings file for security (automatically chmod 600):

pflow settings set-env ANTHROPIC_API_KEY "sk-ant-..."
pflow settings set-env OPENAI_API_KEY "sk-proj-..."

API keys stored via pflow settings set-env are used automatically for workflow inputs and discovery features, and are exported into pflow’s environment when a run starts (see set-env). Your agent can’t set these for security reasons.

Precedence order for a workflow input (highest to lowest):

CLI parameters (key=value)
System environment variables
Settings file (~/.pflow/settings.json → env)
Workflow defaults

pflow configuration variables

Variable	Default	Description
`PFLOW_TEMPLATE_RESOLUTION_MODE`	`strict`	`strict` or `permissive`
`PFLOW_SHELL_STRICT`	`false`	Block dangerous shell commands
`PFLOW_TRACE_RETENTION_DAYS`	unset	Overrides `runtime.trace_retention_days` for one process (`0` keeps every trace); never saved to the settings file

Trace configuration

Every run writes a trace to ~/.pflow/debug/ unless you pass --no-trace (--report and --report-dir turn tracing back on). pflow removes traces older than runtime.trace_retention_days when it finishes writing a trace, and keeps the traces its features still need — pending pauses, each workflow’s newest run and newest successful run, and runs still being written. See trace retention.

Node filtering

Control which nodes are available using allow/deny patterns.

Pattern syntax

pflow uses glob-style patterns (fnmatch):

Pattern	Matches
`*`	Everything
`pflow.nodes.file.*`	All file nodes
`mcp-github-*`	All GitHub MCP tools
`shell`	Exact match only

Evaluation order

Deny patterns - If matched, node is excluded
Allow patterns - If matched, node is included
Default - Included only if * is in allow list

Deny patterns take precedence over allow patterns. If a node matches both, it’s excluded.

Commands

# Allow a pattern
pflow settings allow "pflow.nodes.file.*"

# Deny a pattern
pflow settings deny "shell"

# Remove a pattern
pflow settings remove "shell" --deny

# Check if a node would be included
pflow settings check read-file

# Verify filtering took effect
pflow mcp list              # See all available nodes
pflow mcp list file         # Filter to specific nodes

Examples

Block shell access:

pflow settings deny "shell"

Allow only specific nodes:

# First, remove the wildcard
pflow settings remove "*" --allow

# Then add specific patterns
pflow settings allow "pflow.nodes.file.*"
pflow settings allow "llm"
pflow settings allow "http"

File locations

pflow stores all data in ~/.pflow/:

~/.pflow/
├── settings.json       # User settings + API keys
├── mcp-servers.json    # MCP server configurations
├── registry.json       # Node registry cache
├── workflows/          # Saved workflows
├── debug/              # Trace files
└── cache/              # Execution cache

What’s safe to delete

Path	Safe to Delete	Notes
`registry.json`	Yes	Regenerates automatically on next pflow startup
`debug/`	Caution	Deleting a trace breaks `--only`, `pflow resume`, a pending pause’s answer and `pflow report` for that run — pflow prunes traces itself on `runtime.trace_retention_days`
`cache/`	Yes	Execution cache, regenerates
`settings.json`	Caution	Contains API keys, reverts to defaults
`mcp-servers.json`	Caution	Removes MCP server configurations
`workflows/`	No	User-created workflows

MCP server configuration

MCP servers are configured in ~/.pflow/mcp-servers.json. See Adding MCP servers for details. The file uses the standard MCP configuration format:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@github/mcp-server"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Environment variables in the config (${VAR}) are resolved from:

System environment variables
pflow settings (pflow settings set-env)

CLI commands

Nodes

Configuration

Experimental

Configuration

Settings file

Structure

Fields

Commands

LLM model configuration

API key setup

Override the model (optional)

Resolution order

Environment variables

API keys

pflow configuration variables

Trace configuration

Node filtering

Pattern syntax

Evaluation order

Commands

Examples

File locations

What’s safe to delete

MCP server configuration

​Settings file

​Structure

​Fields

​Commands

​LLM model configuration

​API key setup

​Override the model (optional)

​Resolution order

​Environment variables

​API keys

​pflow configuration variables

​Trace configuration

​Node filtering

​Pattern syntax

​Evaluation order

​Commands

​Examples

​File locations

​What’s safe to delete

​MCP server configuration

Settings file

Structure

Fields

Commands

LLM model configuration

API key setup

Override the model (optional)

Resolution order

Environment variables

API keys

pflow configuration variables

Trace configuration

Node filtering

Pattern syntax

Evaluation order

Commands

Examples

File locations

What’s safe to delete

MCP server configuration