Skip to content
Back to skills

Config Files

ASecurity

Loading a binary's typed config from a YAML/JSON file — --config and the per-binary <BINARY>_CONFIG path variable, precedence, the override, what a missing or invalid file does, and how a root and a command config share one flat file.

  • 10 stars
  • 0 votes
  • 0 copies
  • 1 view
  • Added November 13, 2026
ai-agentsgoshellbashgitapi

Works with

  • api

Security analysis

A100/100

Scanned November 13, 2026

npx -y skills add reliant-labs/forge --skill config-files --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Config Files?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Config Files
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/reliant-labs-config-files/badge)](https://www.skillsdirectory.com/skills/reliant-labs-config-files)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: config-files
description: Loading a binary's typed config from a YAML/JSON file — --config and the per-binary <BINARY>_CONFIG path variable, precedence, the override, what a missing or invalid file does, and how a root and a command config share one flat file.
---

# Config files

Every config also loads from a file: `--config <path>` (`.yaml`, `.yml` or `.json`, keyed by the proto field names), or — when the flag is absent — the binary's OWN path variable, `<BINARY>_CONFIG`: `RELIANT_CONFIG` for `cmd/reliant`, `IDP_PROVISION_ONESHOT_CONFIG` for `cmd/idp-provision-oneshot`. A binary's root config and its command configs share it. The project-global `AppConfig`, bound to no binary, reads `<PROJECT>_CONFIG` (`config.ConfigPathEnv` in the generated `pkg/config`). Precedence is defaults < file < env < flags.

- The variable is per binary on purpose: one shared name would let a shell that sets it for one app make every other forge binary launched from that shell load a file written for a different schema and fail at startup.
- A path that is given but missing, unreadable or invalid fails startup, naming where it came from (`config file "/x.yaml" (from env RELIANT_CONFIG) does not exist`). No path given is not an error: the file layer is skipped. A variable set to `""` is unset, like every variable the loader reads.
- A key the file names sets that field outright, and every key it omits keeps its default. A list or map REPLACES the default, as an env var or flag does (`allowed_registries: []` clears a defaulted list); a zero value (`port: 0`, `enabled: false`) overrides it; a nested block takes only the leaves it names; `null` sets nothing. Durations are protojson strings in seconds (`timeout: 0.5s`), not Go durations.
- One file configures one PROCESS, and it is flat, like the process's flags and env vars: `app server api` reads its root config AND `ApiServerConfig` from the same file, each taking its own top-level keys.

  ```yaml
  # app server api --config api.yaml
  log: {level: debug}                 # AppConfig (root)
  grpc_port: 9090                     # ApiServerConfig (server api)
  ```

  A key that no config the command loads declares is an error naming them all (`unknown key "grcp_port": no config this command loads has such a field (ApiServerConfig, AppConfig)`), so a misspelling still fails — and so does a key only another process reads: `app server worker` refuses `grpc_port`. Give each process its own file. The configs a command loads are the ones registered on its path (`config.Register<Msg>Flags`).
- To answer to a different variable, call `forgeconfig.RegisterConfigFlag(root, "MY_APP_CONFIG")` (`forgeconfig` = `github.com/reliant-labs/forge/pkg/config`) on the binary's root command BEFORE `config.Register<Msg>Flags(root)`: the first `--config` registered on a command path names the variable for every load beneath it.

## Build-time defaults

Between the proto `default_value` and the file sits one more layer: values a BUILD carries. A release binary stamped with its environment's endpoints, while `go install` of the same source keeps the proto default:

```bash
go build -ldflags "-X 'example.com/app/pkg/config.BuildDefaults=APP_SERVER_URL=https://api.example.com&APP_REGION=eu'" ./cmd/app
```

`BuildDefaults` is one string in URL query form, keyed by each field's `env_var` (escape `&`, `=`, `+`, `%` or a space in a value with `url.QueryEscape`). Precedence: `default_value` < build default < file < env < flags. A key naming no config field of the binary, a `sensitive` field, a duplicate key, or a value that does not parse fails every `Load` naming the key — a stamp is a build defect, never silently ignored.

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.