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

# Configuration

> Settings file, environment variables, and file locations

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:

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

### Structure

```json theme={null}
{
  "version": "1.0.0",
  "registry": {
    "nodes": {
      "allow": ["*"],
      "deny": []
    },
    "output_mode": "smart"
  },
  "runtime": {
    "template_resolution_mode": "strict"
  },
  "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"`                                                  |
| `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)                                 |
| `env`                              | `{}`       | API keys and environment variables                                            |

### Commands

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

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

```bash theme={null}
# 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](/reference/cli/settings#llm-model-settings).

## Environment variables

### API keys

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

```bash theme={null}
pflow settings set-env ANTHROPIC_API_KEY "sk-ant-..."
pflow settings set-env OPENAI_API_KEY "sk-proj-..."
```

<Note>
  API keys stored via `pflow settings set-env` are used automatically for workflow inputs and discovery features. Your agent can't set these for security reasons.
</Note>

**Precedence order** (highest to lowest):

1. CLI parameters (`--param key=value`)
2. Settings file (`~/.pflow/settings.json` → `env`)
3. System environment variables

### pflow configuration variables

| Variable                         | Default  | Description                    |
| -------------------------------- | -------- | ------------------------------ |
| `PFLOW_TEMPLATE_RESOLUTION_MODE` | `strict` | `strict` or `permissive`       |
| `PFLOW_SHELL_STRICT`             | `false`  | Block dangerous shell commands |

### Trace configuration

Control trace file verbosity:

| Variable                    | Default | Description                   |
| --------------------------- | ------- | ----------------------------- |
| `PFLOW_TRACE_PROMPT_MAX`    | `50000` | Max prompt length in traces   |
| `PFLOW_TRACE_RESPONSE_MAX`  | `20000` | Max response length in traces |
| `PFLOW_TRACE_STORE_MAX`     | `10000` | Max shared store value length |
| `PFLOW_TRACE_DICT_MAX`      | `50000` | Max dict size in traces       |
| `PFLOW_TRACE_LLM_CALLS_MAX` | `100`   | Max LLM calls to track        |

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

1. **Deny patterns** - If matched, node is excluded
2. **Allow patterns** - If matched, node is included
3. **Default** - Included only if `*` is in allow list

<Warning>
  Deny patterns take precedence over allow patterns. If a node matches both, it's excluded.
</Warning>

### Commands

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

```bash theme={null}
pflow settings deny "shell"
```

**Allow only specific nodes**:

```bash theme={null}
# 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/`           | Yes            | Debug traces only, can grow large               |
| `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](/guides/adding-mcp-servers) for details.

The file uses the standard MCP configuration format:

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

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

1. System environment variables
2. pflow settings (`pflow settings set-env`)