@indigoai-us/hq-cli 5.345.41 → 5.345.42

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## [Unreleased]
 
+## [5.345.42] — 2026-10-07
+- `hq db usage --app <name>` shows one database app's included amounts, use, overage, read-only ceiling and estimated monthly charge.
+
 ## [5.345.41] — 2026-10-07
 - Short-lived hq commands now use a fresh cached company flag snapshot while the registry refresh is pending.
 - Report failed and quota-interrupted keep-alive lead lanes as stranded in the keep-alive audit and `hq doctor`, with the senior recovery command and quota reset time.

package/dist/command-catalog.generated.d.ts

@@ -2012,7 +2012,7 @@ export declare const COMMAND_CATALOG: readonly [{
         readonly subcommands: readonly [];
     }, {
         readonly name: "usage";
-        readonly description: "Show this month's remote database usage against the compute and storage caps";
+        readonly description: "Show this month's remote database usage. With --app: included, used, overage, ceiling and the estimated charge for one app";
         readonly aliases: readonly [];
         readonly hidden: false;
         readonly helpOption: true;
@@ -2024,6 +2024,10 @@ export declare const COMMAND_CATALOG: readonly [{
             readonly flags: "--company <slug>";
             readonly description: "Company slug";
             readonly hidden: false;
+        }, {
+            readonly flags: "--app <name>";
+            readonly description: "Show one app: included amounts, use, overage, ceiling and estimated charge";
+            readonly hidden: false;
         }];
         readonly subcommands: readonly [];
     }, {

package/dist/command-catalog.generated.js

@@ -2414,7 +2414,7 @@ export const COMMAND_CATALOG = [
             },
             {
                 "name": "usage",
-                "description": "Show this month's remote database usage against the compute and storage caps",
+                "description": "Show this month's remote database usage. With --app: included, used, overage, ceiling and the estimated charge for one app",
                 "aliases": [],
                 "hidden": false,
                 "helpOption": true,
@@ -2427,6 +2427,11 @@ export const COMMAND_CATALOG = [
                         "flags": "--company <slug>",
                         "description": "Company slug",
                         "hidden": false
+                    },
+                    {
+                        "flags": "--app <name>",
+                        "description": "Show one app: included amounts, use, overage, ceiling and estimated charge",
+                        "hidden": false
                     }
                 ],
                 "subcommands": []

package/dist/commands/db-remote-deps.js

@@ -54,6 +54,9 @@ export function describeRemoteError(error) {
     if (status === 404 && code === "DB_USAGE_NOT_PROVISIONED") {
         return "This company has no remote database yet. Run hq db provision first.";
     }
+    if (status === 404 && code === "DB_USAGE_APP_NOT_FOUND") {
+        return "No database found for that app in this company. Check the app name, or deploy it with database enabled.";
+    }
     return null;
 }
 //# sourceMappingURL=db-remote-deps.js.map

package/dist/commands/db-usage.js

@@ -3,19 +3,26 @@
  */
 import chalk from "chalk";
 import { safeErrorMessage } from "../lib/db/redact.js";
-import { formatUsage } from "../lib/db/usage-format.js";
+import { formatAppUsageResponse, formatUsage } from "../lib/db/usage-format.js";
 import { isPlanGateError } from "../utils/plan-gate-error.js";
 import { controlPlaneClient, defaultRemoteDeps, describeRemoteError, } from "./db-remote-deps.js";
 export function registerDbUsageCommand(db, depsFactory = defaultRemoteDeps) {
     db.command("usage")
-        .description("Show this month's remote database usage against the compute and storage caps")
+        .description("Show this month's remote database usage. With --app: included, used, overage, ceiling and the estimated charge for one app")
         .requiredOption("--company <slug>", "Company slug")
+        .option("--app <name>", "Show one app: included amounts, use, overage, ceiling and estimated charge")
         .action(async (opts) => {
         try {
             const deps = depsFactory();
             const resolved = await deps.resolveCompany(String(opts.company ?? "").trim());
-            const usage = await controlPlaneClient(deps).usage(resolved.companyUid);
-            console.log(formatUsage(usage));
+            const client = controlPlaneClient(deps);
+            const app = String(opts.app ?? "").trim();
+            if (app) {
+                console.log(formatAppUsageResponse(await client.appUsage(resolved.companyUid, app)));
+            }
+            else {
+                console.log(formatUsage(await client.usage(resolved.companyUid)));
+            }
         }
         catch (error) {
             if (isPlanGateError(error))

package/dist/lib/db/control-plane.d.ts

@@ -24,6 +24,38 @@ export interface RemoteStatusResponse {
         secretRef: string;
     } | null;
 }
+export type RemoteAppLimitState = "ok" | "warn" | "overage" | "locked";
+/** One app that owns its cluster. Cents are whole US cents; `estimate` is null for an exempt company. */
+export interface RemoteAppUsage {
+    appId: string;
+    period: string;
+    measuredAt: string | null;
+    ended: boolean;
+    state: RemoteAppLimitState;
+    locked: boolean;
+    exempt: boolean;
+    dpu: {
+        used: number;
+        included: number;
+        overage: number;
+        ceiling: number;
+        pct: number;
+    };
+    storage: {
+        usedBytes: number;
+        billedBytes: number;
+        includedBytes: number;
+        overageGbMonth: number;
+        ceilingBytes: number;
+        pct: number;
+    };
+    estimate: {
+        baseCents: number;
+        dpuOverageCents: number;
+        storageOverageCents: number;
+        totalCents: number;
+    } | null;
+}
 export interface RemoteUsageResponse {
     companyUid: string;
     dpuUsed: number;
@@ -34,7 +66,20 @@ export interface RemoteUsageResponse {
     pctStorage: number;
     period: string;
     measuredAt: string | null;
+    /** False when every app owns its own cluster and there is no shared company database. */
+    companyCluster?: boolean;
+    apps?: RemoteAppUsage[];
 }
+/** Answer for one app: its own numbers, or the company numbers when it shares the company cluster. */
+export type RemoteAppUsageResponse = (RemoteAppUsage & {
+    companyUid: string;
+    mode: "app-cluster";
+    status?: string;
+}) | (RemoteUsageResponse & {
+    appId: string;
+    mode: "company-cluster";
+    exempt?: boolean;
+});
 /**
  * Scoped temporary AWS credentials for one app's database role. The control
  * plane would issue these from `POST /v1/db/apps/{appId}/session`.
@@ -74,6 +119,7 @@ export declare class ControlPlaneDbClient {
         region?: string;
     }): Promise<RemoteProvisionResponse>;
     status(companyUid: string): Promise<RemoteStatusResponse>;
+    appUsage(companyUid: string, appId: string): Promise<RemoteAppUsageResponse>;
     usage(companyUid: string): Promise<RemoteUsageResponse>;
     appSession(input: {
         companyUid: string;

package/dist/lib/db/control-plane.js

@@ -78,6 +78,20 @@ export class ControlPlaneDbClient {
         }
         return JSON.parse(text);
     }
+    async appUsage(companyUid, appId) {
+        const token = await this.getAccessToken();
+        const query = `companyUid=${encodeURIComponent(companyUid)}&appId=${encodeURIComponent(appId)}`;
+        const res = await this.fetchImpl(`${this.baseUrl}/v1/db/usage?${query}`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(DB_STATUS_TIMEOUT_MS),
+        });
+        const text = await res.text();
+        assertNoPostgresUrl("usage", text);
+        if (!res.ok)
+            throw httpError("usage", res.status, text);
+        return JSON.parse(text);
+    }
     async usage(companyUid) {
         const token = await this.getAccessToken();
         const url = `${this.baseUrl}/v1/db/usage?companyUid=${encodeURIComponent(companyUid)}`;

package/dist/lib/db/usage-format.d.ts

@@ -1,4 +1,7 @@
-import type { RemoteUsageResponse } from "./control-plane.js";
+import type { RemoteAppUsage, RemoteAppUsageResponse, RemoteUsageResponse } from "./control-plane.js";
 export declare function formatBytes(bytes: number): string;
 export declare function formatUsage(usage: RemoteUsageResponse): string;
+export declare function formatAppUsage(usage: RemoteAppUsage): string;
+export declare function formatAppUsageResponse(response: RemoteAppUsageResponse): string;
+export declare function formatCompanyApps(apps: RemoteAppUsage[]): string;
 //# sourceMappingURL=usage-format.d.ts.map

package/dist/lib/db/usage-format.js

@@ -36,6 +36,72 @@ export function formatUsage(usage) {
         lines.push(`Over the cap for ${over.join(" and ")}.`);
     else if (usage.pctDpu >= 80 || usage.pctStorage >= 80)
         lines.push("Close to a cap (80% or more).");
+    if (usage.companyCluster === false) {
+        lines.splice(1, 2, "This company has no shared database. Each app has its own, listed below.");
+    }
+    const apps = formatCompanyApps(usage.apps ?? []);
+    if (apps)
+        lines.push(apps);
     return lines.join("\n");
 }
+function dollars(cents) {
+    return `$${(cents / 100).toFixed(2)}`;
+}
+function count(value) {
+    return Math.round(value).toLocaleString("en-US");
+}
+function gbMonth(value) {
+    return `${value.toFixed(2)} GB-month`;
+}
+const STATE_LINES = {
+    ok: "Within the included amounts.",
+    warn: "Close to the included amount (80% or more). Use above it is billed as overage.",
+    overage: "Above the included amount. The extra use is billed as overage.",
+    locked: "At the ceiling. The database is read-only: reads work, writes are refused. Move this app to a larger service, or contact HQ support to raise the limit.",
+};
+export function formatAppUsage(usage) {
+    const lines = [
+        `Database usage for app ${usage.appId}, ${usage.period}`,
+        `Compute: ${count(usage.dpu.used)} of ${count(usage.dpu.included)} included units (${percent(usage.dpu.pct)}), overage ${count(usage.dpu.overage)}, ceiling ${count(usage.dpu.ceiling)}`,
+        `Storage: ${formatBytes(usage.storage.usedBytes)} of ${formatBytes(usage.storage.includedBytes)} included (${percent(usage.storage.pct)}), month average ${formatBytes(usage.storage.billedBytes)}, overage ${gbMonth(usage.storage.overageGbMonth)}, ceiling ${formatBytes(usage.storage.ceilingBytes)}`,
+        STATE_LINES[usage.locked ? "locked" : usage.state],
+    ];
+    if (usage.estimate) {
+        const e = usage.estimate;
+        lines.push(`Estimated charge this month: ${dollars(e.totalCents)} (${dollars(e.baseCents)} base, ${dollars(e.dpuOverageCents)} compute overage, ${dollars(e.storageOverageCents)} storage overage)`);
+    }
+    else if (usage.exempt) {
+        lines.push("Not billed: this company is exempt from database app charges.");
+    }
+    if (usage.ended)
+        lines.push("This app was deleted. Usage up to deletion still counts for the month.");
+    lines.push(usage.measuredAt === null
+        ? "Not measured yet, so usage shows as 0. Check again in about 15 minutes."
+        : `Last measured ${usage.measuredAt}. Numbers can lag by a few minutes.`);
+    return lines.join("\n");
+}
+export function formatAppUsageResponse(response) {
+    if (response.mode === "company-cluster") {
+        return [
+            `App ${response.appId} uses the shared company database, so these are the company numbers.`,
+            formatUsage(response),
+        ].join("\n");
+    }
+    return formatAppUsage(response);
+}
+export function formatCompanyApps(apps) {
+    if (apps.length === 0)
+        return "";
+    const rows = apps.map((app) => {
+        const note = app.locked
+            ? ", read-only"
+            : app.state === "warn"
+                ? ", close to the included amount"
+                : app.state === "overage"
+                    ? ", over the included amount"
+                    : "";
+        return `  ${app.appId}: ${count(app.dpu.used)} of ${count(app.dpu.included)} compute (${percent(app.dpu.pct)}), ${formatBytes(app.storage.usedBytes)} of ${formatBytes(app.storage.includedBytes)} storage (${percent(app.storage.pct)})${note}${app.ended ? ", deleted" : ""}`;
+    });
+    return ["Apps with their own database:", ...rows, "Run hq db usage --app <name> for one app."].join("\n");
+}
 //# sourceMappingURL=usage-format.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.345.41",
+  "version": "5.345.42",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {