config

Documentation

Overview

Package config provides configuration management for the CLI. It supports loading configuration from: - A YAML file at ~/.config/<cli-name>/config.yaml - Environment variables with a configurable prefix - OS keychain (for security credentials, when available) Priority: CLI flags > environment variables > OS keychain > config file

Index

• Constants
• func DeleteKeyringValue(key string) error
• func GetConfigPath() string
• func GetConfigValue(key string) string
• func GetEnvValue(key string) string
• func GetKeyringValue(key string) string
• func GetString(key string) string
• func Init(name, prefix string) error
• func KeyringAvailable() bool
• func Reset()
• func ResetKeyring()
• func ResolveCredential(cmd *cobra.Command, flagName string) (value, source string)
• func ResolveSecurityCredential(cmd *cobra.Command, flagName string) (value, source string)
• func SaveConfig(c *Config) error
• func SetKeyringBackend(b KeyringBackend)
• func SetKeyringValue(key, value string) error
• type Config
  • func GetConfig() *Config
• type KeyringBackend
• type SecurityConfig

Constants

const ConfigVersion = 1

ConfigVersion is the current config file schema version. Bump this when making breaking changes to the config format.

Functions

func DeleteKeyringValue

func DeleteKeyringValue(key string) error

DeleteKeyringValue removes a credential from the OS keychain.

func GetConfigPath

func GetConfigPath() string

GetConfigPath returns the path to the configuration file.

func GetConfigValue

func GetConfigValue(key string) string

GetConfigValue returns the config file value for a flag name, or "".

func GetEnvValue

func GetEnvValue(key string) string

GetEnvValue returns the environment variable value for a flag name, or "".

func GetKeyringValue

func GetKeyringValue(key string) string

GetKeyringValue retrieves a credential from the OS keychain. Returns "" if keyring is unavailable or key is not found.

func GetString

func GetString(key string) string

GetString returns a configuration value with priority: env var > config file. The key should be the kebab-case flag name (e.g., "api-key", "bearer-token"). CLI flags take highest priority and should be checked by the caller before calling this.

func Init

func Init(name, prefix string) error

Init loads configuration idempotently. It should be called during CLI initialization with the CLI name and environment variable prefix. Returns nil for missing config file, error for malformed YAML. Subsequent calls are no-ops unless Reset is called first.

func KeyringAvailable

func KeyringAvailable() bool

KeyringAvailable returns whether the OS keychain is accessible. Useful for configure command to decide where to store secrets.

func Reset

func Reset()

Reset clears all configuration state, allowing Init to be called again. This is intended for use in tests to support re-initialization between test cases.

func ResetKeyring

func ResetKeyring()

ResetKeyring clears the cached keyring availability state and restores the default backend. Used in tests to re-probe keyring availability.

func ResolveCredential

func ResolveCredential(cmd *cobra.Command, flagName string) (value, source string)

ResolveCredential resolves a credential value using the priority chain: flag > env var > config file. Returns the value and its source ("flag", "env", "config", or "unset"). Used for global parameters. For security credentials, use ResolveSecurityCredential which includes the OS keychain tier.

func ResolveSecurityCredential

func ResolveSecurityCredential(cmd *cobra.Command, flagName string) (value, source string)

ResolveSecurityCredential resolves a security credential using the priority chain: flag > env var > OS keychain > config file. Returns the value and its source ("flag", "env", "keyring", "config", or "unset"). This is used for security fields (tokens, API keys, passwords). For global parameters, use ResolveCredential which skips the keyring tier.

func SaveConfig

func SaveConfig(c *Config) error

SaveConfig saves the configuration to the config file. Creates the config directory if it doesn't exist.

func SetKeyringBackend

func SetKeyringBackend(b KeyringBackend)

SetKeyringBackend replaces the keyring backend (for testing).

func SetKeyringValue

func SetKeyringValue(key, value string) error

SetKeyringValue stores a credential in the OS keychain. Returns an error if the keyring is unavailable.

Types

type Config

type Config struct {
	Version      int            `yaml:"version,omitempty"`
	Security     SecurityConfig `yaml:"security,omitempty"`
	OutputFormat string         `yaml:"output_format,omitempty"`
	Timeout      string         `yaml:"timeout,omitempty"`
}

Config holds the CLI configuration values. Security credentials and other settings are populated from the config file and can be overridden by environment variables or CLI flags.

func GetConfig

func GetConfig() *Config

GetConfig returns the current configuration. Returns nil if Init has not been called.

type KeyringBackend

type KeyringBackend interface {
	Get(service, key string) (string, error)
	Set(service, key, value string) error
	Delete(service, key string) error
}

KeyringBackend abstracts keyring operations for testability.

type SecurityConfig

type SecurityConfig struct {
	ApiKeyAuth string `yaml:"api_key_auth,omitempty"`
}

SecurityConfig holds authentication credentials.