CLI command
jeden stats
Show local usage, quota, and session totals or serve the same snapshot as a loopback dashboard.
Exact invocation#
jeden stats [--json|--summary|--serve [--port N]]Inputs and options#
- No mode prints the full text snapshot;
--jsonprints structured data and--summaryprints one project summary line. --servebinds the local loopback address;--port Nselects au16port. Without--portthe operating system assigns a free port, and the command prints the address and port it actually bound.- Quota entries preserve the provider's explicit
stateand nullable numeric fields. Anullbalance or percentage is not evidence of an unlimited allowance. An entry that failed to load keeps its ownerror; text output reports it as unavailable. JEDEN_BIN=… JEDEN_TEST_SOURCE_REVISION=… node tests/stats/snapshot.mjsruns 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.mjscovers a ledger of another shape. Each command, exit status and output is kept in the run'sreport.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.statsprints every cause with its test. Read before anything else, each exit2:option-unknown(stats takes --json, --summary, or --serve with an optional --port <n>, and `WORD` is none of them),modes-conflicting(two of--json,--summaryand--serve),port-without-serve,port-missingandport-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) andaddress-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) orjeden.usage.ledger.ledger-malformed(PATH is not a usage ledger, with the field the decoder missed) is the scope'serror, printed asusage (<scope>) unreadable: …and shown by the dashboard asusage unreadable: …; a session rootjeden.session.list.root-unlistablerefuses or a session that cannot be examined (jeden.stats.session-unexaminable) issessions.error, printed assessions unreadable: …. A missing ledger or session root is no usage and no sessions.--summaryrefuses either with its own cause and acontext: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:
generatedAtMsis then an object whoseerroris the declared refusaljeden.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) exits69; any other refusal or failure exits1. A refusal a functionality declares ends withfix: …andcause: <operation>.<cause>, andjeden errors show <operation>lists every cause of that functionality.