Improve configuration file discovery and support global config

Improve configuration file discovery and support global config

Summary

The OpenFeature CLI currently only looks for a single hidden config file (.openfeature) in the current working directory. This proposal improves config file naming, discovery, and hierarchy — inspired by mise and aligned with the .config/ directory proposal.

Motivation

• Discoverability: Hidden-only config is easy to miss for new users.
• Monorepo support: Only cwd is searched — running from a subdirectory fails to find the config.
• No global config: Settings like provider and authToken must be duplicated across every repo.
• CI/CD flexibility: No environment variable to override the config path.
• Project root clutter: The .config/ directory proposal is gaining traction as a standard place for tool configs.

Proposal

1. Support multiple config file names and locations

Like mise (which supports mise.toml, .mise.toml, .mise/config.toml, .config/mise.toml, .config/mise/config.toml), support both visible and hidden variants. First match wins:

File Name	Description
.config/openfeature.yaml	.config/ directory convention — keeps root clean
.config/openfeature/config.yaml	Nested .config/ variant — when config grows to multiple files
openfeature.yaml	Visible flat file — simplest, most discoverable
openfeature.json	Visible flat file, JSON variant
.openfeature.yaml	Hidden flat file
.openfeature.json	Hidden flat file, JSON variant
.openfeature/config.yaml	Hidden tool directory

Names follow the .config/ directory proposal conventions: explicit tool name, no .config suffix, format extension required, lowercase.

The init command should default to openfeature.yaml but accept a --config flag. If a .config/ directory already exists, init could prompt the user to place the config there instead.

2. Walk parent directories

Search from cwd up through parent directories, stopping at the repo root (.git) or filesystem root — standard behavior in mise, ESLint, and Prettier. This enables running commands from any subdirectory in a monorepo.

3. Global config at ~/.config/openfeature/config.yaml

Following the XDG Base Directory Specification, support a global user-level config. Respect $XDG_CONFIG_HOME when set, fall back to ~/.config/ otherwise.

Especially valuable for provider and authToken — configure once, use across all repos.

4. OPENFEATURE_CONFIG environment variable

An explicit config file path that takes precedence over automatic discovery. When set, the parent walk and global config are skipped. Essential for CI/CD pipelines.

5. Local override files

Support openfeature.local.yaml (and .config/openfeature.local.yaml) as machine-specific overrides loaded after the project config. Users should add these to .gitignore to keep secrets like authToken out of version control.

Precedence order

From highest to lowest priority:

1. CLI flags (--provider, --output, etc.)
2. OPENFEATURE_CONFIG env var (if set, skips 3-5)
3. Local override (openfeature.local.yaml / .config/openfeature.local.yaml) in nearest project directory
4. Project config (openfeature.yaml, .config/openfeature.yaml, .openfeature.yaml, etc.) in nearest project directory
5. ~/.config/openfeature/config.yaml (global)
6. Built-in defaults

Backwards compatibility

• Existing hidden file names (.openfeature.yaml, .openfeature.json) are fully supported as first-class candidates — no migration required.
• Visible and .config/ paths are checked first, so projects adopting newer conventions naturally take precedence.
• init should check for all supported file names before creating a new one.

Alternatives considered

• TOML format: YAML aligns better with the cloud-native ecosystem (Kubernetes, Docker Compose, GitHub Actions). TOML support is possible via Viper but not a priority.
• Flat files only: Doesn't address root clutter. .config/ is already supported by tools like mise.
• .config/ only: Hurts discoverability. Supporting both gives flexibility.

Related

• .config/ directory proposal and support tracker
• mise configuration docs
• XDG Base Directory Specification

Start by locating the CLI's current configuration discovery entry point and the init command. Map the existing behavior against the proposed search locations, parent walking, global and environment-based configuration, local overrides, and precedence rules; done means these cases are implemented without breaking the listed legacy filenames.