@indigoai-us/hq-cli 5.62.1 → 5.63.0

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]="d99c091a-e57f-55a6-a666-fdc339c83aab")}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,
@@ -117,6 +142,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")
@@ -252,4 +339,4 @@ export function registerOutpostsCommand(program) {
     });
 }
 //# sourceMappingURL=outposts.js.map
-//# debugId=b01c6828-502e-5f7a-b15c-acafef4fa143
+//# debugId=d99c091a-e57f-55a6-a666-fdc339c83aab

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

package/dist/utils/billing-gate.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Billing gate for paid provisioning (agents & Outposts).
+ *
+ * hq-pro enforces billing server-side: a provision call for a resource whose
+ * payer has no card on file returns `402` with a `billing` payload carrying a
+ * `setup` action that names EXACTLY which checkout endpoint to hit. That
+ * endpoint returns `{ url }` — a Stripe-hosted card-capture link.
+ *
+ * This module wires the client-side experience around that contract:
+ *   1. `confirmChargeOrExit` — print the monthly cost and require `--yes`
+ *      BEFORE any paid provisioning call is made.
+ *   2. `surfaceBillingRequired` — when the backend answers `402 billing_required`,
+ *      mint the card-capture link and print a plain, shareable message instead
+ *      of an opaque failure.
+ *   3. `hq billing checkout` (see commands/billing.ts) reuses `mintPaymentLink`
+ *      to hand out the same link proactively.
+ *
+ * Prices mirror the console's authoritative constants
+ * (hq-console `src/lib/billing-pricing.ts`): amounts are in the smallest
+ * currency unit (US cents) to match Stripe's wire shape.
+ */
+/** Per-Agent monthly list price, in cents ($100.00 / agent / month). */
+export declare const AGENT_PRICE_CENTS = 10000;
+/** Per-Outpost monthly list price, in cents ($80.00 / Outpost / month). */
+export declare const OUTPOST_PRICE_CENTS = 8000;
+/** Render a cents amount as a `$X.YZ` USD string. */
+export declare function formatUsd(cents: number): string;
+/**
+ * The server-supplied "how to add a card" action on a `402 billing_required`.
+ * Mirrors hq-pro `src/billing/activation-billing.ts` `BillingSetupAction` and
+ * the console's `src/lib/billing-setup.ts`.
+ */
+export interface BillingSetupAction {
+    payerType: "company" | "person";
+    path: "/v1/billing/checkout/org" | "/v1/billing/checkout/person";
+    method: "POST";
+    body?: {
+        companyUid?: string;
+    };
+}
+/** The `billing` envelope hq-pro attaches to a billing-blocked provision. */
+export interface BillingErrorPayload {
+    status: string;
+    setup?: BillingSetupAction;
+}
+/** Narrow an unknown value to a usable `BillingSetupAction`. */
+export declare function isBillingSetupAction(value: unknown): value is BillingSetupAction;
+/** Pull a `BillingErrorPayload` out of a decoded hq-pro error body, if present. */
+export declare function parseBillingPayload(body: unknown): BillingErrorPayload | undefined;
+export type PaidResource = "agent" | "Outpost";
+/**
+ * Gate a paid provisioning call behind an explicit, informed `--yes`. Prints the
+ * monthly charge in full prose (this is a paid, outward action — Auto-Clarity)
+ * and exits non-zero when the caller has not passed `--yes`. Returns normally
+ * once approved so the caller proceeds to provision.
+ */
+export declare function confirmChargeOrExit(opts: {
+    resource: PaidResource;
+    unitCents: number;
+    quantity?: number;
+    yes?: boolean;
+}): void;
+/**
+ * Mint a Stripe-hosted card-capture link for a `BillingSetupAction`. Returns the
+ * hosted URL the payer opens to add a card. Throws on a non-2xx (the caller
+ * decides how to surface it) — never swallows.
+ */
+export declare function mintPaymentLink(token: string, setup: BillingSetupAction): Promise<string>;
+/**
+ * The provision was blocked because the payer has no card on file. Mint the
+ * card-capture link the backend pointed us at and print a plain, shareable
+ * message so the user can add a card (or hand the link to whoever owns billing)
+ * and re-run. Returns the URL, or `null` when the server gave no `setup` action
+ * to act on. Never prints tokens or secrets.
+ */
+export declare function surfaceBillingRequired(token: string, billing: BillingErrorPayload): Promise<string | null>;
+//# sourceMappingURL=billing-gate.d.ts.map

package/dist/utils/billing-gate.js

@@ -0,0 +1,127 @@
+/**
+ * Billing gate for paid provisioning (agents & Outposts).
+ *
+ * hq-pro enforces billing server-side: a provision call for a resource whose
+ * payer has no card on file returns `402` with a `billing` payload carrying a
+ * `setup` action that names EXACTLY which checkout endpoint to hit. That
+ * endpoint returns `{ url }` — a Stripe-hosted card-capture link.
+ *
+ * This module wires the client-side experience around that contract:
+ *   1. `confirmChargeOrExit` — print the monthly cost and require `--yes`
+ *      BEFORE any paid provisioning call is made.
+ *   2. `surfaceBillingRequired` — when the backend answers `402 billing_required`,
+ *      mint the card-capture link and print a plain, shareable message instead
+ *      of an opaque failure.
+ *   3. `hq billing checkout` (see commands/billing.ts) reuses `mintPaymentLink`
+ *      to hand out the same link proactively.
+ *
+ * Prices mirror the console's authoritative constants
+ * (hq-console `src/lib/billing-pricing.ts`): amounts are in the smallest
+ * currency unit (US cents) to match Stripe's wire shape.
+ */
+
+!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]="89efd1d4-af26-50e1-b94f-72b1b5533e3f")}catch(e){}}();
+import chalk from "chalk";
+import { vaultApiFetch } from "./vault-api.js";
+/** Per-Agent monthly list price, in cents ($100.00 / agent / month). */
+export const AGENT_PRICE_CENTS = 10_000;
+/** Per-Outpost monthly list price, in cents ($80.00 / Outpost / month). */
+export const OUTPOST_PRICE_CENTS = 8_000;
+/** Render a cents amount as a `$X.YZ` USD string. */
+export function formatUsd(cents) {
+    return `$${(Math.max(0, Math.round(cents)) / 100).toFixed(2)}`;
+}
+/** Narrow an unknown value to a usable `BillingSetupAction`. */
+export function isBillingSetupAction(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const setup = value;
+    const body = setup.body;
+    return ((setup.payerType === "company" || setup.payerType === "person") &&
+        (setup.path === "/v1/billing/checkout/org" ||
+            setup.path === "/v1/billing/checkout/person") &&
+        setup.method === "POST" &&
+        (body === undefined || (typeof body === "object" && body !== null)));
+}
+/** Pull a `BillingErrorPayload` out of a decoded hq-pro error body, if present. */
+export function parseBillingPayload(body) {
+    if (!body || typeof body !== "object")
+        return undefined;
+    const raw = body.billing;
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const status = raw.status;
+    if (typeof status !== "string")
+        return undefined;
+    const setup = raw.setup;
+    return {
+        status,
+        ...(isBillingSetupAction(setup) ? { setup } : {}),
+    };
+}
+/**
+ * Gate a paid provisioning call behind an explicit, informed `--yes`. Prints the
+ * monthly charge in full prose (this is a paid, outward action — Auto-Clarity)
+ * and exits non-zero when the caller has not passed `--yes`. Returns normally
+ * once approved so the caller proceeds to provision.
+ */
+export function confirmChargeOrExit(opts) {
+    const quantity = opts.quantity ?? 1;
+    const total = opts.unitCents * quantity;
+    const each = quantity > 1 ? ` (${formatUsd(opts.unitCents)} each × ${quantity})` : "";
+    const noun = quantity > 1 ? `${opts.resource}s` : opts.resource;
+    const article = /^[aeiou]/i.test(opts.resource) ? "an" : "a";
+    const subject = quantity > 1 ? `${quantity} ${noun}` : `${article} ${noun}`;
+    if (!opts.yes) {
+        console.error(chalk.yellow(`Provisioning ${subject} adds a recurring charge of ` +
+            `${formatUsd(total)}/month${each} to the payer on file. This is a ` +
+            `paid resource.\n` +
+            `Re-run with --yes to confirm you want to incur this charge.`));
+        process.exit(1);
+    }
+    console.log(chalk.dim(`Confirmed: ${formatUsd(total)}/month for ${quantity} ${noun}. Provisioning…`));
+}
+/**
+ * Mint a Stripe-hosted card-capture link for a `BillingSetupAction`. Returns the
+ * hosted URL the payer opens to add a card. Throws on a non-2xx (the caller
+ * decides how to surface it) — never swallows.
+ */
+export async function mintPaymentLink(token, setup) {
+    const res = await vaultApiFetch({
+        token,
+        path: setup.path,
+        method: "POST",
+        body: setup.body?.companyUid ? { companyUid: setup.body.companyUid } : {},
+    });
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        throw new Error(`Failed to mint a payment link: ${body.error ?? body.message ?? res.statusText}`);
+    }
+    const data = (await res.json());
+    if (!data.url) {
+        throw new Error("Payment link response did not include a checkout URL.");
+    }
+    return data.url;
+}
+/**
+ * The provision was blocked because the payer has no card on file. Mint the
+ * card-capture link the backend pointed us at and print a plain, shareable
+ * message so the user can add a card (or hand the link to whoever owns billing)
+ * and re-run. Returns the URL, or `null` when the server gave no `setup` action
+ * to act on. Never prints tokens or secrets.
+ */
+export async function surfaceBillingRequired(token, billing) {
+    if (!billing.setup) {
+        console.error(chalk.yellow("Provisioning is blocked on billing, but the server didn't return a " +
+            "payment link. Add a card in the console billing page, then re-run."));
+        return null;
+    }
+    const url = await mintPaymentLink(token, billing.setup);
+    console.log(chalk.yellow("No card on file — provisioning is blocked until one is added."));
+    console.log("Add a card here (safe to share with whoever owns billing):\n  " +
+        chalk.cyan(url));
+    console.log(chalk.dim("Once a card is added, re-run the same command."));
+    return url;
+}
+//# sourceMappingURL=billing-gate.js.map
+//# debugId=89efd1d4-af26-50e1-b94f-72b1b5533e3f

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.62.1",
+  "version": "5.63.0",
   "description": "HQ by Indigo management CLI — modules and cloud sync",
   "main": "dist/index.js",
   "bin": {
@@ -19,7 +19,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@indigoai-us/hq-cloud": "^6.12.1",
+    "@indigoai-us/hq-cloud": "^6.14.2",
     "@indigoai-us/hq-onboarding": "^0.1.0",
     "@sentry/node": "^10.49.0",
     "better-sqlite3": "^12.11.1",

package/src/commands/agents.test.ts

@@ -295,3 +295,87 @@ describe("hq agents status", () => {
     ).rejects.toThrow("process.exit(1)");
   });
 });
+
+describe("hq agents provision (billing gate)", () => {
+  it("refuses without --yes, prints the cost, and makes NO API call", async () => {
+    const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    await expect(
+      run(["agents", "--company", "acme", "provision", "Ops Bot"]),
+    ).rejects.toThrow("process.exit(1)");
+    expect(fetchSpy).not.toHaveBeenCalled();
+    const printed = errSpy.mock.calls
+      .map((c) => c.map(String).join(" "))
+      .join("\n");
+    expect(printed).toMatch(/\$100\.00\/month/);
+  });
+
+  it("POSTs /v1/agents with slugified name + idempotency key when --yes", async () => {
+    fetchSpy.mockResolvedValueOnce(
+      jsonResponse(200, { uid: "agt_new", slug: "ops-bot" }),
+    );
+    await run(["agents", "--company", "acme", "provision", "Ops Bot", "--yes"]);
+    const [url, init] = fetchSpy.mock.calls[0];
+    expect(String(url)).toContain("/v1/agents");
+    expect(init?.method).toBe("POST");
+    const sent = JSON.parse(init?.body as string);
+    expect(sent.companyUid).toBe("cmp_acme");
+    expect(sent.name).toBe("Ops Bot");
+    expect(sent.slug).toBe("ops-bot");
+    expect(sent.codexAuthMode).toBe("subscription");
+    expect(typeof sent.idempotencyKey).toBe("string");
+    expect(sent.idempotencyKey.length).toBeGreaterThan(0);
+  });
+
+  it("mints a card-capture link on 402 billing_required and exits 1", async () => {
+    fetchSpy
+      .mockResolvedValueOnce(
+        jsonResponse(402, {
+          error: "payment required",
+          code: "BILLING_REQUIRED",
+          billing: {
+            status: "billing_required",
+            setup: {
+              payerType: "company",
+              path: "/v1/billing/checkout/org",
+              method: "POST",
+              body: { companyUid: "cmp_acme" },
+            },
+          },
+        }),
+      )
+      .mockResolvedValueOnce(
+        jsonResponse(200, { url: "https://checkout.stripe.com/card" }),
+      );
+
+    const logSpyLocal = vi.spyOn(console, "log").mockImplementation(() => {});
+    await expect(
+      run(["agents", "--company", "acme", "provision", "Ops Bot", "--yes"]),
+    ).rejects.toThrow("process.exit(1)");
+
+    // Second call mints the checkout link the 402 pointed at.
+    expect(String(fetchSpy.mock.calls[1][0])).toContain(
+      "/v1/billing/checkout/org",
+    );
+    expect(JSON.parse(fetchSpy.mock.calls[1][1]?.body as string)).toEqual({
+      companyUid: "cmp_acme",
+    });
+    const printed = logSpyLocal.mock.calls.map((c) => String(c[0])).join("\n");
+    expect(printed).toContain("https://checkout.stripe.com/card");
+  });
+
+  it("requires --api-key-env for --auth-mode apiKey (before any charge)", async () => {
+    await expect(
+      run([
+        "agents",
+        "--company",
+        "acme",
+        "provision",
+        "Ops Bot",
+        "--auth-mode",
+        "apiKey",
+        "--yes",
+      ]),
+    ).rejects.toThrow("process.exit(1)");
+    expect(fetchSpy).not.toHaveBeenCalled();
+  });
+});

package/src/commands/agents.ts

@@ -24,8 +24,16 @@
 
 import { Command } from "commander";
 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,
+  type BillingErrorPayload,
+} from "../utils/billing-gate.js";
 
 /** Reasoning-effort values hq-pro accepts on `runtime-config`. */
 export const VALID_EFFORTS = new Set([
@@ -47,11 +55,19 @@ export const VALID_TIERS = new Set(["default", "priority"]);
 export 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,
+  ) {
     super(message);
     this.name = "AgentsHttpError";
     this.status = status;
     this.code = code;
+    this.billing = billing;
   }
 }
 
@@ -111,11 +127,45 @@ export async function agentsRequest<T>(opts: {
       res.status,
       body.error ?? body.message ?? res.statusText,
       body.code,
+      parseBillingPayload(body),
     );
   }
   return (await res.json()) as T;
 }
 
+/** Slugify an agent name into a lowercase, hyphen-separated slug. */
+export function slugifyAgentName(name: string): string {
+  return name
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+export interface ProvisionAgentInput {
+  companyUid: string;
+  name: string;
+  slug: string;
+  codexAuthMode: "subscription" | "apiKey";
+  provider?: "codex" | "grok";
+  codexApiKey?: string;
+  idempotencyKey: string;
+  title?: string;
+  description?: string;
+}
+
+export async function provisionAgent(
+  token: string,
+  input: ProvisionAgentInput,
+): Promise<{ uid?: string; slug?: string; [key: string]: unknown }> {
+  return agentsRequest({
+    token,
+    path: "/v1/agents",
+    method: "POST",
+    body: input as unknown as Record<string, unknown>,
+  });
+}
+
 export async function listAgents(
   token: string,
   companyUid: string,
@@ -244,6 +294,112 @@ export function registerAgentsCommand(program: Command): void {
     (sub.opts().company as string | undefined) ??
     (agents.opts().company as string | undefined);
 
+  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 (
+      this: Command,
+      name: string,
+      opts: {
+        slug?: string;
+        provider?: string;
+        authMode?: string;
+        apiKeyEnv?: string;
+        title?: string;
+        description?: string;
+        yes?: boolean;
+      },
+    ) {
+      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: string | undefined;
+        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")