Skip to main content
pdd preprocess processes a prompt file and saves the expanded result. It resolves <include> directives, removes <pdd> comments, executes <shell> tags, fetches <web> URLs, and optionally doubles curly brackets. Use it to inspect exactly what the LLM will receive before running any generative command.

​
Usage

pdd [GLOBAL OPTIONS] preprocess [OPTIONS] PROMPT_FILE

​
Arguments

​
PROMPT_FILE
string
required
The prompt file to preprocess.

​
Options

​
--output
string
Where to save the preprocessed prompt file. Default: <basename>_<language>_preprocessed.prompt. Also reads from PDD_PREPROCESS_OUTPUT_PATH.
​
--xml
boolean
default:"false"
Insert XML delimiters for long or complex prompts to add structure. When set, the prompt is only preprocessed to insert XML delimiters — other directives are not expanded.
​
--recursive
boolean
default:"false"
Recursively preprocess all <include> directives found within included files, not just the top-level prompt.
​
--double
boolean
default:"false"
Double all single curly brackets (e.g., {x} becomes {{x}}). Already-doubled brackets are preserved. Useful when a prompt will be used as a Python format string downstream.
​
--exclude
string
Keys to exclude from curly bracket doubling when --double is set. Only applies when the entire contents of a {...} pair exactly match the excluded key. For example, --exclude model keeps {model} as-is but still doubles {model_name}.
​
--pdd-tags
boolean
default:"false"
Inject PDD metadata tags (<pdd-reason>, <pdd-interface>, <pdd-dependency>) from architecture.json into the prompt.

​
Supported directives

pdd preprocess expands the following XML-like tags in prompt files. Tags inside fenced code blocks (``` or ~~~) and inline backticks are left unchanged.
Embeds file content into the prompt. The file path is the tag body.
<include>./path/to/file.txt</include>
Optional attributes for selective extraction:
  • select= — Deterministic structural extraction. Supports def:foo, class:Bar, line ranges, headings, regex, and JSON/YAML paths. Composable with commas.
  • mode="interface" — Python only. Extracts signatures and docstrings with bodies replaced by ....
  • query= — LLM-powered semantic extraction, cached in .pdd/extracts/.
  • optional — A missing file resolves to an empty string instead of an error.
When both select= and query= are present, select= takes precedence (no LLM cost).
<include select="def:foo,class:Bar">src/utils.py</include>
<include select="class:Handler" mode="interface">src/api.py</include>
<include query="authentication flow">docs/api_reference.md</include>
<include optional>config/optional_settings.toml</include>
Marks content as a comment. Removed from the preprocessed output.
<pdd>This is a comment that won't appear in the output</pdd>
Executes a shell command and replaces the tag with its standard output.
<shell>ls -la</shell>
Fetches a web page and includes its Markdown-converted content.
<web>https://example.com</web>

​
Triple-backtick includes

In addition to XML tags, PDD supports embedding file content inside triple-backtick code blocks using angle brackets: 
```
<./path/to/file.txt>
```
This is processed recursively until no more angle bracket includes remain.

​
Curly bracket doubling

When --double is used:
  • Single curly brackets are doubled if not already doubled.
  • Already-doubled brackets are preserved.
  • Nested curly brackets are handled correctly.
  • Special handling is applied for JSON, JavaScript, TypeScript, and Python code blocks.
  • Multiline variables with curly brackets receive special treatment.
Use --exclude to protect specific variable names from doubling: 
# Keep {model} as-is, but still double {model_name}
pdd preprocess --double --exclude model my_prompt_python.prompt

​
Examples

# Basic preprocessing
pdd preprocess my_module_python.prompt

# Save to a specific location
pdd preprocess \
  --output preprocessed/my_module_python_preprocessed.prompt \
  my_module_python.prompt

# Recursive with curly bracket doubling, excluding specific keys
pdd preprocess \
  --output preprocessed/factorial_calculator_python_preprocessed.prompt \
  --recursive \
  --double \
  --exclude model,temperature \
  factorial_calculator_python.prompt
  • pdd auto-deps — Inserts <include> directives; use preprocess to verify they resolve correctly.
  • pdd generate — Calls preprocessing internally before sending content to the LLM.

Build docs developers (and LLMs) love

Get started for freeTalk to us