Principle:Promptfoo Promptfoo Environment Configuration
| Knowledge Sources | |
|---|---|
| Domains | Configuration, Runtime |
| Last Updated | 2026-02-14 07:45 GMT |
Overview
Principle governing centralized, type-safe access to runtime configuration through environment variables, global config files, CLI state, and application constants.
Description
Environment Configuration defines how promptfoo reads and manages runtime configuration from multiple sources: environment variables (with typed accessors), persistent global config files (~/.promptfoo/promptfoo.yaml), mutable CLI state (for cross-module coordination), and compile-time/static constants. The principle mandates that environment variable access is always type-checked, that defaults are specified at the access site, and that provider-specific overrides are supported via the EnvOverrides mechanism.
Usage
Apply this principle when adding new configuration parameters. All environment variables must be registered in the EnvVars type, accessed through the typed getters, and documented with their default values.
Theoretical Basis
The configuration system implements a Layered Configuration Pattern with four layers (in precedence order):
- Provider overrides (EnvOverrides object) — highest priority
- Environment variables (process.env) — runtime overrides
- Global config file (~/.promptfoo/promptfoo.yaml) — persistent user preferences
- Compile-time constants (constants.ts, version.ts) — built-in defaults
The typed accessor functions (getEnvString, getEnvBool, etc.) implement the Encapsulation Pattern by hiding the raw process.env access behind a type-safe API.