Profiles (profiles.yaml)

Profiles are a named bundle of field overrides stored in a YAML file (typically profiles.yaml). They are applied via Glazed middleware and are designed to be mid-precedence defaults:

• Profiles override defaults
• But can be overridden by config files, environment variables, and CLI flags

This makes profiles ideal for “environment presets” (dev/staging/prod), model presets, or organization defaults.

File format

The profile file is a YAML map:

• Top level: profile name
• Second level: section slug
• Third level: field name/value pairs for that section

Example:

development:
  api:
    base-url: http://localhost:8080
  auth:
    token: XXX

production:
  api:
    base-url: https://api.example.com

Default file location

Glazed’s profile middleware (middlewares.GatherFlagsFromProfiles) takes two paths and a default profile name:

• defaultProfileFile: the “well-known default” (commonly os.UserConfigDir() + "/<app>/profiles.yaml")
• profileFile: the actual file to load (can be overridden)
• defaultProfileName: the profile name treated as optional when the default file is missing (defaults to default)

Recommended convention for apps:

• ~/.config/<app>/profiles.yaml (via os.UserConfigDir() / $XDG_CONFIG_HOME)

Selecting a profile

In a Cobra CLI built with Glazed, profile selection typically comes from the ProfileSettings section:

• --profile <name>
• --profile-file <path>

and the matching environment variables (for app PINOCCHIO):

• PINOCCHIO_PROFILE=<name>
• PINOCCHIO_PROFILE_FILE=<path>

Enable the flags (important)

These flags only exist if you enable the ProfileSettings section when building your Cobra command:

command, err := cli.BuildCobraCommand(myCmd,
  cli.WithProfileSettingsSection(),
)

Without that section:

• Cobra won’t accept --profile/--profile-file
• Glazed won’t parse *_PROFILE/_PROFILE_FILE into profile-settings
• Config files won’t be able to set profile-settings either

Setting profile selection in config.yaml

Glazed config files are parsed in section-slug form:

<section-slug>:
  <param-name>: <value>

So profile selection in a config file must be expressed under the profile-settings section:

profile-settings:
  profile: mistral
  profile-file: /etc/pinocchio/profiles.yaml

Precedence (what overrides what)

When profiles are integrated into a full CLI pipeline, the effective precedence should be:

1. CLI flags (highest)
2. Environment variables
3. Config files (low → high overlays)
4. Profiles
5. Defaults (lowest)

This means:

• profiles are a convenient baseline
• but “local overrides” win (config/env/flags)

Error behavior

Recommended (and implemented in Glazed’s GatherFlagsFromProfiles):

• If profileFile does not exist and it is not the defaultProfileFile → error
• If profileFile is the defaultProfileFile:
  • profile == defaultProfileName → skip silently
  • profile != defaultProfileName → error (so APP_PROFILE=foobar fails fast)
• If the file exists but the named profile is missing:
  • profile != defaultProfileName → error
  • profile == defaultProfileName → skip silently

Avoiding “profile selection circularity” (important)

If you want profile selection (profile-settings.profile / profile-settings.profile-file) to be set via:

• env vars, and/or
• config files,

you cannot instantiate the profile middleware with “early” (default) values and expect it to pick up later overrides. The common fix is a bootstrap parse:

1. Parse profile-settings (and usually command-settings) from defaults + config + env + flags.
2. Instantiate GatherFlagsFromProfiles(...) using the resolved values.
3. Run the main middleware chain for all sections, with the profiles middleware inserted between defaults and higher-precedence sources.

If you need a concrete example, see topics/12-profiles-use-code.md and the Geppetto reference implementation.

Debugging

Use --print-parsed-fields to inspect parse provenance per field, including which values came from:

• defaults
• profiles (with metadata like { profile, profileFile })
• config (with metadata like { config_file, index })
• env
• cobra (flags)