feat: add usage to providers list

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.
 

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

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 {

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")}`,