zenmux-usage-cli

zenmux-usage

Terminal CLI for checking ZenMux subscription usage across one or more accounts. Shows the 5-hour, 7-day, and monthly quota windows plus the USD value of tokens consumed. Single static Go binary, no runtime dependencies.

Install

go install github.com/kotoyuuko/zenmux-usage-cli/cmd/zenmux-usage@latest

Or build from a checkout:

make build   # produces ./zenmux-usage
make cross   # cross-compiles to dist/ for darwin/linux/windows

Configure

Copy the example config and add your ZenMux Management API keys (standard keys are rejected by the API — use a Management key):

mkdir -p ~/.config/zenmux-usage
cp config.example.yaml ~/.config/zenmux-usage/config.yaml
chmod 600 ~/.config/zenmux-usage/config.yaml

The CLI prints a stderr warning if the file has any group- or world-readable bits set. Keys are plaintext, so keep the file at 0600.

Schema

accounts:
  - name: personal
    api_key: sk-zm-...
  - name: work
    api_key: sk-zm-...

• accounts (required): list of one or more entries.
• name (required): unique identifier used as the section header in output and as the --account flag value.
• api_key (required): ZenMux Management API key.
• Unknown fields are ignored with a one-line stderr warning.

Alternative paths

• --config <path> overrides the default location.
• $XDG_CONFIG_HOME/zenmux-usage/config.yaml is honored when that env var is set.
• Falls back to ~/.config/zenmux-usage/config.yaml.

Zero-config fallback

If no config file exists and ZENMUX_MANAGEMENT_API_KEY is set, the CLI runs in single-account mode (the account is labeled env in output).

Usage

zenmux-usage                   # render all configured accounts
zenmux-usage --account work    # render one account from the config
zenmux-usage --json            # machine-readable output
zenmux-usage --api-key sk-...  # one-shot; ignore config file
zenmux-usage --config ./c.yaml # explicit config path
zenmux-usage --no-color        # strip ANSI
zenmux-usage --timeout 5s      # HTTP timeout per account

Example output

━━━ personal ━━━
ZenMux Subscription — Ultra plan ($200/mo) · healthy · $0.03283/flow

  5 hour  [██░░░░░░░░░░░░░░░░░░░░░░░░░░░░]    7.15%   57.2 / 800 flows      $1.88 / $26.26
  7 day   [██░░░░░░░░░░░░░░░░░░░░░░░░░░░░]    6.73%   416.11 / 6182 flows   $13.66 / $202.95
  month   [░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░]    n/a     — / 34560 flows       — / $1134.33

  Tokens consumed (estimated USD value): $13.66
  Next reset: 5h → 2026-04-22 22:05  ·  7d → 2026-04-28 08:00

━━━ work ━━━
ZenMux Subscription — Pro plan ($50/mo) · healthy · $0.01000/flow
  ...

Bars are color-coded: green <60%, yellow 60–85%, red >85%.

Flags

Flag	Default	Purpose
--account <name>	—	Filter to one account from the config
--config <path>	$XDG_CONFIG_HOME/zenmux-usage/config.yaml	Override config file location
--api-key <key>	—	Use this key directly; skip the config file
--json	false	Emit JSON on stdout instead of the human layout
--no-color	false	Disable ANSI colors (also honors NO_COLOR)
--timeout <dur>	10s	HTTP timeout per account
--version	—	Print version and exit

Exit codes

Code	Meaning
0	All fetched accounts succeeded
1	Unexpected error, or at least one account failed while others succeeded, or all accounts failed with mixed causes
2	Invalid flags, unexpected positional args, or unknown --account name
3	No account resolvable (no config file, no env var, no --api-key)
4	Every fetched account failed with HTTP 401/403 (auth rejected)
5	Every fetched account failed with HTTP 422 (rate limit)
6	Every fetched account failed with network error or timeout
7	Config file parse or schema error

Rule for multi-account runs: exit codes 4, 5, and 6 only apply when every account failed with the same cause. Any mix of successes and failures — or failures with different causes — yields exit code 1. Single-account runs always get the specific code.

JSON output

--json emits different shapes depending on how many accounts were resolved.

Single account

When only one account is fetched (via --account, --api-key, or the env-var fallback), the output is the raw API response unchanged:

zenmux-usage --api-key sk-zm-xxx --json | jq .data.plan.tier
# "ultra"

Multiple accounts

When two or more accounts are fetched, the output is a JSON array ordered by config position. Each entry has account, success, data, and error. Failed accounts have data: null and a non-empty error.

zenmux-usage --json | jq '.[] | {account, pct: .data.quota_7_day.usage_percentage}'
# {"account": "personal", "pct": 0.0673}
# {"account": "work",     "pct": 0.4012}

zenmux-usage --json | jq '.[] | select(.success == false) | .account'
# "work"

Development

make test    # run all tests
make vet     # go vet
make lint    # vet + gofmt check
make cross   # build binaries for all supported targets under dist/

API

Uses GET https://zenmux.ai/api/v1/management/subscription/detail. See https://zenmux.ai/docs/api/platform/subscription-detail.html.

The base URL can be overridden via ZENMUX_BASE_URL (useful for staging or local testing).