From 8ce6f783f04ffd57de85263dbd0770b9d89f8031 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 8 Jan 2026 02:48:51 +0100
Subject: [PATCH] feat: add usage to providers list

---
 docs/cli/index.md               |  4 ++++
 docs/concepts/usage-tracking.md |  2 +-
 src/cli/providers-cli.ts        |  1 +
 src/commands/providers.ts       | 12 ++++++++++++
 4 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/docs/cli/index.md b/docs/cli/index.md
index 146d834b3..6a827f865 100644
--- a/docs/cli/index.md
+++ b/docs/cli/index.md
@@ -220,6 +220,10 @@ Common options:
 - `--account <id>`: provider account id (default `default`)
 - `--name <label>`: display name for the account
 
+`providers list` options:
+- `--usage`: include provider usage/quota snapshots (OAuth/API-backed only).
+- `--json`: output JSON (includes usage when `--usage` is set).
+
 ### `pairing`
 Approve DM pairing requests across providers.
 
diff --git a/docs/concepts/usage-tracking.md b/docs/concepts/usage-tracking.md
index 2c8e6531c..b9e0b64f6 100644
--- a/docs/concepts/usage-tracking.md
+++ b/docs/concepts/usage-tracking.md
@@ -13,6 +13,7 @@ read_when:
 ## Where it shows up
 - `/status` in chats: adds a short “Usage” line (only if available).
 - CLI: `clawdbot status --usage` prints a full per-provider breakdown.
+- CLI: `clawdbot providers list --usage` prints the same usage snapshot alongside provider config.
 - macOS menu bar: “Usage” section under Context (only if available).
 
 ## Providers + credentials
@@ -24,4 +25,3 @@ read_when:
 - **z.ai**: API key via env/config/auth store.
 
 Usage is hidden if no matching OAuth/API credentials exist.
-
diff --git a/src/cli/providers-cli.ts b/src/cli/providers-cli.ts
index 5e2db2e5b..ce9c759c8 100644
--- a/src/cli/providers-cli.ts
+++ b/src/cli/providers-cli.ts
@@ -51,6 +51,7 @@ export function registerProvidersCli(program: Command) {
   providers
     .command("list")
     .description("List configured providers + auth profiles")
+    .option("--usage", "Show provider usage/quota snapshots", false)
     .option("--json", "Output JSON", false)
     .action(async (opts) => {
       try {
diff --git a/src/commands/providers.ts b/src/commands/providers.ts
index 3fa3ce716..2d7d30d43 100644
--- a/src/commands/providers.ts
+++ b/src/commands/providers.ts
@@ -12,6 +12,10 @@ import {
   resolveDiscordAccount,
 } from "../discord/accounts.js";
 import { callGateway } from "../gateway/call.js";
+import {
+  formatUsageReportLines,
+  loadProviderUsageSummary,
+} from "../infra/provider-usage.js";
 import {
   listIMessageAccountIds,
   resolveIMessageAccount,
@@ -56,6 +60,7 @@ type ChatProvider = (typeof CHAT_PROVIDERS)[number];
 
 type ProvidersListOptions = {
   json?: boolean;
+  usage?: boolean;
 };
 
 type ProvidersStatusOptions = {
@@ -461,6 +466,7 @@ export async function providersListCommand(
         profileId === CODEX_CLI_PROFILE_ID,
     }),
   );
+  const usage = opts.usage ? await loadProviderUsageSummary() : undefined;
 
   if (opts.json) {
     const payload = {
@@ -473,6 +479,7 @@ export async function providersListCommand(
         imessage: imessageAccounts,
       },
       auth: authProfiles,
+      ...(usage ? { usage } : {}),
     };
     runtime.log(JSON.stringify(payload, null, 2));
     return;
@@ -567,6 +574,11 @@ export async function providersListCommand(
     }
   }
 
+  if (usage) {
+    lines.push("");
+    lines.push(...formatUsageReportLines(usage));
+  }
+
   lines.push("");
   lines.push(
     `Docs: ${docsLink("/gateway/configuration", "gateway/configuration")}`,