Specification: Configuration Settings Layer

Objective

Centralise all runtime configuration (CLI arguments, environment variables, .env files, defaults) so that the rest of the application can rely on a single read-only settings object. This layer has no dependency on network or rendering code.

1. Sources & Precedence

  1. Command-line arguments – highest priority.

  2. Environment variables – fallback when corresponding CLI arg is null.

  3. .env file – loaded from current working directory if present.

  4. Hard-coded defaults – used when neither CLI, environment, nor .env provide a value.

Precedence is evaluated per setting key, not all-or-nothing.

2. Supported Settings Keys

Key

Default

Env Var

CLI Flag

Notes

gitlab_host

(required)

GITLAB_HOST

--gitlab-host

Base URL of GitLab instance.

group_api_key

none

GROUP_API_KEY

--group-api-key

Exactly one key or a JSON-List of keys. Stored as list of strings.

debug

false

DEBUG

--debug

Enables verbose logging.

display_shared

false

DISPLAY_SHARED

--display-shared

Includes shared projects in output when true.

table_config

table_config.yaml

TABLE_CONFIG

--table-config

Path to YAML file with column definitions (see Table Rendering & UI).

todo_keywords

["status", "todo", "stand", "fortschritt", "offen", "geplant"]

TODO_KEYWORDS

--todo-keywords

JSON-List with strings of keywords.

log_level

INFO

LOG_LEVEL

--log-level

Root logger level.

api_retry_count

3

API_RETRY_COUNT

--api-retry-count

Max retries for API client.

api_retry_backoff

1.0

API_RETRY_BACKOFF

--api-retry-backoff

Seconds added per retry attempt (linear).

3. Parsing Rules

  • Boolean CLI Flags are either present (=true) or omitted (=false, the default).

  • Boolean env vars accept true/false, 1/0, yes/no (case-insensitive).

  • Integer/float settings validate numeric input; invalid values raise configuration error at startup.

  • File-path settings must point to readable files; resolved relative to the current working directory.

  • CLI value parsing:

    • List fields accept JSON arrays or a single strings

    • Single values are automatically converted to single-item lists

    • Numeric fields are automatically converted from strings

    • Environment variables are temporarily unset when CLI values override them

  • Environment variable preprocessing:

    • List fields (group_api_key, todo_keywords) accept JSON arrays or a single string

    • Single values are automatically converted to single-item lists

    • Invalid JSON (if not a single string) raises an error and aborts the program.

  • Validation behavior:

    • File existence validation shows warnings instead of errors for missing files and prints the fallback-values in the INFO-Log

    • Numeric fields must be non-negative (api_retry_count, api_retry_backoff)

    • Invalid values raise configuration errors with descriptive messages and abort the program.

4. Runtime Behaviour

  • Settings are evaluated once at process start and exposed as immutable object(s).

  • Callers use helper class methods:

    • current() → load from environment only.

    • from_args(parsed_args) → merge CLI→env→defaults precedence.

    • override(kwargs) → return new Settings instance with overridden values.

  • No part of the application may modify settings after creation.

5. Non-Goals

  • Does not implement command-line parsing itself; relies on an external parser to create a namespace passed to from_args.

  • Any dynamic reloading or hot-update of environment variables is out of scope.

6. Implementation Notes

  • Uses Pydantic Settings for type safety and validation

  • Ignores unknown fields (extra="ignore")

  • Provides automatic type conversion and validation