Cloud mode vs local mode

Overview

PDD commands can run either in cloud mode or local mode. Cloud mode is the default and requires no API key management. Local mode uses the --local flag and requires you to provide API keys for one or more LLM providers.

Cloud mode (default)

GitHub SSO authentication. No API keys needed. Access to powerful models with automatic selection, cost optimization, and shared grounding from the PDD community.

Local mode (--local)

API keys required per provider. Uses LiteLLM to route to OpenAI, Anthropic, Google, or any supported provider. Full control over model selection.

Cloud mode

Cloud mode is the default for all PDD commands. It provides:

No need to manage API keys locally
Access to more powerful models
Shared examples and improvements across the PDD community
Automatic updates and improvements
Better cost optimization

Authentication flow

Cloud mode uses GitHub Single Sign-On (SSO) for authentication.

Trigger authentication

On first use of a cloud command, PDD automatically opens your default browser to the GitHub login page.

Return to terminal

Once authorized, return to your terminal. PDD resumes the command automatically.

Token stored locally

The authentication token is securely stored locally and automatically refreshed as needed. You will not need to re-authenticate on subsequent runs.

You can also manage authentication explicitly:

pdd auth

Automated grounding

In cloud mode, PDD uses Automated Grounding to prevent implementation drift. When you run pdd generate, the system:

Embeds your prompt into a vector
Searches for similar prompts in the cloud database (cosine similarity)
Auto-injects the closest (prompt, code) pair as a few-shot example

This is automatic — you do not configure it. On re-generation of an established module, your prior successful generation is typically the closest match, stabilizing the output over time.

Local users without cloud access must be more explicit in prompts — include structural guidance and explicit examples via <include>. Use a shared preamble for coding style. The minimal prompt guidance in the prompting guide assumes cloud access.

Local mode

Use the --local flag to run commands without cloud connectivity. Local mode uses LiteLLM to route requests to supported providers.

pdd --local sync factorial_calculator
pdd --local generate prompts/calculator_python.prompt

API key setup

Set environment variables for the providers you want to use:

export OPENAI_API_KEY=your_api_key_here

Add these to your .bashrc, .zshrc, or equivalent shell profile for persistence. When keys are missing, PDD prompts for them interactively and securely stores them in your local .env file.

pdd setup scans for API keys across .env, ~/.pdd/api-env.*, and the shell environment. Run it after installation to configure keys, select models, and test connectivity:

pdd setup

LiteLLM integration

Local mode uses LiteLLM (version 1.75.5 or higher) which provides:

Support for multiple model providers: OpenAI, Anthropic, Google/Vertex AI, and more
Automatic model selection based on strength settings
Response caching for improved performance
Smart token usage tracking and cost estimation

LiteLLM model identifiers typically follow the format provider/model_name:

openai/gpt-4
anthropic/claude-3-opus-20240229
gemini/gemini-1.5-pro

For the full list of supported providers and model identifiers, see the LiteLLM model list.

Model configuration

PDD selects models using a CSV configuration file (llm_model.csv). This file is loaded from the first location that exists, in order of precedence:

Precedence	Location	Description
1 (highest)	`~/.pdd/llm_model.csv`	User-specific configuration
2	`<PROJECT_ROOT>/.pdd/llm_model.csv`	Project-specific configuration
3 (lowest)	Bundled with PDD	Default fallback

CSV columns

Column	Description
`provider`	LLM provider (e.g., `openai`, `anthropic`, `google`)
`model`	LiteLLM model identifier (e.g., `gpt-4`, `claude-3-opus-20240229`)
`input`	Cost per million input tokens (USD)
`output`	Cost per million output tokens (USD)
`coding_arena_elo`	ELO rating for coding ability — used for `--strength` selection
`api_key`	Environment variable name for the required API key
`structured_output`	Whether the model supports structured JSON output
`reasoning_type`	Reasoning capability: `none`, `budget`, or `effort`

The bundled CSV includes top models with ELO ≥ 1400 across all LiteLLM-supported providers. For an up-to-date reference, see pdd/data/llm_model.csv in the repository.

LLM strength

The --strength flag controls which model tier is selected based on ELO rating. It applies globally to any command:

pdd --strength 1.0 sync factorial_calculator   # Most powerful model
pdd --strength 0.0 sync factorial_calculator   # Cheapest available model
pdd --strength 0.5 sync factorial_calculator   # Default (base model)

Value	Behavior
`0.0`	Cheapest available model (lowest ELO among available keys)
`0.5`	Default base model
`1.0`	Most powerful model (highest ELO rating)

Values between 0.0 and 1.0 select proportionally within the available model range. PDD filters the model list to only those for which you have a valid API key, then selects by ELO position within that filtered set.

LLM reasoning allocation

The --time flag controls the reasoning allocation for models that support extended reasoning capabilities (e.g., models with reasoning tokens or discrete effort levels):

pdd --time 1.0 sync factorial_calculator   # Maximum reasoning
pdd --time 0.0 sync factorial_calculator   # Minimum reasoning
pdd --time 0.25 sync factorial_calculator  # Default

Value	Behavior
`0.0`	Minimum reasoning allocation
`0.25`	Default
`1.0`	Maximum available reasoning tokens or highest effort level

For models with specific reasoning token limits (e.g., 64k tokens), 1.0 utilizes the maximum. For models with discrete effort levels, 1.0 corresponds to the highest effort level. Values between 0.0 and 1.0 scale proportionally.

The --time flag only affects models that have a reasoning_type of budget or effort in llm_model.csv. For models with reasoning_type: none, the flag has no effect.

Additional model controls

Temperature (--temperature)

Controls the randomness of model output. Default is 0.0 for deterministic, reproducible generation. Higher values increase diversity but may produce less coherent results.

pdd --temperature 0.0 sync factorial_calculator  # Deterministic (default)
pdd --temperature 0.7 sync factorial_calculator  # More varied output

Cost tracking (--output-cost)

Enable cost tracking and write usage details to a CSV file. Tracks timestamp, model, command, cost (USD), input files, and output files for each operation.

pdd --output-cost costs.csv sync factorial_calculator

Set PDD_OUTPUT_COST_PATH to configure a default output path.

Verbose output (--verbose)

Includes token count and context window usage for each LLM call. Useful for diagnosing context size issues or optimizing prompt efficiency.

pdd --verbose sync factorial_calculator

Budget limits (--budget)

Set a maximum total cost for the entire operation. PDD stops before exceeding the budget.

pdd --force sync --budget 5.0 factorial_calculator

Choosing between cloud and local

Use cloud mode when
Use local mode when

You want zero API key management
You want access to the most powerful models without provider accounts
You want automated grounding from the PDD community
You are getting started with PDD for the first time

Get Started

Core Concepts

Guides

Troubleshooting

Overview

Cloud mode (default)

Local mode (--local)

Cloud mode

Authentication flow

Automated grounding

Local mode

API key setup

LiteLLM integration

Model configuration

CSV columns

LLM strength

LLM reasoning allocation

Additional model controls

Choosing between cloud and local

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Troubleshooting

​Overview

Cloud mode (default)

Local mode (--local)

​Cloud mode

​Authentication flow

​Automated grounding

​Local mode

​API key setup

​LiteLLM integration

​Model configuration

​CSV columns

​LLM strength

​LLM reasoning allocation

​Additional model controls

​Choosing between cloud and local

Build docs developers (and LLMs) love

Overview

Cloud mode

Authentication flow

Automated grounding

Local mode

API key setup

LiteLLM integration

Model configuration

CSV columns

LLM strength

LLM reasoning allocation

Additional model controls

Choosing between cloud and local