Skip to main content
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. Read-only discovery (llm show, llm providers, llm models) is safe for agents to run.

Commands

pflow settings init

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

pflow settings show

Display current settings with every env value masked.
Output:
Every env value is masked to its length (*** (N chars)), whatever its name — the same rule as list-env. Use pflow settings list-env --show-values to see full values.

pflow settings set-env

Set an environment variable for pflow workflows.
Arguments:
  • KEY - Environment variable name
  • VALUE - Environment variable value
Examples:
Output:
Security: Always set API keys yourself - never let AI agents run this command.
Where a stored value goes:
  • It fills the declared workflow input of the same name. A ${...} template reads it only through that input.
  • It is exported into pflow’s environment when a run starts, unless your shell already exports that name. Shell, code and agent steps see it like any other exported variable, and LLM providers that LiteLLM handles itself (such as OpenRouter) find their keys there.
Alternative: Set the key as a shell environment variable instead. pflow reads ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, and provider-specific equivalents from your environment first, then from settings.

pflow settings unset-env

Remove an environment variable.
Arguments:
  • KEY - Environment variable name to remove
Example:

pflow settings list-env

List all configured environment variables.
Options:
  • --show-values - Display full unmasked values (use with caution)
Examples:
Output (masked):
Only use --show-values in secure environments. Never let agents access unmasked credentials.

pflow settings allow

Add an allow pattern for node filtering.
Arguments:
  • PATTERN - Glob-style pattern for nodes to allow
Examples:
Pattern syntax:
  • * matches any characters
  • ? matches single character
  • [seq] matches any character in seq

pflow settings deny

Add a deny pattern for node filtering.
Arguments:
  • PATTERN - Glob-style pattern for nodes to deny
Examples:
Deny patterns take precedence over allow patterns.

pflow settings remove

Remove a pattern from allow or deny list.
Arguments:
  • PATTERN - Pattern to remove
Options:
  • --allow - Remove from allow list (default)
  • --deny - Remove from deny list
Examples:

pflow settings check

Check if a node would be included based on current settings.
Arguments:
  • NODE_NAME - Node name to check
Example:
Output (included):
Output (excluded):

pflow settings reset

Reset settings to defaults.
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.
Output:

pflow settings llm models

List the model ids you can pass to an LLM node’s model, per provider.
  • No keyword: up to 10 models for each provider you have a key for, each with a see all command.
  • A provider name (e.g. anthropic, bedrock): that provider’s complete list, even without a key. The header shows the env var to set.
  • Any other keyword: filters model ids across your configured providers (or within a named provider). All keywords must match; matching ignores case.
Models come from LiteLLM’s model catalog, limited to ones an LLM node can call: chat and responses models, without pricing-only or deprecated entries. The list is fetched live and falls back to the snapshot bundled with LiteLLM when offline; the first line says which. The order is mechanical (by name, higher version numbers first) — not a ranking. Any LiteLLM model works as provider/model even if it isn’t listed. The catalog can also lag behind a provider: an id it still lists may already be retired (the run then fails with Unknown model and names a working one). Examples:
JSON output:
source is live or offline; status is set, - (no key) or n/a (local provider). JSON lists every matched model. Naming a provider inspects it without its key. With no provider named and no keys configured, or when nothing matches, providers is empty and the guidance goes to stderr.

pflow settings llm set-default

Override the auto-detected model for all pflow LLM usage.
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:
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-discovery

Set the model for discovery commands (pflow mcp find, pflow find).
Arguments:
  • MODEL - Model identifier
Example:

pflow settings llm set-filtering

Set the model for smart field filtering (used when smart output mode filters large API responses).
Arguments:
  • MODEL - Model identifier
Example:
Smart filtering is a simple task - use a fast, cheap model.Recommended (fast + cheap):Alternative (higher cost):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>).
Example:

pflow settings llm unset

Remove an LLM model setting. Models revert to auto-detection; the TTS fields revert to their built-in defaults.
Arguments:
  • SETTING - Which setting to remove: default, discovery, filtering, tts-model, tts-voice, or all
Examples:

Model resolution order

pflow uses the same resolution order for all LLM usage (discovery, filtering, and workflow LLM nodes):
  1. Explicit setting (workflow params or feature-specific setting)
  2. default_model from settings
  3. Auto-detect from configured API keys (Anthropic → Google → OpenAI)
  4. Error with setup instructions
Auto-detected defaults by provider:
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.
Arguments:
  • MODE (optional) - One of smart, structure, or full. If omitted, shows current mode.
Modes: Examples:
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:
  1. Deny patterns - Block matching nodes (highest precedence)
  2. Allow patterns - Include matching nodes
  3. Default - Include if * in allow list
Example configuration:
This allows all nodes except test nodes and the shell node.

Environment variable precedence

When a workflow declares an input, pflow looks for its value in this order:
  1. CLI parameters (key=value arguments)
  2. Shell environment variables (export key=value)
  3. Settings environment variables (pflow settings set-env)
  4. Workflow defaults
  5. Error if required and not found
Example:

Sensitive parameter detection

Values under these names are masked as <REDACTED> when pflow displays them:
  • password, passwd, pwd
  • token, api_token, access_token, auth_token
  • api_key, apikey, api-key
  • secret, client_secret, secret_key
  • private_key, ssh_key
  • credential, credentials, authorization, auth
  • cookie, cookies (so the HTTP Cookie and Set-Cookie headers)
Matching is case-insensitive and by whole word, across snake_case, kebab-case and camelCase: GITHUB_TOKEN, X-API-Key and sessionCookie are masked, while author and tokens are not. Masking applies to pflow report, the web UI, approval previews and error output. Execution always uses the real value, and declared workflow outputs are not masked by name.

Secret values

Masking by name misses a secret that travels into free text — shell stderr, an error message, a workflow result. So pflow also replaces every occurrence of a run’s secret values with <REDACTED> in everything it prints: CLI text and JSON output (results included), MCP responses, pflow report, the web UI and -v. A run’s secret values are every value stored with pflow settings set-env and every value passed to a declared input with a sensitive name — strings of 8 characters or more. A value exported only in your shell, or one a step produces mid-run, is not known to be secret and prints as is. The trace file keeps every value raw so pflow resume can restore it.

File locations