Configuration¶

Master the cascading configuration system that makes WireFlow flexible and powerful.

Configuration Cascade¶

WireFlow uses a cascading configuration system where each level inherits from and can override previous levels:

Builtin Defaults
    ↓
Global Config (~/.config/wireflow/config)
    ↓
Ancestor Projects (grandparent → parent)
    ↓
Project Config (.workflow/config)
    ↓
Workflow Config (.workflow/run/<name>/config)
    ↓
CLI Flags (--model, --temperature, etc.)

Key principle: Empty values pass through to inherit from parent levels. Set a value to override.

Configuration Levels¶

1. Global Configuration¶

Location: ~/.config/wireflow/config

MODEL=claude-sonnet-4-5
TEMPERATURE=1.0
MAX_TOKENS=4096
OUTPUT_FORMAT=md
SYSTEM_PROMPTS=(base)

2. Project Configuration¶

Location: .workflow/config

MODEL=claude-opus-4
TEMPERATURE=0.5
SYSTEM_PROMPTS=(base research)
MAX_TOKENS=        # Inherit from global

3. Workflow Configuration¶

Location: .workflow/run/<name>/config

INPUT=(data.csv notes.md)
DEPENDS_ON=(preprocessing)
TEMPERATURE=0.3
SYSTEM_PROMPTS+=(statistics)  # Append to project's prompts

4. CLI Overrides¶

wfw run analysis --model claude-opus-4 --temperature 0.3
wfw run analysis -cx extra-notes.md

Variable Syntax¶

Scalar Variables¶

MODEL=claude-opus-4     # Override parent
MODEL=                  # Inherit from parent (pass-through)

Array Variables¶

CONTEXT=           # Inherit from parent
CONTEXT=()         # Clear (reset to empty)
CONTEXT=(file.pdf) # Replace (override parent)
CONTEXT+=(add.pdf) # Append (add to parent)

# Glob patterns expand at config source time (from project root)
CONTEXT=(data/*.csv notes.md docs/**/*.pdf)

# Multi-line arrays (use quotes for filenames with spaces)
CONTEXT=(
    "notes/background.md"
    "data/results.csv"
)

Configuration Variables¶

Model & Profile¶

Variable	Description	Default
`PROFILE`	Model tier: `fast`, `balanced`, `deep`	`balanced`
`MODEL_FAST`	Model for fast profile	`claude-haiku-4-5`
`MODEL_BALANCED`	Model for balanced profile	`claude-sonnet-4-5`
`MODEL_DEEP`	Model for deep profile	`claude-opus-4-5`
`MODEL`	Explicit model override	(empty)

Extended Thinking & Effort¶

Variable	Description	Default
`ENABLE_THINKING`	Enable extended thinking	`false`
`THINKING_BUDGET`	Token budget (min 1024)	`10000`
`EFFORT`	Opus 4.5 effort: `low`, `medium`, `high`	`high`

API Settings¶

Variable	Description	Default
`TEMPERATURE`	Randomness (0.0-1.0)	`1.0`
`MAX_TOKENS`	Max response tokens	`16000`
`ENABLE_CITATIONS`	Enable source citations	`false`

Provider Selection¶

Variable	Description	Default
`PROVIDER`	API provider: `anthropic` or `openai`	`anthropic`
`OPENAI_BASE_URL`	OpenAI-compatible server URL	(empty)
`OPENAI_API_KEY`	API key for OpenAI provider	`lm-studio`
`OPENAI_MODEL`	Explicit model override	(empty)
`OPENAI_MODEL_FAST`	Model for fast profile	(empty)
`OPENAI_MODEL_BALANCED`	Model for balanced profile	(empty)
`OPENAI_MODEL_DEEP`	Model for deep profile	(empty)

Example configuration for LM Studio:

# ~/.config/wireflow/config
PROVIDER="openai"
OPENAI_BASE_URL="http://localhost:1234"
OPENAI_MODEL_FAST="phi-4-mini"
OPENAI_MODEL_BALANCED="qwen2.5-14b"
OPENAI_MODEL_DEEP="qwen2.5-72b"

Feature Differences

When using the OpenAI provider, some Anthropic-specific features are unavailable:

Extended thinking: Warned and skipped
Effort parameter: Warned and skipped
Citations: Disabled with warning
Native PDF: Automatically converted to page images
Batch API: Not supported
Prompt caching: Silently ignored (no cost savings)

Output & Prompts¶

Variable	Description	Default
`OUTPUT_FORMAT`	File extension (`md`, `txt`, `json`)	`md`
`EXPORT_PATH`	Additional output path	(empty)
`SYSTEM_PROMPTS`	Prompt names	`(base)`
`WIREFLOW_PROMPT_PREFIX`	Prompts directory	`~/.config/wireflow/prompts`

Context & Input¶

Variable	Description	Scope
`CONTEXT`	Context file paths	Project, Workflow
`INPUT`	Input file paths	Workflow
`DEPENDS_ON`	Workflow dependencies	Workflow

Path types accepted: Relative paths (project-root relative), absolute paths, directory paths, and glob patterns (expand at source time). See Path Specification for details.

# Examples
CONTEXT=(docs/notes.md)                    # Relative file
CONTEXT=(/tmp/shared/reference.pdf)        # Absolute file
CONTEXT=(data/)                            # Directory (non-recursive)
CONTEXT=(data/*.csv notes/**/*.md)         # Glob patterns
INPUT=(/external/data.csv local-report.md) # Mixed paths

CLI Flags¶

Flag	Config Variable	Example
`--profile`	`PROFILE`	`--profile deep`
`--model`	`MODEL`	`--model claude-opus-4-5`
`--enable-thinking`	`ENABLE_THINKING`	`--enable-thinking`
`--thinking-budget`	`THINKING_BUDGET`	`--thinking-budget 15000`
`--effort`	`EFFORT`	`--effort medium`
`--temperature`	`TEMPERATURE`	`--temperature 0.5`
`--max-tokens`	`MAX_TOKENS`	`--max-tokens 8192`
`--system`	`SYSTEM_PROMPTS`	`--system base,research`
`--format`	`OUTPUT_FORMAT`	`--format json`
`-in/--input`	`INPUT`	`-in data.csv`
`-cx/--context`	`CONTEXT`	`-cx notes.md`
`--depends-on`	`DEPENDS_ON`	`--depends-on preprocessing`
`--export`	`EXPORT_PATH`	`--export reports/out.md`

Viewing Configuration¶

wfw config              # Project configuration
wfw config analysis     # Workflow configuration

Example output:

Configuration Paths:
  Global:     ~/.config/wireflow/config                    [✓]
  Project:    ~/project/.workflow/config                   [✓]
  Workflow:   ~/project/.workflow/run/analysis/config      [✓]

Effective Configuration:
  MODEL = claude-opus-4                                    [project]
  TEMPERATURE = 0.3                                        [workflow]
  MAX_TOKENS = 8192                                        [global]
  SYSTEM_PROMPTS = (base research statistics)              [workflow]

Source labels: [builtin], [global], [ancestor], [project], [workflow], [cli], [env]

Pass-Through Inheritance¶

Leave values empty to inherit from parent levels:

# .workflow/config (project)
MODEL=claude-opus-4
TEMPERATURE=          # Inherit from global

# .workflow/run/analysis/config (workflow)
MODEL=                # Inherit from project (claude-opus-4)
TEMPERATURE=0.3       # Override for this workflow

Override Patterns¶

Per-Workflow Overrides¶

# .workflow/run/exploratory/config
TEMPERATURE=0.9
SYSTEM_PROMPTS=(base creative)

# .workflow/run/analysis/config
TEMPERATURE=0.3
SYSTEM_PROMPTS=(base research stats)

CLI Experiments¶

wfw run analysis --profile deep --enable-thinking
wfw run analysis --temperature 0.5 --model claude-opus-4-5

Best Practices¶

Do:

Use global config for personal defaults
Use project config for project-wide settings
Use workflow config for context and task-specific settings
Use CLI flags for experiments
Leave values empty to enable inheritance
Use array append (+=) to build on parent values

Don't:

Set the same value at multiple levels
Put sensitive data in project configs (use global or env)
Override everything at every level

Parameter Guidelines¶

Temperature	Use Case
0.0-0.4	Technical analysis, data processing
0.5-0.7	Balanced tasks, general writing
0.8-1.0	Creative writing, brainstorming

Profile	Model	Use Case
`fast`	Haiku	Quick iterations, simple tasks
`balanced`	Sonnet	General use (default)
`deep`	Opus	Complex reasoning

← Back to Execution Modes