@indigoai-us/hq-cli 5.62.2 → 5.64.0

package/dist/commands/agents.d.ts

@@ -22,6 +22,7 @@
  * the caller's single active membership (same as `members.ts`).
  */
 import { Command } from "commander";
+import { type BillingErrorPayload } from "../utils/billing-gate.js";
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
 export declare const VALID_EFFORTS: Set<string>;
 /** Service-tier (speed) values hq-pro accepts on `runtime-config`. */
@@ -35,7 +36,9 @@ export declare const VALID_TIERS: Set<string>;
 export declare class AgentsHttpError extends Error {
     status: number;
     code?: string;
-    constructor(status: number, message: string, code?: string);
+    /** hq-pro's billing envelope on a `402 billing_required` provision block. */
+    billing?: BillingErrorPayload;
+    constructor(status: number, message: string, code?: string, billing?: BillingErrorPayload);
 }
 /** Roster row from `GET /v1/agents` — a superset is returned; we keep what we render. */
 export interface CompanyAgentView {
@@ -79,6 +82,24 @@ export declare function agentsRequest<T>(opts: {
     body?: Record<string, unknown>;
     query?: Record<string, string>;
 }): Promise<T>;
+/** Slugify an agent name into a lowercase, hyphen-separated slug. */
+export declare function slugifyAgentName(name: string): string;
+export interface ProvisionAgentInput {
+    companyUid: string;
+    name: string;
+    slug: string;
+    codexAuthMode: "subscription" | "apiKey";
+    provider?: "codex" | "grok";
+    codexApiKey?: string;
+    idempotencyKey: string;
+    title?: string;
+    description?: string;
+}
+export declare function provisionAgent(token: string, input: ProvisionAgentInput): Promise<{
+    uid?: string;
+    slug?: string;
+    [key: string]: unknown;
+}>;
 export declare function listAgents(token: string, companyUid: string): Promise<CompanyAgentView[]>;
 export declare function getAgentStatus(token: string, agentUid: string): Promise<Record<string, unknown>>;
 export declare function patchAgentProfile(token: string, agentUid: string, patch: ProfilePatch): Promise<{

package/dist/commands/agents.js

@@ -22,10 +22,12 @@
  * the caller's single active membership (same as `members.ts`).
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="8a374059-a137-5cce-94ad-9e2647fc37c5")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="581b1950-a9bc-50a4-b16b-6e6649e9db30")}catch(e){}}();
 import chalk from "chalk";
+import { randomUUID } from "node:crypto";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
+import { AGENT_PRICE_CENTS, confirmChargeOrExit, parseBillingPayload, surfaceBillingRequired, } from "../utils/billing-gate.js";
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
 export const VALID_EFFORTS = new Set([
     "minimal",
@@ -45,11 +47,14 @@ export const VALID_TIERS = new Set(["default", "priority"]);
 export class AgentsHttpError extends Error {
     status;
     code;
-    constructor(status, message, code) {
+    /** hq-pro's billing envelope on a `402 billing_required` provision block. */
+    billing;
+    constructor(status, message, code, billing) {
         super(message);
         this.name = "AgentsHttpError";
         this.status = status;
         this.code = code;
+        this.billing = billing;
     }
 }
 /**
@@ -61,10 +66,26 @@ export async function agentsRequest(opts) {
     const res = await vaultApiFetch(opts);
     if (!res.ok) {
         const body = (await res.json().catch(() => ({})));
-        throw new AgentsHttpError(res.status, body.error ?? body.message ?? res.statusText, body.code);
+        throw new AgentsHttpError(res.status, body.error ?? body.message ?? res.statusText, body.code, parseBillingPayload(body));
     }
     return (await res.json());
 }
+/** Slugify an agent name into a lowercase, hyphen-separated slug. */
+export function slugifyAgentName(name) {
+    return name
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+export async function provisionAgent(token, input) {
+    return agentsRequest({
+        token,
+        path: "/v1/agents",
+        method: "POST",
+        body: input,
+    });
+}
 export async function listAgents(token, companyUid) {
     const data = await agentsRequest({
         token,
@@ -144,6 +165,79 @@ export function registerAgentsCommand(program) {
     // `hq agents --company acme list`.
     const companyOf = (sub) => sub.opts().company ??
         agents.opts().company;
+    agents
+        .command("provision <name>")
+        .alias("new")
+        .description("Provision a new cloud agent ($100/month — requires --yes)")
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--slug <slug>", "Agent slug (defaults to a slug of <name>)")
+        .option("--provider <provider>", "Runtime: codex | grok (default codex)")
+        .option("--auth-mode <mode>", "Codex auth: subscription | apiKey (default subscription)", "subscription")
+        .option("--api-key-env <VAR>", "Env var holding the API key for --auth-mode apiKey (never pass the key as a flag)")
+        .option("--title <title>", "Org-chart job title")
+        .option("--description <text>", "Short description / bio")
+        .option("--yes", "Confirm the $100/month charge (required to provision)")
+        .action(async function (name, opts) {
+        try {
+            const authMode = opts.authMode === "apiKey" ? "apiKey" : "subscription";
+            const provider = opts.provider === "grok" ? "grok" : opts.provider ? "codex" : undefined;
+            // Resolve the API key from the environment (never from a flag value) when
+            // apiKey mode is requested — validated BEFORE the paid gate so we don't
+            // charge and then fail.
+            let codexApiKey;
+            if (authMode === "apiKey") {
+                const envVar = opts.apiKeyEnv;
+                if (!envVar) {
+                    console.error(chalk.red("--auth-mode apiKey requires --api-key-env <VAR> naming the env var that holds the key."));
+                    process.exit(1);
+                }
+                codexApiKey = process.env[envVar];
+                if (!codexApiKey) {
+                    console.error(chalk.red(`Env var ${envVar} is empty or unset — no API key to use.`));
+                    process.exit(1);
+                }
+            }
+            const token = await ensureCognitoToken();
+            const companyUid = await getCompanyUid(token, companyOf(this));
+            // Paid gate: print the monthly cost and require --yes before any call.
+            confirmChargeOrExit({
+                resource: "agent",
+                unitCents: AGENT_PRICE_CENTS,
+                yes: opts.yes,
+            });
+            const slug = opts.slug ?? slugifyAgentName(name);
+            try {
+                const result = await provisionAgent(token, {
+                    companyUid,
+                    name,
+                    slug,
+                    codexAuthMode: authMode,
+                    ...(provider ? { provider } : {}),
+                    ...(codexApiKey ? { codexApiKey } : {}),
+                    idempotencyKey: `hq-cli-${randomUUID()}`,
+                    ...(opts.title ? { title: opts.title } : {}),
+                    ...(opts.description ? { description: opts.description } : {}),
+                });
+                const uid = typeof result.uid === "string" ? result.uid : slug;
+                console.log(chalk.green(`Provisioning started for agent "${name}".`));
+                console.log(chalk.dim(`Track setup: hq agents status ${uid} --company <slug>`));
+            }
+            catch (err) {
+                // No card on file → surface the shareable payment link instead of an
+                // opaque 402, then exit non-zero so scripts can react.
+                if (err instanceof AgentsHttpError &&
+                    err.status === 402 &&
+                    err.billing) {
+                    await surfaceBillingRequired(token, err.billing);
+                    process.exit(1);
+                }
+                throw err;
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
     agents
         .command("list")
         .description("List the company's agents")
@@ -382,4 +476,4 @@ export function registerAgentsCommand(program) {
     });
 }
 //# sourceMappingURL=agents.js.map
-//# debugId=8a374059-a137-5cce-94ad-9e2647fc37c5
+//# debugId=581b1950-a9bc-50a4-b16b-6e6649e9db30

package/dist/commands/billing.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `hq billing` — inspect billing state and mint a card-capture link from the
+ * terminal. Backs the paid-provisioning gate (agents & Outposts): a user can
+ * check whether a card is on file, and proactively hand out the same Stripe
+ * hosted card-capture link that a `402 billing_required` would surface.
+ *
+ * Targets the hq-pro billing control plane on `DEFAULT_VAULT_API_URL` via the
+ * shared `vaultApiFetch` helper — the same routes the console billing surfaces
+ * call.
+ *
+ * Subcommands:
+ *   hq billing status   [--company <slug>]              — subscription + card on file
+ *   hq billing checkout [--company <slug>] [--personal] — mint a card-capture link
+ */
+import { Command } from "commander";
+export declare function registerBillingCommand(program: Command): void;
+//# sourceMappingURL=billing.d.ts.map

package/dist/commands/billing.js

@@ -0,0 +1,114 @@
+/**
+ * `hq billing` — inspect billing state and mint a card-capture link from the
+ * terminal. Backs the paid-provisioning gate (agents & Outposts): a user can
+ * check whether a card is on file, and proactively hand out the same Stripe
+ * hosted card-capture link that a `402 billing_required` would surface.
+ *
+ * Targets the hq-pro billing control plane on `DEFAULT_VAULT_API_URL` via the
+ * shared `vaultApiFetch` helper — the same routes the console billing surfaces
+ * call.
+ *
+ * Subcommands:
+ *   hq billing status   [--company <slug>]              — subscription + card on file
+ *   hq billing checkout [--company <slug>] [--personal] — mint a card-capture link
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9a5d87b5-94d2-5893-8c48-af8db719fa05")}catch(e){}}();
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
+import { mintPaymentLink } from "../utils/billing-gate.js";
+function fail(err) {
+    console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+    process.exit(1);
+}
+async function getBillingSummary(token, companyUid) {
+    const res = await vaultApiFetch({
+        token,
+        path: "/v1/billing/summary",
+        query: { companyUid },
+    });
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        throw new Error(body.error ?? body.message ?? res.statusText);
+    }
+    return (await res.json());
+}
+export function registerBillingCommand(program) {
+    const billing = program
+        .command("billing")
+        .description("Inspect billing and mint a card-capture link")
+        .option("--company <slug>", "Company slug (resolves to companyUid)");
+    const companyOf = (sub) => sub.opts().company ??
+        billing.opts().company;
+    billing
+        .command("status")
+        .description("Show subscription status and whether a card is on file")
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--json", "Emit raw JSON")
+        .action(async function (opts) {
+        try {
+            const token = await ensureCognitoToken();
+            const companyUid = await getCompanyUid(token, companyOf(this));
+            const summary = await getBillingSummary(token, companyUid);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(summary, null, 2) + "\n");
+                return;
+            }
+            const sub = summary.subscriptionStatus ?? "none";
+            console.log(`${chalk.bold("Subscription")}: ${sub}`);
+            const pm = summary.defaultPaymentMethod;
+            if (pm?.present) {
+                const detail = pm.brand && pm.last4 ? `${pm.brand} ••••${pm.last4}` : "on file";
+                console.log(`${chalk.bold("Card")}: ${detail}`);
+            }
+            else {
+                console.log(`${chalk.bold("Card")}: ${chalk.yellow("no card on file")} — ` +
+                    `run \`hq billing checkout\` to add one before provisioning paid resources.`);
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+    billing
+        .command("checkout")
+        .description("Mint a Stripe card-capture link (shareable) to add a card")
+        .option("--company <slug>", "Company slug (resolves to companyUid)")
+        .option("--personal", "Mint the link for your personal payer (Outposts) instead of a company")
+        .option("--json", "Emit raw JSON")
+        .action(async function (opts) {
+        try {
+            const token = await ensureCognitoToken();
+            let setup;
+            if (opts.personal) {
+                setup = {
+                    payerType: "person",
+                    path: "/v1/billing/checkout/person",
+                    method: "POST",
+                };
+            }
+            else {
+                const companyUid = await getCompanyUid(token, companyOf(this));
+                setup = {
+                    payerType: "company",
+                    path: "/v1/billing/checkout/org",
+                    method: "POST",
+                    body: { companyUid },
+                };
+            }
+            const url = await mintPaymentLink(token, setup);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify({ url }, null, 2) + "\n");
+                return;
+            }
+            console.log("Add a card here (safe to share with whoever owns billing):\n  " +
+                chalk.cyan(url));
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
+}
+//# sourceMappingURL=billing.js.map
+//# debugId=9a5d87b5-94d2-5893-8c48-af8db719fa05

package/dist/commands/members.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="9dbfcbea-adf6-5852-b0de-aa6ee4391615")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="09a00ce0-be62-5739-9816-042dda515518")}catch(e){}}();
 import chalk from "chalk";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch, getCompanyUid } from "../utils/vault-api.js";
@@ -267,9 +267,17 @@ export function resolveRevokeTargetToMembershipKey(arg, companyUid) {
         return arg;
     const detected = detectTarget(arg);
     if (detected?.type === "email") {
+        // Active agent guest memberships are personUid-keyed (agt_…#cmp_…), not
+        // email-keyed. Map machine emails to that key so revoke works after invite.
+        if (detected.isAgent) {
+            const local = detected.value.split("@")[0] ?? "";
+            const m = local.match(/^agt-(.+)$/i);
+            if (m)
+                return `agt_${m[1].toUpperCase()}#${companyUid}`;
+        }
         return `email:${detected.value}#${companyUid}`;
     }
-    if (detected?.type === "person") {
+    if (detected?.type === "person" || detected?.type === "agent") {
         return `${detected.value}#${companyUid}`;
     }
     return arg;
@@ -623,4 +631,4 @@ export function registerMembersCommand(program) {
     });
 }
 //# sourceMappingURL=members.js.map
-//# debugId=9dbfcbea-adf6-5852-b0de-aa6ee4391615
+//# debugId=09a00ce0-be62-5739-9816-042dda515518

package/dist/commands/outposts.d.ts

@@ -21,11 +21,14 @@
  * and status routes that exist. Renaming an Outpost is not a backend capability.
  */
 import { Command } from "commander";
+import { type BillingErrorPayload } from "../utils/billing-gate.js";
 /** A non-2xx from the `/outpost/*` control plane. Carries status + `step`. */
 export declare class OutpostHttpError extends Error {
     status: number;
     step?: string;
-    constructor(status: number, message: string, step?: string);
+    /** hq-pro's billing envelope on a `402 billing_required` provision block. */
+    billing?: BillingErrorPayload;
+    constructor(status: number, message: string, step?: string, billing?: BillingErrorPayload);
 }
 /** Row summary from `GET /outpost/list`. */
 export interface OutpostSummary {
@@ -49,12 +52,47 @@ export declare function outpostRequest<T>(opts: {
     token: string;
     path: string;
     method?: string;
+    body?: Record<string, unknown>;
     query?: Record<string, string>;
 }): Promise<T>;
+/**
+ * Provision the caller's Outpost. Sends the cached Cognito refresh token so the
+ * box can authenticate AS the caller (the same body the console's
+ * `provisionMyOutpost` sends). Idempotent server-side: a caller already at their
+ * per-person cap gets their existing box back rather than a duplicate. The
+ * refresh token is sent over HTTPS and NEVER printed.
+ */
+export declare function provisionOutpost(token: string, input: {
+    refreshToken: string;
+    clientIp?: string;
+    diskSizeGb?: number;
+    agentRuntime?: "claude" | "codex";
+}): Promise<Record<string, unknown>>;
 export declare function listOutposts(token: string): Promise<OutpostSummary[]>;
 export declare function getOutpostStatus(token: string, outpostId?: string): Promise<Record<string, unknown>>;
 export declare function enableCodex(token: string, outpostId?: string): Promise<Record<string, unknown>>;
 export declare function regenerateLoginUrl(token: string, outpostId?: string): Promise<Record<string, unknown>>;
 export declare function destroyOutpost(token: string, outpostId?: string): Promise<Record<string, unknown>>;
+/** Result of `POST /outpost/exec` — a terminal SSM invocation on the box. */
+export interface OutpostExecResult {
+    ok: true;
+    outpostId: string;
+    instanceId: string;
+    commandId: string;
+    /** SSM invocation status (Success | Failed | Cancelled). */
+    status: string;
+    /** Remote process exit code, or null when SSM reported none. */
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+    /** True when SSM clipped stdout/stderr at its inline output limit. */
+    truncated: boolean;
+}
+/**
+ * Run a one-shot shell command on the caller's Outpost via `POST /outpost/exec`
+ * (server-brokered SSM — no SSH). Throws `OutpostHttpError` on a non-2xx, whose
+ * `step` distinguishes not-ready / platform-unsupported / timeout / ssm.
+ */
+export declare function execOutpost(token: string, command: string, outpostId?: string): Promise<OutpostExecResult>;
 export declare function registerOutpostsCommand(program: Command): void;
 //# sourceMappingURL=outposts.d.ts.map

package/dist/commands/outposts.js

@@ -21,19 +21,24 @@
  * and status routes that exist. Renaming an Outpost is not a backend capability.
  */
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="b01c6828-502e-5f7a-b15c-acafef4fa143")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="067e20d6-0132-565a-8a22-9c27520669d2")}catch(e){}}();
 import chalk from "chalk";
+import { loadCachedTokens } from "@indigoai-us/hq-cloud";
 import { ensureCognitoToken } from "../utils/cognito-session.js";
 import { vaultApiFetch } from "../utils/vault-api.js";
+import { OUTPOST_PRICE_CENTS, confirmChargeOrExit, parseBillingPayload, surfaceBillingRequired, } from "../utils/billing-gate.js";
 /** A non-2xx from the `/outpost/*` control plane. Carries status + `step`. */
 export class OutpostHttpError extends Error {
     status;
     step;
-    constructor(status, message, step) {
+    /** hq-pro's billing envelope on a `402 billing_required` provision block. */
+    billing;
+    constructor(status, message, step, billing) {
         super(message);
         this.name = "OutpostHttpError";
         this.status = status;
         this.step = step;
+        this.billing = billing;
     }
 }
 /**
@@ -52,10 +57,30 @@ export async function outpostRequest(opts) {
             : typeof body.error === "string"
                 ? body.error
                 : res.statusText;
-        throw new OutpostHttpError(res.status, message, body.step);
+        throw new OutpostHttpError(res.status, message, body.step, parseBillingPayload(body));
     }
     return (await res.json());
 }
+/**
+ * Provision the caller's Outpost. Sends the cached Cognito refresh token so the
+ * box can authenticate AS the caller (the same body the console's
+ * `provisionMyOutpost` sends). Idempotent server-side: a caller already at their
+ * per-person cap gets their existing box back rather than a duplicate. The
+ * refresh token is sent over HTTPS and NEVER printed.
+ */
+export async function provisionOutpost(token, input) {
+    return outpostRequest({
+        token,
+        path: "/outpost/provision",
+        method: "POST",
+        body: {
+            refreshToken: input.refreshToken,
+            ...(input.clientIp ? { clientIp: input.clientIp } : {}),
+            ...(input.diskSizeGb ? { diskSizeGb: input.diskSizeGb } : {}),
+            ...(input.agentRuntime ? { agentRuntime: input.agentRuntime } : {}),
+        },
+    });
+}
 export async function listOutposts(token) {
     const data = await outpostRequest({
         token,
@@ -94,6 +119,20 @@ export async function destroyOutpost(token, outpostId) {
         query: outpostId ? { outpostId } : undefined,
     });
 }
+/**
+ * Run a one-shot shell command on the caller's Outpost via `POST /outpost/exec`
+ * (server-brokered SSM — no SSH). Throws `OutpostHttpError` on a non-2xx, whose
+ * `step` distinguishes not-ready / platform-unsupported / timeout / ssm.
+ */
+export async function execOutpost(token, command, outpostId) {
+    return outpostRequest({
+        token,
+        path: "/outpost/exec",
+        method: "POST",
+        body: { command },
+        query: outpostId ? { outpostId } : undefined,
+    });
+}
 // ---------------------------------------------------------------------------
 // Command registration
 // ---------------------------------------------------------------------------
@@ -117,6 +156,68 @@ export function registerOutpostsCommand(program) {
     const outposts = program
         .command("outposts")
         .description("Manage your personal HQ Outposts (EC2 boxes)");
+    outposts
+        .command("provision")
+        .alias("create")
+        .description("Provision a new Outpost ($80/month — requires --yes)")
+        .option("--runtime <runtime>", "Agent runtime: claude | codex (default claude)")
+        .option("--disk <gb>", "Root disk size in GB (EC2 only)")
+        .option("--client-ip <ip>", "Your public IP for the box's SSH ingress (optional; server derives it otherwise)")
+        .option("--yes", "Confirm the $80/month charge (required to provision)")
+        .action(async function (opts) {
+        try {
+            const agentRuntime = opts.runtime === "codex"
+                ? "codex"
+                : opts.runtime
+                    ? "claude"
+                    : undefined;
+            let diskSizeGb;
+            if (opts.disk !== undefined) {
+                diskSizeGb = Number(opts.disk);
+                if (!Number.isFinite(diskSizeGb) || diskSizeGb <= 0) {
+                    console.error(chalk.red(`Invalid --disk '${opts.disk}': must be a positive number of GB.`));
+                    process.exit(1);
+                }
+            }
+            // Paid gate: print the monthly cost and require --yes before any call.
+            confirmChargeOrExit({
+                resource: "Outpost",
+                unitCents: OUTPOST_PRICE_CENTS,
+                yes: opts.yes,
+            });
+            // The box authenticates AS the caller using the cached refresh token —
+            // the same body the console sends. Never printed.
+            const refreshToken = loadCachedTokens()?.refreshToken;
+            if (!refreshToken) {
+                console.error(chalk.red("No cached session found — run `hq login` first, then re-run."));
+                process.exit(1);
+            }
+            const token = await ensureCognitoToken();
+            try {
+                await provisionOutpost(token, {
+                    refreshToken,
+                    ...(opts.clientIp ? { clientIp: opts.clientIp } : {}),
+                    ...(diskSizeGb ? { diskSizeGb } : {}),
+                    ...(agentRuntime ? { agentRuntime } : {}),
+                });
+                console.log(chalk.green("Provisioning started for your Outpost."));
+                console.log(chalk.dim("Track it: hq outposts status"));
+            }
+            catch (err) {
+                // No card on file → surface the shareable payment link, not an opaque 402.
+                if (err instanceof OutpostHttpError &&
+                    err.status === 402 &&
+                    err.billing) {
+                    await surfaceBillingRequired(token, err.billing);
+                    process.exit(1);
+                }
+                throw err;
+            }
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
     outposts
         .command("list")
         .description("List every Outpost you own")
@@ -180,6 +281,45 @@ export function registerOutpostsCommand(program) {
             fail(err);
         }
     });
+    outposts
+        .command("exec <command...>")
+        .description("Run a shell command on an Outpost and print its output (use -- before flags meant for the remote command)")
+        .option("--id <outpostId>", "Outpost id (defaults to your primary box)")
+        .option("--json", "Emit raw JSON")
+        .action(async function (commandParts, opts) {
+        try {
+            const command = commandParts.join(" ").trim();
+            if (!command) {
+                console.error(chalk.red("No command given. Usage: hq outposts exec -- <command>"));
+                process.exit(1);
+            }
+            const token = await ensureCognitoToken();
+            const result = await execOutpost(token, command, opts.id);
+            if (opts.json) {
+                process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+            }
+            else {
+                // Stream the remote streams to ours so the command feels local, then
+                // exit with the remote exit code.
+                if (result.stdout)
+                    process.stdout.write(result.stdout);
+                if (result.stderr)
+                    process.stderr.write(result.stderr);
+                if (result.truncated) {
+                    console.error(chalk.yellow("(output truncated by SSM's inline limit — redirect to a file on the box for full output)"));
+                }
+                if (result.status !== "Success" && result.exitCode === null) {
+                    console.error(chalk.yellow(`(command ended with SSM status: ${result.status})`));
+                }
+            }
+            // Propagate the remote exit code so `hq outposts exec -- false` exits 1.
+            process.exitCode =
+                typeof result.exitCode === "number" ? result.exitCode : 0;
+        }
+        catch (err) {
+            fail(err);
+        }
+    });
     outposts
         .command("codex-enable")
         .description("Enable (or retry) Codex on an Outpost")
@@ -252,4 +392,4 @@ export function registerOutpostsCommand(program) {
     });
 }
 //# sourceMappingURL=outposts.js.map
-//# debugId=b01c6828-502e-5f7a-b15c-acafef4fa143
+//# debugId=067e20d6-0132-565a-8a22-9c27520669d2

package/dist/main.js

@@ -5,7 +5,7 @@
 // MUST be first: guard the Node version before any dependency that needs a
 // Node 20+ API (e.g. util.styleText) or a newer native ABI is evaluated.
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="d089113e-52b9-5313-a256-63f054d8e72a")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="1cc9f0b6-d8a8-54ea-a85f-44437f67b856")}catch(e){}}();
 import "./node-preflight.js";
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
@@ -56,6 +56,7 @@ import { registerCrmCommand } from "./commands/crm.js";
 import { registerCompanyCommand } from "./commands/company.js";
 import { registerAgentsCommand } from "./commands/agents.js";
 import { registerOutpostsCommand } from "./commands/outposts.js";
+import { registerBillingCommand } from "./commands/billing.js";
 import { registerDbCommand } from "./commands/db.js";
 import { sanitizeArgv } from "./utils/feedback-diagnostics.js";
 import { environmentalFsErrorMessage } from "./utils/environmental-error.js";
@@ -209,6 +210,10 @@ registerAgentsCommand(program);
 // enable Codex on, refresh login for, and destroy your EC2 boxes via the hq-pro
 // /outpost/* control plane.
 registerOutpostsCommand(program);
+// Billing (subcommand group — `hq billing …`). Check subscription/card state and
+// mint a shareable Stripe card-capture link — the client side of the paid-
+// provisioning gate for agents & Outposts.
+registerBillingCommand(program);
 export async function runCli() {
     try {
         Sentry.addBreadcrumb({
@@ -269,4 +274,4 @@ export async function runCli() {
     }
 }
 //# sourceMappingURL=main.js.map
-//# debugId=d089113e-52b9-5313-a256-63f054d8e72a
+//# debugId=1cc9f0b6-d8a8-54ea-a85f-44437f67b856