Load files and secrets

File references let one config read values from another file. This guide is for users who keep shared defaults, stage-specific settings, or secret placeholders outside the main config and want a predictable way to import whole files or selected fields.

This matters because production config rarely lives in one document. A service may use one YAML file for public defaults, one JSON file for generated values, and environment-specific overrides for deployment. File references keep that composition explicit and testable.

stage: ${opt:stage, "dev"}
settings: ${file(./settings.yml)}
databaseHost: ${file(./settings.yml):database.host}
databasePort: ${file(./settings.yml).database.port}
stageConfig: ${file(./config.${opt:stage}.json)}
fallbackValue: ${file(./missing.yml):name, "local"}

Aliases can keep long paths readable when a project has a stable config layout:

appName: ${file(@config/app.yml):name}
featureFlag: ${file(@data/features.json):checkout.enabled}

Secret values do not need to live in the committed config. A common local pattern is to keep the reference in config.yml and point it at a gitignored file:

database:
  password: ${file(./.secrets/local.yml):database.password}

.secrets/

That keeps the dependency visible without committing the value. If secrets live somewhere else, provide a custom variable source instead of a file reference. Custom variable sources can read from local stores such as the macOS Keychain or 1Password CLI, or from remote stores such as AWS Secrets Manager, GCP Secret Manager, Vault, or your own internal service.

Missing files can fail, use fallback values, or pass through when unknown refs are explicitly allowed. For exact source syntax, see variable sources. For root restrictions and safe-mode behavior, see safe inspection.