tools-only Getting Started with PDD using a Free Gemini API Key
This example shows you how to set up Prompt-Driven Development (PDD) with a free Gemini API key and run the built-in Hello example.
Goal: By the end, you'll have PDD installed, Gemini configured, and
pdd syncrunning on the Hello example.
1. Install the pdd CLI
PDD works best in an isolated environment. You can pick one of these methods:
Option A — uv (recommended)
macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install pdd-cli
pdd --version
Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex
uv tool install pdd-cli
pdd --version
Option B — pipx
python -m pip install --user pipx
python -m pipx ensurepath
pipx install pdd-cli
pdd --version
Option C — venv
python -m venv ~/.venvs/pdd
source ~/.venvs/pdd/bin/activate # Windows: %USERPROFILE%\venvs\pdd\Scripts\activate
pip install --upgrade pip
pip install pdd-cli
pdd --version
✅ If you see pdd, version X.Y.Z, installation worked.
⚠️ If pdd isn’t found, try ~/.local/bin/pdd --version once, then add ~/.local/bin to your PATH.
2. Run the guided setup
Right after installation, let PDD bootstrap its configuration:
pdd setup
During the wizard:
- Choose Install tab completion if you want shell helpers.
- Pick Google Gemini when asked which providers to configure.
- Paste your Gemini API key when prompted (you can create it in the next step if you haven’t already).
The wizard writes your credentials to ~/.pdd/api-env, seeds ~/.pdd/llm_model.csv with Gemini entries, and reminds you to reload your shell (source ~/.zshrc, etc.) so completion and env hooks load.
If you prefer to configure everything manually—or you’re on an offline machine—skip the wizard and follow the manual instructions below.
3. Clone the repo
git clone https://github.com/promptdriven/pdd.git
cd pdd/examples/hello
4. Configure your Google API Key (manual setup)
If you already pasted the key into pdd setup, you can skip this section. Otherwise:
- Go to Google AI Studio.
- Log in with your Google account.
- Click Create API key.
- Copy the key.
Students: The Gemini API is free for everyone, but university students get higher rate limits (60 requests/min, 300K tokens/day) extended through June 2026. You can also claim 1 year of Google AI Pro free (sign up by Jan 31, 2026) for additional perks like NotebookLM and 2TB storage.
macOS/Linux (bash/zsh)
export GEMINI_API_KEY="PASTE_YOUR_KEY_HERE"
Windows (PowerShell)
setx GEMINI_API_KEY "PASTE_YOUR_KEY_HERE"
Then close and reopen your terminal.
Check:
echo $GEMINI_API_KEY # macOS/Linux
echo $Env:GEMINI_API_KEY # Windows
5. Create ~/.pdd/llm_model.csv (manual setup)
The setup wizard already adds a Gemini row. Only follow this step if you skipped the wizard or want to edit the file by hand. Add Gemini rows so PDD knows how to call the Google AI Studio models:
provider,model,input,output,coding_arena_elo,base_url,api_key,max_reasoning_tokens,structured_output,reasoning_type
gemini,gemini/gemini-2.5-pro,0,0,0,,GEMINI_API_KEY,0,True,none
Make sure the file exists:
head -2 ~/.pdd/llm_model.csv
6. Output locations (optional, skip for this quickstart)
By default, PDD writes generated files next to your source code. For real projects, you can set these environment variables to organize outputs:
export PDD_TEST_OUTPUT_PATH=tests
export PDD_EXAMPLE_OUTPUT_PATH=examples
With these set, PDD will place outputs like so:
- Examples →
examples/<module>/... - Tests →
tests/<module>/...
Note: For the Hello example below, leave these unset so files generate in the current directory.
7. Validate Your Setup
Before using the main workflow, verify your configuration works by running a quick generate:
From pdd/examples/hello:
pdd generate hello_python.prompt
If this succeeds, your API key and model configuration are working correctly.
8. Use Sync (Primary Workflow)
The pdd sync command is the primary way to work with PDD. It generates code, tests, and examples for a module, keeping everything in sync:
pdd sync hello
Use --force to regenerate even if files already exist:
pdd --force sync hello
After syncing, run the generated example:
python hello.py
If the generated hello.py is minimal (no __main__ block), run it interactively:
python -i hello.py
>>> hello()
hello
9. What if nothing prints?
Sometimes the generated file only defines the function (e.g., def hello(): print("hello")) but doesn’t include the standard Python entry point:
if __name__ == "__main__":
hello()
In that case you have two options:
Option A — Run interactively
python -i hello.py
>>> hello()
hello
Option B — Add a main guard
Append this to the bottom of the file:
if __name__ == "__main__":
hello()
Then re-run:
python hello.py
# output:
hello
10. Try the Web Interface with pdd connect
PDD also provides a web-based interface for generating code and managing projects. Start the local server:
pdd connect
This launches a FastAPI server on http://localhost:9876 and opens your browser automatically.
From the web interface you can:
- Generate code from prompts visually
- Implement GitHub issues automatically
- Manage PDD projects through a GUI
Common options:
# Use a different port
pdd connect --port 8000
# Don't auto-open the browser
pdd connect --no-browser
# View API docs at http://localhost:9876/docs
Press Ctrl+C to stop the server when you're done.
✅ That's it! You've installed PDD, configured Gemini, and used pdd sync to generate your first module.