---
canonical: "https://agi-labo.com/en/tools/cockpit/docs/cockpit-cli/reference/usage"
title: "cockpit usage"
description: "Generated reference for cockpit usage, including its syntax, options, results, and constraints from the canonical cockpit CLI source."
section: "Reference"
order: 104
pageType: reference
lastVerifiedVersion: 4.61.0
lastVerifiedAt: "2026-08-27"
draft: false
surfaces:
  - cli
operatingSystems:
  - windows
  - macos
  - linux
plans:
  - guest
  - member
navigation: false
---

This reference is generated from the same canonical source distributed as cockpit CLI help. See [Cockpit CLI](/en/tools/cockpit/docs/cockpit-cli) for concepts and safe operating guidance.

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

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