Skip to main content
If you run pdd and see command not found, the CLI’s install directory is not on your PATH.Add ~/.local/bin to your PATH by running:
export PATH="$HOME/.local/bin:$PATH"
To make this permanent, add that line to your ~/.bashrc or ~/.zshrc, then reload your shell:
source ~/.zshrc   # or source ~/.bashrc
Verify the fix:
pdd --version
If you installed with uv, the pdd binary is placed in ~/.local/bin automatically. On Windows (Git Bash), use ~/.local/bin/pdd --version once to confirm, then add the directory to your PATH.
If pip install pdd-cli fails with a permission error, install with user-level permissions instead:
pip install --user pdd-cli
Alternatively, use uv, which installs into an isolated environment that does not require elevated permissions:
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install pdd-cli
PDD requires Xcode Command Line Tools on macOS for compiling Python dependencies. Install them with:
xcode-select --install
A dialog will prompt you to install the tools. After installation completes, retry your PDD installation.
Several macOS prerequisites (Python, uv, gh) are easiest to install via Homebrew. Install it with:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
After installation, add Homebrew to your PATH (required on Apple Silicon):
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile && eval "$(/opt/homebrew/bin/brew shellenv)"
Recent versions of macOS no longer ship with Python pre-installed. PDD requires Python 3.8 or higher.Check your current version:
python3 --version
If Python is missing or older than 3.8, install the latest Python 3 via Homebrew:
brew install python
If you have multiple Python versions installed, confirm python3 resolves to 3.8 or higher:
which python3 && python3 --version
Compilation failures with Permission denied typically mean Xcode Command Line Tools are not installed correctly or you lack write permissions to the installation directory.
  1. Ensure Xcode Command Line Tools are installed: 
    xcode-select --install
  2. Confirm the tools are active: 
    xcode-select -p
  3. If problems persist, reset the tool path: 
    sudo xcode-select --reset
If the curl installer for uv fails, install it through Homebrew instead:
brew install uv
Then install PDD:
uv tool install pdd-cli
If you have multiple Python installations (Homebrew, pyenv, system, Conda), python3 may resolve to the wrong version. Check which interpreter is active:
which python3 && python3 --version
PDD requires Python 3.8+. If the active interpreter is older, update your shell’s PATH so the correct Python comes first, or use uv (which manages its own Python version independently):
uv tool install pdd-cli
On Windows, PDD works best with uv (recommended), pipx, or a virtual environment.
irm https://astral.sh/uv/install.ps1 | iex
uv tool install pdd-cli
pdd --version
If pdd is not found, try ~/.local/bin/pdd --version. If that works, add ~/.local/bin to your PATH permanently.pdd setup fails with “Unsupported shell”If you see an error like Unsupported shell: or Error during 'setup' command, your SHELL environment variable is missing or invalid. Set it for the current session:
# PowerShell
$env:SHELL = "C:\Path\To\bash.exe"

rem CMD
set SHELL=C:\Path\To\bash.exe
To make the setting permanent, add SHELL to your user environment variables via Start → Edit the system environment variables → Environment Variables → New.
After updating PDD on Windows, use uv tool upgrade pdd-cli instead of re-running the install command if prompted to update.
After running pdd setup, the wizard writes your API keys to ~/.pdd/api-env.zsh (or api-env.bash). These keys are not automatically available in your current terminal session — you must source the file first:
source ~/.pdd/api-env.zsh   # zsh
# or
source ~/.pdd/api-env.bash  # bash
New terminal windows source this file automatically. If the wizard still does not detect your keys, confirm the file exists and contains the correct values:
cat ~/.pdd/api-env.zsh
Re-run pdd setup at any time to add keys, switch providers, or reconfigure models.
If you see a reminder banner about missing setup artifacts when running a PDD command, it means pdd setup has not been completed yet (or ~/.pdd/api-env does not exist).The banner is shown once as a reminder — the command you ran still executes if it can. To dismiss the banner permanently and complete your configuration:
pdd setup
The banner is automatically suppressed once ~/.pdd/api-env exists or when your project provides credentials via a .env file or a .pdd/ directory.
PDD requires at least one LLM provider API key. The relevant environment variables are:
ProviderEnvironment variable
OpenAIOPENAI_API_KEY
AnthropicANTHROPIC_API_KEY
Google GeminiGEMINI_API_KEY
Google (alternative)GOOGLE_API_KEY
PDD checks for keys in this order (highest priority first):
  1. Infisical secrets (when running via infisical run --)
  2. ~/.pdd/llm_model.csv (user-specific model registry)
  3. .env file in the project root
  4. Shell environment variables
To add keys manually, create or edit the .env file in your project root:
OPENAI_API_KEY=sk-your-key-here
# OR
ANTHROPIC_API_KEY=sk-ant-your-key-here
# OR
GEMINI_API_KEY=your-google-api-key
The easiest way to configure keys is through the setup wizard, which validates each key with a real test call:
pdd setup
If you have a ~/.pdd/llm_model.csv that references a rate-limited model, remove it to fall back to project defaults: rm -f ~/.pdd/llm_model.csv

Build docs developers (and LLMs) love

Get started for freeTalk to us