cockpit usage
Generated reference for cockpit usage, including its syntax, options, results, and constraints from the canonical cockpit CLI source.
Some screens and steps may differ in the latest version.
This reference is generated from the same canonical source distributed as cockpit CLI help. See Cockpit CLI for concepts and safe operating guidance.
Read agent usage, and spend a Codex usage reset credit.
cockpit usage
cockpit usage reset --agent-type codex --confirm
cockpit usage reset --agent-type codex --account work --confirm
cockpit usage returns one snapshot for every usage provider AGI Cockpit tracks: Claude, Codex, Antigravity, Cursor, Qoder, Grok, and Cockpit's own model spend, each with its per-account profiles, its rate-limit buckets, and — for Codex — resetCreditsAvailable and the resetCredits entries with their expiration dates. It is a read; it never spends anything.
Spending a reset credit
reset consumes one earned Codex reset credit for one account, which clears that account's current rate-limit window. This is the same operation as the account's reset button in the Usage panel, routed through the same main-process code, so the GUI and the CLI validate the same way and report the same outcomes.
Spending a credit cannot be undone. Credits are earned, finite, and expire; there is no refund and no way to re-earn one on demand. --confirm is therefore mandatory, exactly as it is for cockpit accounts remove — a non-interactive agent cannot spend a credit unless the flag was typed deliberately.
--agent-type is mandatory and has no default. Codex is the only provider that has reset credits today, but a default would silently change meaning the day a second provider gains an equivalent, so the account's provider is always stated. An unsupported value answers HTTP 400 usage_reset_unsupported and lists the providers that do support a reset.
--account takes the same selector as cockpit accounts: an account name, a profile id, or default (the default is default when the option is omitted). An unknown selector answers HTTP 404 account_not_found; an account that exists but is not signed in answers HTTP 400 usage_reset_failed with the same validation message the Usage panel shows. Read resetCreditsAvailable from cockpit usage or cockpit accounts list --agent-type codex before spending.
Outcomes
A request that reached the Codex account answers HTTP 200 with data.outcome, data.success, data.account, and a localized data.message.
outcome |
Meaning | Credit spent | Exit code |
|---|---|---|---|
reset |
The rate-limit window was cleared | yes | 0 |
nothingToReset |
No limit is currently in effect, so there was nothing to clear | no | 0 |
alreadyRedeemed |
That reset had already been used | no | 0 |
noCredit |
The account has no reset credit available | no | 3 |
noCredit gets its own exit code so a script can tell "there is nothing left to spend" from a failed request without parsing the body; data.success is false for it and true for the other three. Every other failure — a missing --confirm, an unknown account, a signed-out account, an unsupported agent type, a provider error — exits 1 with {"ok": false, ...}.
An unreachable AGI Cockpit also exits 1, with {"ok": false, "error": "Cannot reach AGI Cockpit (127.0.0.1:<port>) ..."}. usage is a local control family, like settings, update, remote-access, setup, and hooks, and every one of them reports an unreachable app as exit 1; the exit 7 described in cockpit help transport is the behaviour of the task family and of cockpit doctor, which is why that page tells you to branch on either exit 7 or the Cannot reach AGI Cockpit body. Retry logic around usage reset must therefore read the error body: exit 1 alone does not distinguish "AGI Cockpit is down, retry" from "the request was rejected, do not retry".