zenmux-usage-cli/openspec/changes/archive/2026-04-22-build-usage-cli/proposal.md

Why

ZenMux users on paid tiers need a fast, terminal-native way to see how much of their rolling subscription quota they have burned through. The web dashboard is fine for occasional checks, but for developers iterating at the command line it is too many clicks away. A small Go CLI that hits GET /api/v1/management/subscription/detail and renders the 5-hour, 7-day, and monthly windows — plus the USD value of tokens consumed — gives immediate visibility without leaving the shell. Many users also run more than one ZenMux account (personal + work, or multiple projects), so the CLI needs to pull several accounts from a single config file and show them side by side.

What Changes

• Introduce a new Go CLI binary zenmux-usage that renders ZenMux subscription quota data in the terminal.
• Multi-account support via a YAML config file at ~/.config/zenmux-usage/config.yaml listing one or more accounts (name, api_key). By default, the CLI fetches and renders every account in the file, one section per account.
• Support flags:
  • --account <name> — restrict output to a single named account from the config
  • --config <path> — override the default config file path
  • --api-key <key> — one-shot single-account override (bypasses config entirely)
  • --json — raw passthrough of the API response(s); shape is an array when multiple accounts, single object when only one
  • --no-color — disable ANSI
  • --timeout <duration> — HTTP timeout
• Render each account's three quota windows as labeled progress bars with usage percentage, used vs. max flows, and used USD value; below the bars show the plan, effective per-flow rate, and account status, plus the tokens-consumed USD summary.
• Preserve a no-config fallback: if no config file exists and ZENMUX_MANAGEMENT_API_KEY is set, behave as single-account.
• Handle common error cases (missing config/key, 401/403, 422 rate-limit, network timeout) with distinct exit codes and clear messages. With multiple accounts, one account's failure MUST NOT prevent the others from rendering.

Capabilities

New Capabilities

• subscription-usage: Fetch ZenMux subscription detail and render quota windows and token USD value in the terminal.
• account-config: Load one or more ZenMux accounts from a YAML config file and resolve which account(s) the CLI should act on for a given invocation.

Modified Capabilities

Impact

• New Go module at repo root with main.go entrypoint under cmd/zenmux-usage/.
• Dependencies: Go standard library for HTTP/JSON; github.com/fatih/color for terminal rendering; gopkg.in/yaml.v3 for config parsing.
• No backend or API changes — this consumes an existing ZenMux endpoint (one request per account).
• Adds a README.md usage section documenting the YAML schema and an example config.example.yaml file committed to the repo.
• Config file contains API keys, so documentation MUST advise chmod 600 and avoid committing it.