cockpit usage

このReference本文は、アプリが配布するcockpit CLIヘルプと同じ英語の正本から自動生成されています。日本語の概念説明と安全な使い方はcockpit CLIを参照してください。

Read agent usage, and spend a Codex usage reset credit.

cockpit usage
cockpit usage --all
cockpit usage reset --agent-type codex --confirm
cockpit usage reset --agent-type codex --account work --confirm

cockpit usage returns one snapshot per usage provider, 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.

Claude accounts carry the limit resets granted to the account, when Claude reports them: limitResetsAvailable is the total number of unused resets, and limitResets lists the grants that still have resets left, nearest expiration first, each with resetsLeft, endsAt (the date the unused resets expire), and label when Claude names the grant. Paused and expired grants are not counted. Claude reports this through an undocumented part of its usage API, so both fields are omitted — never reported as zero — when the account is not eligible, the information is missing, or its shape cannot be read; the five-hour, weekly, and model-specific windows are unaffected either way. limitResetsAvailable is 0 only when Claude explicitly reports an eligible account with no resets left. Cockpit only reads limit resets; cockpit usage reset cannot spend them.

Claude accounts also carry extraUsage when extra usage is enabled. It is { "usedCredits": <number>, "monthlyLimit": <number|null>, "currency": "<ISO 4217>" }: usedCredits is this month's extra-usage spend and monthlyLimit is that month's spend limit. Both amounts are minor units of currency, the same units Claude reports (cents when currency is USD). monthlyLimit is null when Claude reports that extra usage is enabled and there is no monthly cap; that is a known unlimited limit, not a missing reading. The field is omitted when extra usage is disabled, the response has no extra-usage block, or the spend or the currency cannot be read. A missing field means the spend is not known, never zero. This is a spend against a monthly limit, separate from a purchased balance and from limit resets. A change in the shape of this block leaves the five-hour, weekly, and model-specific windows as they were.

Codex accounts also carry credits, the balance of credits purchased for the ChatGPT account, as reported by Codex with its rate limits. It is { "unlimited": false, "balance": <number> } for a positive balance, or { "unlimited": true } for an account with unlimited credits. credits is omitted when the account has no purchased credits or Codex did not report a balance, so a missing field means "not known", never zero. Purchased credits are separate from reset credits: they are not spent by cockpit usage reset.

Muse Code has no remaining-quota query: it reports the account's subscription usage only while it calls a model, and keeps no copy. Cockpit therefore records the newest report from its Muse Code native-UI conversations (Muse Code's usage/changed notification, and usage/read after each turn), keeps it across restarts, and returns it as muse: { "fiveHour": { "usedPercent", "resetsAt", "windowDurationMins"? }, "weekly": { "usedPercent", "resetsAt" }, "planTier"?, "observedAt" }. The percentages are Muse Code's own, observedAt and metadata.muse.fetchedAt are the time of that report, and metadata.muse.state is ok for a report from the last 15 minutes and stale after that. Before the first report muse is null with metadata.muse.state unknown. A report belongs to the sign-in it was observed with (the muse login account, or the Meta API key in API-key mode): after a switch to another account or key, muse is null until that sign-in reports usage. Muse Code reports these windows for subscription plans; a pay-as-you-go account has none, so muse stays null. Conversations in Muse Code's terminal app or in a terminal-mode task never reach Cockpit and are not counted.

Which providers are listed

cockpit usage lists only the providers that are set up on this machine, exactly like the Usage screen: an agent CLI whose command cannot be resolved locally — Claude, Codex, Antigravity, Cursor, Qoder, Grok, or Muse Code — is left out, and its usage is not even requested. Cockpit's own model spend needs no CLI and is always listed. Being set up is the only condition: an installed CLI that is signed out, whose authentication expired, or whose usage request failed stays in the response with its metadata.<provider>.state and its error, because that state is the thing you need to act on.

--all restores the unfiltered snapshot and requests every provider, including the ones with no CLI on this machine. Use it to confirm what AGI Cockpit tracks in total, or to read a provider you are about to install.

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.

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".