zenmux-usage-cli/openspec/changes/archive/2026-04-22-build-usage-cli/specs/account-config/spec.md

ADDED Requirements

Requirement: Load accounts from a YAML config file

The CLI SHALL read a YAML config file containing one or more ZenMux accounts. The default path SHALL be $XDG_CONFIG_HOME/zenmux-usage/config.yaml, falling back to ~/.config/zenmux-usage/config.yaml when XDG_CONFIG_HOME is unset. The schema MUST be:

accounts:
  - name: <string, required, unique>
    api_key: <string, required, non-empty>

The CLI SHALL validate that accounts has at least one entry, that every entry has a non-empty name and api_key, and that name values are unique. Unknown top-level or per-account fields MUST produce a single-line stderr warning but MUST NOT fail the load.

Scenario: Valid config with multiple accounts

• WHEN the default config file contains two accounts personal and work, each with a non-empty api_key
• THEN the CLI loads both accounts in file order and exposes them to the fetch layer

Scenario: Duplicate account names

• WHEN the config file contains two accounts both named personal
• THEN the CLI exits with code 7 and writes a message identifying the duplicate name to stderr

Scenario: Missing required field

• WHEN an account in the config has no api_key or an empty api_key
• THEN the CLI exits with code 7 and writes a message identifying the offending account entry

Scenario: Empty accounts list

• WHEN the config file contains accounts: [] or no accounts key
• THEN the CLI exits with code 7 and writes a message to stderr

Scenario: Unknown top-level field is ignored

• WHEN the config file contains an unrecognized top-level key such as notifications:
• THEN the CLI still loads successfully and writes a one-line stderr warning naming the unknown key

Requirement: Override config path with flag

The CLI SHALL honor a --config <path> flag that overrides the default config file path. If the explicit path does not exist or cannot be read, the CLI SHALL exit with code 3.

Scenario: Explicit config path

• WHEN the user runs zenmux-usage --config ./my-config.yaml
• THEN the CLI reads ./my-config.yaml instead of the default location

Scenario: Explicit config path missing

• WHEN the user runs zenmux-usage --config ./nope.yaml and that file does not exist
• THEN the CLI exits with code 3 and writes a message to stderr

Requirement: Resolve which account(s) to fetch

The CLI SHALL resolve the set of accounts to fetch in this precedence:

1. --api-key <key> set → a single synthetic account named cli using that key; config is not loaded.
2. Otherwise, config is loaded (from --config or the default path). If --account <name> is provided, the set is filtered to that single matching account. If --account is not provided, the set is every account in the config, in file order.
3. If no config file exists at the resolved path AND ZENMUX_MANAGEMENT_API_KEY is set, the CLI SHALL use a single synthetic account named env with that key.
4. If none of the above yields at least one account, the CLI SHALL exit with code 3 and print a message directing the user to create the config file.

Scenario: --api-key beats config

• WHEN a valid config file exists and the user runs zenmux-usage --api-key sk-ad-hoc
• THEN the CLI does not read the config file and fetches using only the cli synthetic account
• AND the outgoing request uses Authorization: Bearer sk-ad-hoc

Scenario: --account filters to a single entry

• WHEN the config has accounts personal and work, and the user runs zenmux-usage --account work
• THEN only the work account is fetched and rendered

Scenario: --account name not found

• WHEN the config has accounts personal and work, and the user runs zenmux-usage --account missing
• THEN the CLI exits with code 2 and writes a message listing the available account names to stderr

Scenario: No config, env var fallback

• WHEN no config file exists at the default path and ZENMUX_MANAGEMENT_API_KEY=env-key is set
• THEN the CLI fetches a single synthetic account named env using env-key

Scenario: No config, no env

• WHEN no config file exists at the default path and no ZENMUX_MANAGEMENT_API_KEY env var is set, and no --api-key flag is passed
• THEN the CLI exits with code 3 and writes a message pointing the user at the default config path

Requirement: Warn on world-readable config permissions

On POSIX systems, if the resolved config file has group- or world-readable mode bits set (i.e. mode has any of 0044 set), the CLI SHALL write a one-line stderr warning advising the user to run chmod 600 on the file. The warning MUST NOT be fatal and MUST NOT be printed on Windows.

Scenario: Config mode 0644

• WHEN the config file permissions are 0644 on a POSIX system
• THEN the CLI prints a one-line stderr warning about permissions and continues normally

Scenario: Config mode 0600

• WHEN the config file permissions are 0600
• THEN the CLI prints no permission warning