pflow settings

The pflow settings command group manages pflow configuration stored in ~/.pflow/settings.json. This includes API keys, environment variables, and node filtering.

Your commands. These are setup commands that you run directly - not your agent. API keys and security settings should always be configured by you, never by an AI agent.

Commands

Command	Description
`init`	Initialize settings with defaults
`show`	Display current settings
`set-env`	Set an environment variable
`unset-env`	Remove an environment variable
`list-env`	List all environment variables
`allow`	Add an allow pattern
`deny`	Add a deny pattern
`remove`	Remove a pattern
`check`	Check if a node is allowed
`reset`	Reset to defaults
`llm show`	Show LLM model settings
`llm set-default`	Set default model for all features
`llm set-discovery`	Set model for discovery commands
`llm set-filtering`	Set model for smart filtering
`llm set-tts-model`	Set the TTS model for `pflow ui --say` narration
`llm set-tts-voice`	Set the TTS voice for `pflow ui --say` narration
`llm unset`	Remove an LLM model setting
`registry output-mode`	Set registry run output display mode

pflow settings init

Initialize settings file with defaults.

pflow settings init

Creates ~/.pflow/settings.json with default configuration. Prompts for confirmation if the file already exists. Default settings:

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

pflow settings show

Display current settings with sensitive values masked.

pflow settings show

Output:

Settings file: ~/.pflow/settings.json

Current settings:
{
  "version": "1.0.0",
  "registry": {
    "nodes": {
      "allow": ["*"],
      "deny": []
    }
  },
  "llm": {
    "default_model": "openai/gpt-5.2",
    "discovery_model": null,
    "filtering_model": null
  },
  "env": {
    "ANTHROPIC_API_KEY": "sk-***",
    "log_level": "debug"
  }
}

Sensitive values (API keys, tokens, secrets) are automatically masked. Use pflow settings list-env --show-values to see full values.

pflow settings set-env

Set an environment variable for pflow workflows.

pflow settings set-env <KEY> <VALUE>

Arguments:

KEY - Environment variable name
VALUE - Environment variable value

Examples:

# Set API keys for LLM providers
pflow settings set-env OPENAI_API_KEY "sk-..."
pflow settings set-env ANTHROPIC_API_KEY "sk-ant-..."

# Set other variables
pflow settings set-env GITHUB_TOKEN "ghp_..."

Output:

✓ Set environment variable: OPENAI_API_KEY
   Value: sk-***

Security: Always set API keys yourself - never let AI agents run this command.

Alternative: Set the key as a shell environment variable instead — pflow (via LiteLLM) reads ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, and provider-specific equivalents directly from os.environ.

pflow settings unset-env

Remove an environment variable.

pflow settings unset-env <KEY>

Arguments:

KEY - Environment variable name to remove

Example:

pflow settings unset-env GITHUB_TOKEN

pflow settings list-env

List all configured environment variables.

pflow settings list-env [--show-values]

Options:

--show-values - Display full unmasked values (use with caution)

Examples:

# List with masked values (safe)
pflow settings list-env

# List with full values (sensitive!)
pflow settings list-env --show-values

Output (masked):

Environment variables:
  OPENAI_API_KEY: sk-***
  GITHUB_TOKEN: ghp***
  LOG_LEVEL: debug

Only use --show-values in secure environments. Never let agents access unmasked credentials.

pflow settings allow

Add an allow pattern for node filtering.

pflow settings allow <PATTERN>

Arguments:

PATTERN - Glob-style pattern for nodes to allow

Examples:

# Allow all file nodes
pflow settings allow "pflow.nodes.file.*"

# Allow specific MCP tools
pflow settings allow "mcp-github-*"

# Allow specific node
pflow settings allow "llm"

Pattern syntax:

* matches any characters
? matches single character
[seq] matches any character in seq

pflow settings deny

Add a deny pattern for node filtering.

pflow settings deny <PATTERN>

Arguments:

PATTERN - Glob-style pattern for nodes to deny

Examples:

# Block dangerous operations
pflow settings deny "shell"
pflow settings deny "*-delete-*"

Deny patterns take precedence over allow patterns.

pflow settings remove

Remove a pattern from allow or deny list.

pflow settings remove <PATTERN> [--allow|--deny]

Arguments:

PATTERN - Pattern to remove

Options:

--allow - Remove from allow list (default)
--deny - Remove from deny list

Examples:

# Remove from deny list
pflow settings remove "shell" --deny

# Remove from allow list
pflow settings remove "file.*" --allow

pflow settings check

Check if a node would be included based on current settings.

pflow settings check <NODE_NAME>

Arguments:

NODE_NAME - Node name to check

Example:

pflow settings check read-file

Output (included):

✓ Node 'read-file' would be INCLUDED

  Matched allow patterns: file.*, *

Output (excluded):

✗ Node 'shell' would be EXCLUDED

  Matched deny patterns: shell

pflow settings reset

Reset settings to defaults.

pflow settings reset

Prompts for confirmation before resetting. This removes all custom settings including API keys.

This deletes ALL custom settings including environment variables and API keys.

LLM model settings

These commands let you override which models pflow uses for its internal features. By default, pflow auto-detects based on your configured API keys - these are optional.

pflow settings llm show

Display LLM model settings with resolution status.

pflow settings llm show

Output:

LLM Model Settings:

  default_model:    openai/gpt-5.2 (configured)
  discovery_model:  (using default_model → openai/gpt-5.2)
  filtering_model:  (using default_model → openai/gpt-5.2)
  tts_model:        gemini-3.1-flash-tts-preview
  tts_voice:        Kore

Resolution order:
  default:    workflow params → default_model → auto-detect → error
  discovery:  discovery_model → default_model → auto-detect → fallback
  filtering:  filtering_model → default_model → auto-detect → fallback

To configure:
  pflow settings llm set-default <model>
  pflow settings llm set-discovery <model>
  pflow settings llm set-filtering <model>
  pflow settings llm set-tts-model <model>
  pflow settings llm set-tts-voice <voice>

pflow settings llm set-default

Override the auto-detected model for all pflow LLM usage.

pflow settings llm set-default <MODEL>

Arguments:

MODEL - Model identifier (e.g., openai/gpt-5.2, anthropic/claude-sonnet-4-5, gemini/gemini-3-flash-preview). LiteLLM requires the provider prefix.

When set, this model is used instead of auto-detection for:

LLM nodes in workflows (when no model specified in params)
Discovery commands (when discovery_model not set)
Smart filtering (when filtering_model not set)

Examples:

# Set OpenAI model
pflow settings llm set-default openai/gpt-5.2

# Set Anthropic model
pflow settings llm set-default anthropic/claude-sonnet-4-5

# Set Google model
pflow settings llm set-default gemini/gemini-3-flash-preview

This is optional - pflow auto-detects a model based on your API keys. Use this if you want a specific model instead of the auto-detected one.

Bare model names are auto-prefixed. Bare names from known providers (gpt-*, o1*, o3*, o4*, claude-*, gemini-*) are rewritten to the canonical <provider>/<name> form at write time, with a Normalized: line confirming the rewrite. Unknown bare names pass through with a warning so custom or self-hosted models still work. This applies to set-default, set-discovery, and set-filtering — not to the TTS setters (TTS ids aren’t LiteLLM-routed).

$ pflow settings llm set-default gemini-3-flash-preview
  Normalized: gemini/gemini-3-flash-preview
✓ Set default_model: gemini/gemini-3-flash-preview

pflow settings llm set-discovery

Set the model for discovery commands (pflow mcp find, pflow find).

pflow settings llm set-discovery <MODEL>

Arguments:

MODEL - Model identifier

Example:

# Use a fast, cheap model for discovery
pflow settings llm set-discovery gemini/gemini-3-flash-preview

pflow settings llm set-filtering

Set the model for smart field filtering (used when smart output mode filters large API responses).

pflow settings llm set-filtering <MODEL>

Arguments:

MODEL - Model identifier

Example:

# Use a fast, cheap model for filtering
pflow settings llm set-filtering gemini/gemini-2.5-flash-lite

Smart filtering is a simple task - use a fast, cheap model.Recommended (fast + cheap):

Provider	Model	Overhead	Notes
Google	`gemini/gemini-2.5-flash-lite`	~2-3s	Best budget option
OpenAI	`openai/gpt-5-mini`	~1-2s	Runner-up budget
Anthropic	`anthropic/claude-haiku-4-5`	~1-2s	Third place budget

Alternative (higher cost):

Provider	Model	Overhead	Notes
Anthropic	`anthropic/claude-sonnet-5`	~1-2s	Best premium option
Google	`gemini/gemini-3.5-flash-lite`	~2-3s	Cheap, fast runner-up
OpenAI	`openai/gpt-5.6-luna`	varies	Common fallback

All models produce equivalent quality for this task. Timings are approximate and vary with network latency.

pflow settings llm set-tts-model / set-tts-voice

Configure voice narration for pflow ui focus/frame --say (see the UI command). Both have working defaults — you only need these to change the voice or track a new TTS model. Narration also needs a Gemini API key (pflow settings set-env GEMINI_API_KEY <value>).

pflow settings llm set-tts-model <MODEL>   # a Gemini TTS model id
pflow settings llm set-tts-voice <VOICE>   # a Gemini prebuilt voice name, e.g. Kore (default), Puck

Example:

pflow settings llm set-tts-voice Puck

pflow settings llm unset

Remove an LLM model setting. Models revert to auto-detection; the TTS fields revert to their built-in defaults.

pflow settings llm unset {default|discovery|filtering|tts-model|tts-voice|all}

Arguments:

SETTING - Which setting to remove: default, discovery, filtering, tts-model, tts-voice, or all

Examples:

# Clear default model
pflow settings llm unset default

# Clear discovery model (will use default_model or auto-detect)
pflow settings llm unset discovery

# Back to the default narration voice
pflow settings llm unset tts-voice

# Clear all LLM settings
pflow settings llm unset all

Model resolution order

pflow uses the same resolution order for all LLM usage (discovery, filtering, and workflow LLM nodes):

Explicit setting (workflow params or feature-specific setting)
default_model from settings
Auto-detect from configured API keys (Anthropic → Google → OpenAI)
Error with setup instructions

Auto-detected defaults by provider:

Provider	Default model
Anthropic	`anthropic/claude-sonnet-5`
Google	`gemini/gemini-3.5-flash-lite`
OpenAI	`openai/gpt-5.6-luna`

Most users just need an API key configured. pflow auto-detects the appropriate model. Use these commands only to override the auto-detected model.

Registry settings

Configure how pflow probe displays output.

pflow settings registry output-mode

Show or set the output display mode for pflow probe.

pflow settings registry output-mode [MODE]

Arguments:

MODE (optional) - One of smart, structure, or full. If omitted, shows current mode.

Modes:

Mode	Description
`smart` (default)	Shows template paths with values. Uses LLM to filter large outputs (>30 fields) to relevant fields.
`structure`	Shows template paths only (no values). No filtering - shows all fields. Fast, no LLM overhead.
`full`	Shows all fields with full values, no truncation or filtering.

Examples:

# Show current mode
pflow settings registry output-mode

# Set to smart (default - shows values with truncation)
pflow settings registry output-mode smart

# Set to structure-only (paths without values)
pflow settings registry output-mode structure

# Set to full (all values, no truncation)
pflow settings registry output-mode full

Use structure mode when working with sensitive data — it shows types and paths without actual values, so your agent can build workflows without ever seeing the data itself. Avoid full mode with AI agents — it shows all values without truncation and can consume excessive tokens.

See pflow probe for the command that uses these output modes.

How node filtering works

Node filtering uses allow and deny patterns evaluated in this order:

Deny patterns - Block matching nodes (highest precedence)
Allow patterns - Include matching nodes
Default - Include if * in allow list

Example configuration:

{
  "registry": {
    "nodes": {
      "allow": ["*"],
      "deny": ["shell"]
    }
  }
}

This allows all nodes except test nodes and the shell node.

Environment variable precedence

When workflows need parameters, pflow looks in this order:

CLI parameters (key=value arguments)
Settings environment variables (pflow settings set-env)
Workflow defaults
Error if required and not found

Example:

# Store API key once
pflow settings set-env OPENAI_API_KEY "sk-..."

# Workflows automatically use it
pflow my-llm-workflow  # No need to pass --param

Sensitive parameter detection

These keys are automatically masked in output:

password, passwd, pwd
token, api_token, access_token, auth_token
api_key, apikey, api-key
secret, client_secret, secret_key
private_key, ssh_key

Matching is case-insensitive.

File locations

Path	Purpose
`~/.pflow/settings.json`	Settings file

CLI overview - Main pflow command
Configuration reference - All configuration options
Quickstart - Initial setup including API keys

CLI commands

Nodes

Configuration

Experimental

pflow settings

Commands

pflow settings init

pflow settings show

pflow settings set-env

pflow settings unset-env

pflow settings list-env

pflow settings allow

pflow settings deny

pflow settings remove

pflow settings check

pflow settings reset

LLM model settings

pflow settings llm show

pflow settings llm set-default

pflow settings llm set-discovery

pflow settings llm set-filtering

pflow settings llm set-tts-model / set-tts-voice

pflow settings llm unset

Model resolution order

Registry settings

pflow settings registry output-mode

How node filtering works

Environment variable precedence

Sensitive parameter detection

File locations

​Commands

​pflow settings init

​pflow settings show

​pflow settings set-env

​pflow settings unset-env

​pflow settings list-env

​pflow settings allow

​pflow settings deny

​pflow settings remove

​pflow settings check

​pflow settings reset

​LLM model settings

​pflow settings llm show

​pflow settings llm set-default

​pflow settings llm set-discovery

​pflow settings llm set-filtering

​pflow settings llm set-tts-model / set-tts-voice

​pflow settings llm unset

​Model resolution order

​Registry settings

​pflow settings registry output-mode

​How node filtering works

​Environment variable precedence

​Sensitive parameter detection

​File locations

​Related

Commands

pflow settings init

pflow settings show

pflow settings set-env

pflow settings unset-env

pflow settings list-env

pflow settings allow

pflow settings deny

pflow settings remove

pflow settings check

pflow settings reset

LLM model settings

pflow settings llm show

pflow settings llm set-default

pflow settings llm set-discovery

pflow settings llm set-filtering

pflow settings llm set-tts-model / set-tts-voice

pflow settings llm unset

Model resolution order

Registry settings

pflow settings registry output-mode

How node filtering works

Environment variable precedence

Sensitive parameter detection

File locations

Related