内容摘录
PDD (Prompt-Driven Development) Command Line Interface
!PDD-CLI Version Discord
Introduction
PDD (Prompt-Driven Development) is a toolkit for AI-powered code generation and maintenance.
**Getting started is simple:**
This launches a web interface at localhost:9876 where you can:
Implement GitHub issues automatically
Generate and test code from prompts
Manage your PDD projects visually
<p align="center">
<img src="docs/videos/handpaint_demo.gif" alt="PDD Handpaint Demo" />
</p>
For CLI users, PDD also offers powerful **agentic commands** that implement GitHub issues automatically:
pdd change <issue-url> - Implement feature requests (12-step workflow)
pdd bug <issue-url> - Create failing tests for bugs
pdd fix <issue-url> - Fix the failing tests
pdd generate <issue-url> - Generate architecture.json from a PRD issue (11-step workflow)
pdd test <issue-url> - Generate UI tests from issue descriptions (9-step workflow)
For prompt-based workflows, the **sync** command automates the complete development cycle with intelligent decision-making, real-time visual feedback, and sophisticated state management.
Whitepaper
For a detailed explanation of the concepts, architecture, and benefits of Prompt-Driven Development, please refer to our full whitepaper. This document provides an in-depth look at the PDD philosophy, its advantages over traditional development, and includes benchmarks and case studies.
Read the Full Whitepaper with Benchmarks
Also see the Prompt‑Driven Development Doctrine for core principles and practices: docs/prompt-driven-development-doctrine.md
Installation
Prerequisites for macOS
On macOS, you'll need to install some prerequisites before installing PDD:
**Install Xcode Command Line Tools** (required for Python compilation):
**Install Homebrew** (recommended package manager for macOS):
After installation, add Homebrew to your PATH:
**Install Python** (if not already installed):
**Note**: Recent versions of macOS no longer ship with Python pre-installed. PDD requires Python 3.8 or higher. The brew install python command installs the latest Python 3 version.
Recommended Method: uv
We recommend installing PDD using the uv package manager for better dependency management and automatic environment configuration:
This installation method ensures:
Faster installations with optimized dependency resolution
Automatic environment setup without manual configuration
Proper handling of the PDD_PATH environment variable
Better isolation from other Python packages
The PDD CLI will be available immediately after installation without requiring any additional environment configuration.
Verify installation:
With the CLI on your PATH, continue with:
The command detects agentic CLI tools, scans for API keys, configures models, and seeds local configuration files.
If you postpone this step, the CLI detects the missing setup artifacts the first time you run another command and shows a reminder banner so you can complete it later (the banner is suppressed once ~/.pdd/api-env exists or when your project already provides credentials via .env or .pdd/).
Alternative: pip Installation
If you prefer using pip, you can install PDD with:
Advanced Installation Options
Virtual Environment Installation
Getting Started
Option 1: Web Interface (Recommended)
The easiest way to use PDD is through the web interface:
This opens a browser-based interface where you can:
**Run Commands**: Execute pdd change, pdd bug, pdd fix, pdd sync etc. visually
**Browse Files**: View and edit prompts, code, and tests in your project
**Remote Access**: Access your session from any browser via PDD Cloud (use --local-only to disable)
Option 2: Issue-Driven CLI
For CLI enthusiasts, implement GitHub issues directly:
**Prerequisites:**
**GitHub CLI** - Required for issue access:
**One Agentic CLI** - Required to run the workflows (install at least one):
**Claude Code**: npm install -g @anthropic-ai/claude-code (requires ANTHROPIC_API_KEY)
**Gemini CLI**: npm install -g @google/gemini-cli (requires GOOGLE_API_KEY or GEMINI_API_KEY)
**Codex CLI**: npm install -g @openai/codex (requires OPENAI_API_KEY)
**Usage:**
Option 3: Manual Prompt Workflow
For learning PDD fundamentals or working with existing prompt files:
See the Hello Example below for a step-by-step introduction.
---
🚀 Quickstart (Hello Example)
If you want to understand PDD fundamentals, follow this manual example to see it in action.
**Install prerequisites** (macOS/Linux):
**Clone repo**
**Set one API key** (choose your provider):
Post-Installation Setup (Required first step after installation)
Run the comprehensive setup wizard:
The setup wizard runs these steps:
Detects agentic CLI tools (Claude, Gemini, Codex) and offers installation and API key configuration if needed
Scans for API keys across .env, and ~/.pdd/api-env.*, and the shell environment; prompts to add one if none are found
Configures models from a reference CSV data/llm_model.csv of top models (ELO ≥ 1400) across all LiteLLM-supported providers based on your available keys
Optionally creates a .pddrc project config
Tests the first available model with a real LLM call
Prints a structured summary (CLIs, keys, models, test result)
The wizard can be re-run at any time to update keys, add providers, or reconfigure settings.
**Important:** After setup completes, source the API environment file so your keys take effect in the current terminal session:
New terminal windows will load keys automatically.
If you skip this step, the first regular pdd command you run will detect the missing setup files and print a reminder banner so you can finish onboarding later.
**Run Hello**:
✅ Expected output:
Cloud vs Local Execution
PDD commands can be run either in the cloud or locally. By default, all commands run in the cloud mode, which provides several advantages:
No need to manage API keys locally
Access to more powerful models
Shared examples and improvements across the PDD comm…