codex-quota Practical Guide: Local, Web, and Docker Usage with Original CLI Commands

Thu, 16 Apr 2026 18:13:04 +0800

What This Project Does

codex-quota is a lightweight tool for checking ChatGPT Codex quota usage, with data fetched from https://chatgpt.com/backend-api/wham/usage.

Main features:

Supports both single-account and multi-account queries (account/*.auth.json).
Outputs five_hour%, weekly%, weekly_reset, and marks the source (network or cache).
Uses exponential backoff retries for temporary failures (408, 429, 5xx).
Includes local caching to reduce repeated requests when quota is already exhausted.
Provides a Web Dashboard, JSON API, and auth file management pages.

Advantages:

Lightweight: runs with simple scripts and minimal dependencies.
Practical: supports both CLI and Web entry points.
Deployable: works with Docker and Docker Compose.
Easy to operate: includes retry, cache, and scheduled refresh support.

Prepare Account Credentials First

Create credential files in account/<name>.auth.json, for example:

{
  "tokens": {
    "access_token": "eyJ...",
    "account_id": "user-xxxxxxxx"
  }
}

Explanation:

access_token and account_id are required by the usage API.
<name> in the filename is used as the account name in output.

Local CLI Usage (Keep Original Commands)

Install dependencies:

`1`	`pip install -r requirements.txt`

Explanation: installs project dependencies.

Query all accounts:

`1`	`python codex_quota.py`

Explanation: reads account/*.auth.json and outputs quota summary for all accounts.

Query one account:

`1`	`python codex_quota.py your_account_name`

Explanation: only queries account/your_account_name.auth.json.

Force refresh (skip cache):

`1`	`python codex_quota.py --refresh`

Explanation: ignores local cache and fetches fresh data directly.

CLI Options (Aligned with README)

account_name: optional account name (without .auth.json).
--account-dir: auth directory, default account.
--chatgpt-url: quota API endpoint.
--raw-json: print full JSON response body.
--raw-headers: print response headers.
--refresh: ignore cache.
--retries: retry count, default 3.
--retry-delay: base retry delay in seconds, default 2.0.

Web Dashboard Usage (Keep Original Command)

Start the service:

`1`	`python codex_quota_service.py --host 0.0.0.0 --port 8081`

Explanation: starts HTTP service listening on port 8081.

Access URL: http://localhost:8081

Service options:

--host: bind address, default 0.0.0.0.
--port: service port, default 8081.
--interval-seconds: scheduled refresh interval, default 3600.
--account-dir: auth directory, default account.
--state-file: state file path, default <account-dir>/codex_quota_web_results.json.
--account-name: optional single-account mode.
--chatgpt-url: quota API endpoint.
--retries: retry count.
--retry-delay: base retry delay.
--refresh: ignore CLI cache during scheduled runs.

HTTP Endpoints (For Automation)

GET /: dashboard page.
GET /api/results: latest results in JSON.
GET /refresh: trigger immediate refresh and redirect to /.
GET /auth: list auth files.
GET /auth/new: form to create auth file.
GET /auth/edit?name=<account>: form to edit auth file.
POST /auth/save: create/update auth file.
POST /auth/delete: delete auth file.

Docker Usage (Keep Original Commands)

Build image:

`1`	`docker build -t codex-quota .`

Explanation: builds the current project as image codex-quota.

Run container (map 8081):

`1`	`docker run --rm -p 8081:8081 -v ./account:/app/account codex-quota`

Explanation:

--rm: remove container automatically after exit.
-p 8081:8081: map host port to container port.
-v ./account:/app/account: mount local credentials into container.

Access URL: http://localhost:8081

Docker Compose Usage (Keep Original Command)

Start:

`1`	`docker compose up --build`

Explanation: build and start services based on docker-compose.yml.

Access URL: http://localhost:8081

Usage Tips

For multi-account scenarios, use Dashboard first for unified view and auth management.
For alerting or automation, prefer GET /api/results.
Do not commit real access_token values to public repositories.
If you see many temporary failures, increase --retries and --retry-delay.

Quota Tracking on KnightLi Blog

codex-quota Practical Guide: Local, Web, and Docker Usage with Original CLI Commands

What This Project Does

Prepare Account Credentials First

Local CLI Usage (Keep Original Commands)

CLI Options (Aligned with README)

Web Dashboard Usage (Keep Original Command)

HTTP Endpoints (For Automation)

Docker Usage (Keep Original Commands)

Docker Compose Usage (Keep Original Command)

Usage Tips