> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pflow.run/llms.txt
> Use this file to discover all available pages before exploring further.

# pflow settings

> Manage pflow configuration

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

<Note>
  **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.
</Note>

## 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 unset`            | Remove an LLM model setting          |
| `registry output-mode` | Set registry run output display mode |

## pflow settings init

Initialize settings file with defaults.

```bash theme={null}
pflow settings init
```

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

**Default settings:**

```json theme={null}
{
  "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.

```bash theme={null}
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"
  }
}
```

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

## pflow settings set-env

Set an environment variable for pflow workflows.

```bash theme={null}
pflow settings set-env <KEY> <VALUE>
```

**Arguments:**

* `KEY` - Environment variable name
* `VALUE` - Environment variable value

**Examples:**

```bash theme={null}
# 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-***
```

<Warning>
  **Security:** Always set API keys yourself - never let AI agents run this command.
</Warning>

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

```bash theme={null}
pflow settings unset-env <KEY>
```

**Arguments:**

* `KEY` - Environment variable name to remove

**Example:**

```bash theme={null}
pflow settings unset-env GITHUB_TOKEN
```

## pflow settings list-env

List all configured environment variables.

```bash theme={null}
pflow settings list-env [--show-values]
```

**Options:**

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

**Examples:**

```bash theme={null}
# 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
```

<Warning>
  Only use `--show-values` in secure environments. Never let agents access unmasked credentials.
</Warning>

## pflow settings allow

Add an allow pattern for node filtering.

```bash theme={null}
pflow settings allow <PATTERN>
```

**Arguments:**

* `PATTERN` - Glob-style pattern for nodes to allow

**Examples:**

```bash theme={null}
# 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.

```bash theme={null}
pflow settings deny <PATTERN>
```

**Arguments:**

* `PATTERN` - Glob-style pattern for nodes to deny

**Examples:**

```bash theme={null}
# Block dangerous operations
pflow settings deny "shell"
pflow settings deny "*-delete-*"
```

<Note>
  Deny patterns take precedence over allow patterns.
</Note>

## pflow settings remove

Remove a pattern from allow or deny list.

```bash theme={null}
pflow settings remove <PATTERN> [--allow|--deny]
```

**Arguments:**

* `PATTERN` - Pattern to remove

**Options:**

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

**Examples:**

```bash theme={null}
# 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.

```bash theme={null}
pflow settings check <NODE_NAME>
```

**Arguments:**

* `NODE_NAME` - Node name to check

**Example:**

```bash theme={null}
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.

```bash theme={null}
pflow settings reset
```

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

<Warning>
  This deletes ALL custom settings including environment variables and API keys.
</Warning>

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

```bash theme={null}
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)

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

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

```bash theme={null}
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:**

```bash theme={null}
# 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
```

<Tip>
  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.
</Tip>

<Note>
  **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 all three `set-*` commands below.

  ```bash theme={null}
  $ pflow settings llm set-default gemini-3-flash-preview
    Normalized: gemini/gemini-3-flash-preview
  ✓ Set default_model: gemini/gemini-3-flash-preview
  ```
</Note>

### pflow settings llm set-discovery

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

```bash theme={null}
pflow settings llm set-discovery <MODEL>
```

**Arguments:**

* `MODEL` - Model identifier

**Example:**

```bash theme={null}
# 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).

```bash theme={null}
pflow settings llm set-filtering <MODEL>
```

**Arguments:**

* `MODEL` - Model identifier

**Example:**

```bash theme={null}
# Use a fast, cheap model for filtering
pflow settings llm set-filtering gemini/gemini-2.5-flash-lite
```

<Tip>
  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-4-5`   | \~1-2s   | Best premium option     |
  | Google    | `gemini/gemini-3-flash-preview` | \~2-3s   | Runner-up premium       |
  | OpenAI    | `openai/gpt-5.2`                | \~5-6s   | Slower, not recommended |

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

### pflow settings llm unset

Remove an LLM model setting, reverting to auto-detection.

```bash theme={null}
pflow settings llm unset {default|discovery|filtering|all}
```

**Arguments:**

* `SETTING` - Which setting to remove: `default`, `discovery`, `filtering`, or `all`

**Examples:**

```bash theme={null}
# Clear default model
pflow settings llm unset default

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

# 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):

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

| Provider  | Default model                   |
| --------- | ------------------------------- |
| Anthropic | `anthropic/claude-sonnet-4-5`   |
| Google    | `gemini/gemini-3-flash-preview` |
| OpenAI    | `openai/gpt-5.2`                |

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

## Registry settings

Configure how `pflow probe` displays output.

### pflow settings registry output-mode

Show or set the output display mode for `pflow probe`.

```bash theme={null}
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:**

```bash theme={null}
# 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
```

<Warning>
  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.
</Warning>

See [pflow probe](/reference/cli/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:**

```json theme={null}
{
  "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:

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

**Example:**

```bash theme={null}
# 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 |

## Related

* [CLI overview](/reference/cli/index) - Main pflow command
* [Configuration reference](/reference/configuration) - All configuration options
* [Quickstart](/quickstart) - Initial setup including API keys