Jeden/Docs

CLI command

jeden stats

Show local usage, quota, and session totals or serve the same snapshot as a loopback dashboard.

Exact invocation#

Shell
jeden stats [--json|--summary|--serve [--port N]]

Inputs and options#

  • No mode prints the full text snapshot; --json prints structured data and --summary prints one project summary line.
  • --serve binds the local loopback address; --port N selects a u16 port. Without --port the operating system assigns a free port, and the command prints the address and port it actually bound.
  • Quota entries preserve the provider's explicit state and nullable numeric fields. A null balance or percentage is not evidence of an unlimited allowance. An entry that failed to load keeps its own error; text output reports it as unavailable.
  • JEDEN_BIN=… JEDEN_TEST_SOURCE_REVISION=… node tests/stats/snapshot.mjs runs the built binary in an isolated HOME, session root and project under .build/stats-snapshot: the snapshot and summary over a session root it made, the loopback routes on an operating-system-assigned port, and every refusal below; tests/usage/ledger.mjs covers a ledger of another shape. Each command, exit status and output is kept in the run's report.json. It does not qualify graphical interactions or account-specific quota outcomes.

Output and state effect#

Reads the project and user usage ledgers through jeden.usage.ledger, the live quotas of the browser-automation alternative, and every session directory under the session root jeden sessions lists (JEDEN_SESSION_ROOT, else ~/.jeden/sessions) in newest-modified order. The shared JSON snapshot and dashboard do not hide older sessions behind an undeclared display ceiling. Serve mode exposes only / and /api/stats on loopback until stopped. The page reads once when opened; later reads require Refresh. There is no periodic refresh. The button is disabled during a read. Each successful snapshot shows its generation timestamp.

Refusals and boundaries#

  • The functionality is jeden.stats; jeden errors show jeden.stats prints every cause with its test. Read before anything else, each exit 2: option-unknown (stats takes --json, --summary, or --serve with an optional --port <n>, and `WORD` is none of them), modes-conflicting (two of --json, --summary and --serve), port-without-serve, port-missing and port-invalid (jeden stats --serve --port takes a port number from 0 to 65535, not VALUE).
  • Exit 1: port-unbindable (cannot bind 127.0.0.1:PORT: another process listens on that port, or this user may not bind it, observed: what the system answered) and address-unprintable (standard output is closed, so the dashboard stops instead of serving unseen).
  • A part of the snapshot that cannot be read is reported in place with its declared refusal, never as zero: a usage ledger refused by jeden.state.file (cannot be read, not JSON) or jeden.usage.ledger.ledger-malformed (PATH is not a usage ledger, with the field the decoder missed) is the scope's error, printed as usage (<scope>) unreadable: … and shown by the dashboard as usage unreadable: …; a session root jeden.session.list.root-unlistable refuses or a session that cannot be examined (jeden.stats.session-unexaminable) is sessions.error, printed as sessions unreadable: …. A missing ledger or session root is no usage and no sessions. --summary refuses either with its own cause and a context: line naming what it adds up.
  • Unknown HTTP paths return 404. Unavailable quota is reported in the snapshot rather than represented as available.
  • A host clock set before the Unix epoch gives the snapshot no time: generatedAtMs is then an object whose error is the declared refusal jeden.clock.before-epoch, and the dashboard says the snapshot was generated at an undated moment with that cause, instead of stamping it as the epoch.
  • A failed dashboard request displays GET /api/stats failed: with the actual fetch or decoding error, or the HTTP status and response body. The page keeps the previous complete snapshot and labels it as previous; if none succeeded, it says no snapshot is available. A later successful read clears the error.
  • A command line of the wrong form (an unknown command or option, a missing, unexpected or invalid argument, a missing confirmation) prints the error and the usage and exits 2; a refusal that retrying unchanged can help (a dependency down or not answering, a rate limit) exits 69; any other refusal or failure exits 1. A refusal a functionality declares ends with fix: … and cause: <operation>.<cause>, and jeden errors show <operation> lists every cause of that functionality.