Module config 

Configuration and authentication management. Configuration and authentication for the ROMM client.

This module is deliberately independent of any particular frontend: both the TUI and the command-line subcommands share the same Config and AuthConfig types.

Configuration precedence

Configuration is layered per field. Lowest precedence wins first; higher layers override only the fields they set. There is no automatic .env file loading.

Layer 1 — built-in defaults

Examples: use_https = true, theme terminal, OS download directory when unset.

Layer 2 — config.json

User file at [user_config_json_path], written by romm-cli init, the TUI setup wizard, Settings, or auth login. Fills fields not set by higher layers.

Layer 3 — process environment

Overrides config.json per field in [load_config]. Includes API_BASE_URL, ROMM_ROMS_DIR / ROMM_DOWNLOAD_DIR, API_USE_HTTPS, auth vars (API_TOKEN, ROMM_TOKEN_FILE / API_TOKEN_FILE, etc.), ROMM_THEME, and path overrides (ROMM_CACHE_PATH, ROMM_OPENAPI_PATH, …).

Layer 4 — OS keyring

After env + JSON merge, secrets that are still placeholders (including [KEYRING_SECRET_PLACEHOLDER]) are resolved via the OS keyring (keyring crate, service romm-cli). On Windows the stored credential target is typically API_TOKEN.romm-cli, API_PASSWORD.romm-cli, or API_KEY.romm-cli. Missing entries are silent; other keyring errors are logged at warn (never with secret values). On save, a successful store is followed by read-back verification before writing the sentinel to JSON.

Layer 5 — command-specific CLI (runtime only)

Narrow exceptions on top of [load_config] for a single invocation (not global):

Command / flag	Effect
download -o / --output	Download directory for that run; ignores env and file
sync run --download-dir	Save download base; defaults to manifest parent, not save_sync.save_dir
init / auth login flags	Persist to config.json; effective on the next run unless env overrides

There are no global --url / --token flags on normal API commands; connection settings come from env + file + keyring via [load_config].

Structs

Config

High-level configuration for the romm-cli application.

ExtrasDefaults

Default checked state for categories in the TUI extras picker (when each row exists).

RomsLayoutConfig

Per-console ROM storage layout preferences.

SaveSyncConfig

Save sync preferences shared by CLI/TUI frontends.

TuiLayoutConfig

TUI panel layout preferences (library split and game detail cover width).

Enums

AuthConfig

Supported authentication modes for the RomM API.

Constants

DEFAULT_THEME_ID

Default TUI theme ID when none is configured.

GAME_DETAIL_COVER_PANEL_WIDTH_DEFAULT

Default game detail cover column width in terminal cells.

GAME_DETAIL_COVER_PANEL_WIDTH_MAX

Maximum game detail cover column width.

GAME_DETAIL_COVER_PANEL_WIDTH_MIN

Minimum game detail cover column width.

KEYRING_SECRET_PLACEHOLDER

Written to config.json when the real secret is stored in the OS keyring (persist_user_config).

LIBRARY_LEFT_PANEL_PERCENT_DEFAULT

Default library browse split: left pane width as a percentage.

LIBRARY_LEFT_PANEL_PERCENT_MAX

Maximum library left pane width (percent).

LIBRARY_LEFT_PANEL_PERCENT_MIN

Minimum library left pane width (percent).

Functions

auth_for_persist_merge

Auth to pass to persist_user_config when saving non-auth fields (e.g. TUI Settings).

default_theme_id

disk_has_unresolved_keyring_sentinel

Returns true when load_config has no resolved AuthConfig::Bearer (etc.) but config.json on disk still contains KEYRING_SECRET_PLACEHOLDER (OS keyring could not supply the secret).

is_keyring_placeholder

Returns true if s is the sentinel written to disk when the secret lives in the keyring.

keyring_get

Retrieve a secret from the OS keyring, returning None if not found or on error.

keyring_store

Store a secret in the OS keyring under the romm-cli service name.

load_config

Loads the merged configuration from the process environment, config.json, and the OS keyring.

normalize_romm_origin

Normalizes a RomM site URL by trimming whitespace, trailing slashes, and removing the /api suffix.

openapi_cache_path

Where the OpenAPI spec is cached (.../romm-cli/openapi.json).

persist_user_config

Persists the user configuration to config.json and stores secrets in the OS keyring.

read_user_config_json_from_disk

Reads config.json from disk only (no env merge, no keyring resolution). Used by the TUI setup wizard to detect <stored-in-keyring> placeholders.

reset_all_settings

Deletes the config.json file and clears the secrets from the OS keyring.

resolve_console_save_dir

Resolve the directory where save files for a console should be stored.

resolve_game_save_dir

Resolve the directory where a specific game’s saves should be downloaded.

resolved_save_dir

should_check_updates

Returns true if the application should check for updates on startup.

user_config_dir

Directory for user-level config (romm-cli under the OS config dir).

user_config_json_path

Path to the user-level config.json file (.../romm-cli/config.json).