Skip to main content

​
Verbosity flags

PDD provides two flags to control how much output commands produce. --verbose increases output detail. When set, every LLM call includes:
  • Token count for the request and response
  • Context window usage as a percentage of the model’s limit
pdd --verbose sync factorial_calculator
--quiet suppresses all non-essential output for minimal terminal noise: 
pdd --quiet sync factorial_calculator
Both flags are global options and work with any PDD command.

​
Inspecting sync state with —dry-run

Use pdd sync --dry-run to inspect what sync would do without executing any operations or acquiring locks. This is safe to run even when another sync process is active. 
pdd sync --dry-run calculator
The dry run output includes:
  • Current file state and fingerprint comparisons
  • Decision reasoning (heuristic-based or LLM-powered)
  • Operation recommendations with confidence levels
  • Estimated costs for recommended operations
  • Lock status and potential conflicts
  • State management details
To see detailed LLM reasoning for complex multi-file change scenarios, combine --dry-run with --verbose: 
pdd --verbose sync --dry-run calculator
Use --dry-run first when sync behaves unexpectedly — it shows exactly what the state analysis determined without making any changes.

​
Core dump bundles

When something goes wrong and you want the PDD team to reproduce the issue, run the failing command with --core-dump: 
pdd --core-dump sync factorial_calculator
pdd --core-dump crash prompts/calc_python.prompt src/calc.py examples/run_calc.py crash_errors.log
When --core-dump is set, PDD captures:
  • The full CLI command and arguments
  • Relevant logs and internal trace information for the run
  • The prompt files involved
  • Generated code
  • Key metadata needed to replay the issue
At the end of the run, PDD prints the path to the bundle. Bundles are saved under .pdd/core_dumps/ in your project directory. Attach the bundle when opening a GitHub issue so maintainers can quickly reproduce and diagnose the problem.

​
Reporting a bug with report-core

The report-core command creates a GitHub issue from a core dump bundle, collecting the relevant files automatically. 
pdd report-core [OPTIONS] [CORE_FILE]
Arguments
  • CORE_FILE — path to a core dump file (e.g., .pdd/core_dumps/pdd-core-....json). If omitted, the most recent core dump is used.
Options
OptionDescription
--apiCreate the issue via the GitHub API instead of opening a browser. Enables automatic Gist creation.
--repo OWNER/REPOOverride the target repository. Defaults to promptdriven/pdd.
--description TEXT / -d TEXTA short description of what went wrong.

​
Authentication for —api

To use --api, PDD needs a GitHub token. It checks for credentials in this order:
  1. GitHub CLI — gh auth token (recommended)
  2. Environment variables — GITHUB_TOKEN or GH_TOKEN
  3. Legacy variable — PDD_GITHUB_TOKEN
The GitHub CLI method is simplest. If you have gh installed and authenticated, --api works without any additional setup.

​
API vs browser submission

Without --api, PDD opens your browser with a pre-filled issue form. Files are truncated to fit within URL length limits, so some context may be missing for large runs.Use this method if you are not authenticated with GitHub CLI and do not have a GITHUB_TOKEN available.
pdd report-core --description "crash command loop did not terminate"

​
Examples

# Report the most recent core dump via the GitHub API
pdd report-core --api

# Report a specific core dump with a description
pdd report-core --api -d "generate fails on parameterized prompt" .pdd/core_dumps/pdd-core-20260330.json

# Report to a fork instead of the main repo
pdd report-core --api --repo myorg/pdd-fork .pdd/core_dumps/pdd-core-20260330.json
Core dump bundles may contain prompt text and generated code from your project. Review the bundle before reporting if your prompts contain sensitive information.

Build docs developers (and LLMs) love

Get started for freeTalk to us