@indigoai-us/hq-cli 5.47.13 → 5.47.14

package/dist/commands/api-keys.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+export declare function registerApiKeysCommand(program: Command): Command;
+//# sourceMappingURL=api-keys.d.ts.map

package/dist/commands/api-keys.js

@@ -0,0 +1,198 @@
+
+!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]="c9f6fe34-9e38-5001-97b7-14b35c956330")}catch(e){}}();
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { getCompanyUid, vaultApiFetch } from "./secrets.js";
+function collectRepeatedOption(value, previous) {
+    return [...previous, value];
+}
+function formatMaybe(value) {
+    return value ?? "-";
+}
+function formatPrefixes(prefixes) {
+    return prefixes.length > 0 ? prefixes.join(", ") : "-";
+}
+function parsePermission(value) {
+    if (value === "read" || value === "write" || value === "admin") {
+        return value;
+    }
+    throw new Error(`Invalid permission '${value}'. Use one of: read, write, admin.`);
+}
+function parseExpires(expires) {
+    if (expires === undefined)
+        return undefined;
+    if (Number.isNaN(Date.parse(expires))) {
+        throw new Error(`Invalid --expires value '${expires}'. Use an ISO-8601 timestamp.`);
+    }
+    return expires;
+}
+async function readApiError(res, action) {
+    const body = (await res.json().catch(() => ({})));
+    const message = typeof body.message === "string"
+        ? body.message
+        : typeof body.error === "string"
+            ? body.error
+            : res.statusText;
+    if (res.status === 401) {
+        return "Not authenticated - please run `hq login`";
+    }
+    if (res.status === 403) {
+        return `Not authorized to ${action}`;
+    }
+    if (res.status === 404) {
+        return message || "API key not found";
+    }
+    if (res.status >= 500) {
+        return `Server error: ${message}`;
+    }
+    return message || `Request failed (${res.status})`;
+}
+function renderApiKeysTable(apiKeys) {
+    const rows = apiKeys.map((apiKey) => ({
+        keyId: apiKey.keyId,
+        name: apiKey.name,
+        permission: apiKey.scope.permission,
+        prefixes: formatPrefixes(apiKey.scope.allowedPrefixes),
+        status: apiKey.status,
+        lastUsedAt: formatMaybe(apiKey.lastUsedAt),
+        expiresAt: formatMaybe(apiKey.expiresAt),
+    }));
+    const keyIdWidth = Math.max(6, ...rows.map((row) => row.keyId.length));
+    const nameWidth = Math.max(4, ...rows.map((row) => row.name.length));
+    const permissionWidth = Math.max(10, ...rows.map((row) => row.permission.length));
+    const prefixesWidth = Math.max(8, ...rows.map((row) => row.prefixes.length));
+    const statusWidth = Math.max(6, ...rows.map((row) => row.status.length));
+    const lastUsedWidth = Math.max(11, ...rows.map((row) => row.lastUsedAt.length));
+    const expiresWidth = Math.max(10, ...rows.map((row) => row.expiresAt.length));
+    const header = [
+        "KEY ID".padEnd(keyIdWidth),
+        "NAME".padEnd(nameWidth),
+        "PERMISSION".padEnd(permissionWidth),
+        "PREFIXES".padEnd(prefixesWidth),
+        "STATUS".padEnd(statusWidth),
+        "LAST USED".padEnd(lastUsedWidth),
+        "EXPIRES".padEnd(expiresWidth),
+    ].join("  ");
+    console.log(chalk.bold(header));
+    for (const row of rows) {
+        console.log([
+            row.keyId.padEnd(keyIdWidth),
+            row.name.padEnd(nameWidth),
+            row.permission.padEnd(permissionWidth),
+            row.prefixes.padEnd(prefixesWidth),
+            row.status.padEnd(statusWidth),
+            row.lastUsedAt.padEnd(lastUsedWidth),
+            row.expiresAt.padEnd(expiresWidth),
+        ].join("  "));
+    }
+}
+export function registerApiKeysCommand(program) {
+    const apiKeys = program
+        .command("api-keys")
+        .description("Manage vault API keys for CI and automation")
+        .option("--company <slug>", "Company slug (resolves to companyUid)");
+    apiKeys
+        .command("create")
+        .description("Create a new API key")
+        .requiredOption("--name <label>", "Human-readable label for the API key")
+        .option("--scope <prefix>", "Allowed prefix (repeatable)", collectRepeatedOption, [])
+        .option("--permission <level>", "Permission level: read | write | admin", "read")
+        .option("--expires <ISO8601>", "Optional ISO-8601 expiry timestamp")
+        .action(async (opts) => {
+        try {
+            if (opts.scope.length === 0) {
+                console.error(chalk.red("Error: at least one --scope <prefix> is required."));
+                process.exit(1);
+            }
+            const permission = parsePermission(opts.permission);
+            const expiresAt = parseExpires(opts.expires);
+            const token = await ensureCognitoToken();
+            const companyUid = await getCompanyUid(token, apiKeys.opts().company);
+            const res = await vaultApiFetch({
+                token,
+                path: "/v1/api-keys",
+                method: "POST",
+                body: {
+                    companyUid,
+                    name: opts.name,
+                    allowedPrefixes: opts.scope,
+                    permission,
+                    ...(expiresAt ? { expiresAt } : {}),
+                },
+            });
+            if (!res.ok) {
+                throw new Error(await readApiError(res, "create API keys"));
+            }
+            const data = (await res.json());
+            console.log(chalk.green("API key created."));
+            console.log(chalk.yellow("Store this key now - it won't be shown again:"));
+            console.log(`\n  ${data.key.value}\n`);
+            console.log(chalk.bold("Metadata"));
+            console.log(`  Key ID: ${data.apiKey.keyId}`);
+            console.log(`  Name: ${data.apiKey.name}`);
+            console.log(`  Company: ${data.apiKey.companyUid}`);
+            console.log(`  Permission: ${data.apiKey.scope.permission}`);
+            console.log(`  Prefixes: ${formatPrefixes(data.apiKey.scope.allowedPrefixes)}`);
+            console.log(`  Status: ${data.apiKey.status}`);
+            console.log(`  Created: ${data.apiKey.createdAt}`);
+            console.log(`  Last used: ${formatMaybe(data.apiKey.lastUsedAt)}`);
+            console.log(`  Expires: ${formatMaybe(data.apiKey.expiresAt)}`);
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    apiKeys
+        .command("list")
+        .description("List API keys for a company")
+        .action(async () => {
+        try {
+            const token = await ensureCognitoToken();
+            const companyUid = await getCompanyUid(token, apiKeys.opts().company);
+            const res = await vaultApiFetch({
+                token,
+                path: "/v1/api-keys",
+                query: { companyUid },
+            });
+            if (!res.ok) {
+                throw new Error(await readApiError(res, "list API keys"));
+            }
+            const data = (await res.json());
+            if (data.apiKeys.length === 0) {
+                console.log(chalk.dim("No API keys found."));
+                return;
+            }
+            renderApiKeysTable(data.apiKeys);
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    apiKeys
+        .command("revoke <keyId>")
+        .description("Revoke an API key")
+        .action(async (keyId) => {
+        try {
+            const token = await ensureCognitoToken();
+            const res = await vaultApiFetch({
+                token,
+                path: `/v1/api-keys/${encodeURIComponent(keyId)}/revoke`,
+                method: "POST",
+            });
+            if (!res.ok) {
+                throw new Error(await readApiError(res, "revoke this API key"));
+            }
+            const data = (await res.json());
+            console.log(chalk.green(`Revoked API key '${data.apiKey.keyId}'`));
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+    });
+    return apiKeys;
+}
+//# sourceMappingURL=api-keys.js.map
+//# debugId=c9f6fe34-9e38-5001-97b7-14b35c956330

package/dist/index.js

@@ -3,7 +3,7 @@
  * HQ CLI - Module management, package management, and cloud sync for HQ
  */
 
-!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]="6fa5c878-2930-5b94-bc7c-5deea8795218")}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]="964b8c71-056c-51fb-893a-d51f8f6ad5d9")}catch(e){}}();
 import { Command } from "commander";
 import { initSentry, Sentry } from "./sentry.js";
 import { registerAddCommand } from "./commands/add.js";
@@ -28,6 +28,7 @@ import { registerPublishCommand } from "./commands/publish.js";
 import { registerCreatorsCommand } from "./commands/creators.js";
 import { registerTeamSyncCommand } from "./commands/team-sync.js";
 import { registerAuthCommands } from "./commands/auth.js";
+import { registerApiKeysCommand } from "./commands/api-keys.js";
 import { registerSecretsCommand } from "./commands/secrets.js";
 import { registerRunCommand } from "./commands/run.js";
 import { registerGroupsCommand } from "./commands/groups.js";
@@ -117,6 +118,8 @@ registerWhoamiCommand(program);
 registerAuthCommands(program);
 // Secrets management (subcommand group — hq secrets set|get|list|delete|exec|generate-link|cache)
 registerSecretsCommand(program);
+// API key management (subcommand group — hq api-keys create|list|revoke)
+registerApiKeysCommand(program);
 // Schema-driven dev runner — hq run [options] -- <cmd>
 registerRunCommand(program);
 // Groups management (subcommand group — hq groups create|delete|add|remove|list|members)
@@ -177,4 +180,4 @@ registerRescueCommand(program);
     }
 })();
 //# sourceMappingURL=index.js.map
-//# debugId=6fa5c878-2930-5b94-bc7c-5deea8795218
+//# debugId=964b8c71-056c-51fb-893a-d51f8f6ad5d9

package/package.json

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

package/src/commands/api-keys.test.ts

@@ -0,0 +1,217 @@
+import {
+  afterEach,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+  type MockInstance,
+} from "vitest";
+
+vi.mock("../utils/cognito-session.js", async (importOriginal) => {
+  const original = (await importOriginal()) as Record<string, unknown>;
+  return {
+    ...original,
+    ensureCognitoToken: vi.fn(async () => "test-token"),
+  };
+});
+
+vi.mock("./secrets.js", async (importOriginal) => {
+  const original = (await importOriginal()) as Record<string, unknown>;
+  return {
+    ...original,
+    getCompanyUid: vi.fn(async () => "cmp_acme"),
+    vaultApiFetch: vi.fn(),
+  };
+});
+
+import { Command } from "commander";
+import { registerApiKeysCommand } from "./api-keys.js";
+import { getCompanyUid, vaultApiFetch } from "./secrets.js";
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function buildProgram(): Command {
+  const program = new Command();
+  program.exitOverride();
+  program.configureOutput({
+    writeOut: () => undefined,
+    writeErr: () => undefined,
+  });
+  registerApiKeysCommand(program);
+  return program;
+}
+
+let logSpy: MockInstance<typeof console.log>;
+let errSpy: MockInstance<typeof console.error>;
+let exitSpy: MockInstance<typeof process.exit>;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  logSpy = vi.spyOn(console, "log").mockImplementation(() => undefined);
+  errSpy = vi.spyOn(console, "error").mockImplementation(() => undefined);
+  exitSpy = vi
+    .spyOn(process, "exit")
+    .mockImplementation(((code?: number) => {
+      throw new Error(`__EXIT__:${code ?? 0}`);
+    }) as never);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("hq api-keys create", () => {
+  it("POSTs the expected body and prints the raw key exactly once", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      jsonResponse({
+        apiKey: {
+          keyId: "key_123",
+          companyUid: "cmp_acme",
+          name: "CI key",
+          scope: {
+            allowedPrefixes: ["HQ_PRO/HQ_PROD", "HQ_PRO/HQ_DEV"],
+            permission: "read",
+          },
+          status: "active",
+          createdAt: "2026-06-19T12:00:00.000Z",
+          lastUsedAt: null,
+          expiresAt: "2026-07-01T00:00:00.000Z",
+        },
+        key: { value: "hqk_test_secret_value" },
+      }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync(
+      [
+        "api-keys",
+        "create",
+        "--company",
+        "indigo",
+        "--name",
+        "CI key",
+        "--scope",
+        "HQ_PRO/HQ_PROD",
+        "--scope",
+        "HQ_PRO/HQ_DEV",
+        "--permission",
+        "read",
+        "--expires",
+        "2026-07-01T00:00:00.000Z",
+      ],
+      { from: "user" },
+    );
+
+    expect(getCompanyUid).toHaveBeenCalledWith("test-token", "indigo");
+    expect(vaultApiFetch).toHaveBeenCalledWith({
+      token: "test-token",
+      path: "/v1/api-keys",
+      method: "POST",
+      body: {
+        companyUid: "cmp_acme",
+        name: "CI key",
+        allowedPrefixes: ["HQ_PRO/HQ_PROD", "HQ_PRO/HQ_DEV"],
+        permission: "read",
+        expiresAt: "2026-07-01T00:00:00.000Z",
+      },
+    });
+
+    const printed = logSpy.mock.calls
+      .map((call) => call.map((value) => String(value)).join(" "))
+      .join("\n");
+    expect(printed).toContain("Store this key now");
+    expect(printed.match(/hqk_test_secret_value/g)?.length ?? 0).toBe(1);
+    expect(errSpy).not.toHaveBeenCalled();
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("hq api-keys list", () => {
+  it("renders metadata rows and never prints any key value", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      jsonResponse({
+        companyUid: "cmp_acme",
+        apiKeys: [
+          {
+            keyId: "key_123",
+            companyUid: "cmp_acme",
+            name: "CI key",
+            scope: {
+              allowedPrefixes: ["HQ_PRO/HQ_PROD", "HQ_PRO/HQ_DEV"],
+              permission: "read",
+            },
+            status: "active",
+            createdAt: "2026-06-19T12:00:00.000Z",
+            lastUsedAt: "2026-06-20T08:00:00.000Z",
+            expiresAt: "2026-07-01T00:00:00.000Z",
+            key: { value: "hqk_should_not_print" },
+          },
+        ],
+      }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync(
+      ["api-keys", "--company", "indigo", "list"],
+      { from: "user" },
+    );
+
+    expect(getCompanyUid).toHaveBeenCalledWith("test-token", "indigo");
+    expect(vaultApiFetch).toHaveBeenCalledWith({
+      token: "test-token",
+      path: "/v1/api-keys",
+      query: { companyUid: "cmp_acme" },
+    });
+
+    const printed = logSpy.mock.calls
+      .map((call) => call.map((value) => String(value)).join(" "))
+      .join("\n");
+    expect(printed).toContain("KEY ID");
+    expect(printed).toContain("key_123");
+    expect(printed).toContain("CI key");
+    expect(printed).toContain("HQ_PRO/HQ_PROD, HQ_PRO/HQ_DEV");
+    expect(printed).not.toContain("hqk_should_not_print");
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+});
+
+describe("hq api-keys revoke", () => {
+  it("POSTs to the revoke route for the provided key id", async () => {
+    vi.mocked(vaultApiFetch).mockResolvedValueOnce(
+      jsonResponse({
+        apiKey: {
+          keyId: "key_123",
+          companyUid: "cmp_acme",
+          name: "CI key",
+          scope: {
+            allowedPrefixes: ["HQ_PRO/HQ_PROD"],
+            permission: "read",
+          },
+          status: "revoked",
+          createdAt: "2026-06-19T12:00:00.000Z",
+          lastUsedAt: null,
+          expiresAt: null,
+        },
+      }),
+    );
+
+    const program = buildProgram();
+    await program.parseAsync(["api-keys", "revoke", "key_123"], {
+      from: "user",
+    });
+
+    expect(vaultApiFetch).toHaveBeenCalledWith({
+      token: "test-token",
+      path: "/v1/api-keys/key_123/revoke",
+      method: "POST",
+    });
+    expect(logSpy).toHaveBeenCalledWith(expect.stringContaining("key_123"));
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+});

package/src/commands/api-keys.ts

@@ -0,0 +1,306 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { getCompanyUid, vaultApiFetch } from "./secrets.js";
+
+type ApiKeyPermission = "read" | "write" | "admin";
+
+interface ApiKeyMetadata {
+  keyId: string;
+  companyUid: string;
+  name: string;
+  scope: {
+    allowedPrefixes: string[];
+    permission: ApiKeyPermission;
+  };
+  status: string;
+  createdAt: string;
+  lastUsedAt?: string | null;
+  expiresAt?: string | null;
+}
+
+interface CreateApiKeyResponse {
+  apiKey: ApiKeyMetadata;
+  key: {
+    value: string;
+  };
+}
+
+interface ListApiKeysResponse {
+  companyUid: string;
+  apiKeys: ApiKeyMetadata[];
+}
+
+interface RevokeApiKeyResponse {
+  apiKey: ApiKeyMetadata;
+}
+
+interface ApiKeysGroupOptions {
+  company?: string;
+}
+
+interface CreateApiKeyOptions {
+  name: string;
+  scope: string[];
+  permission: string;
+  expires?: string;
+}
+
+function collectRepeatedOption(value: string, previous: string[]): string[] {
+  return [...previous, value];
+}
+
+function formatMaybe(value?: string | null): string {
+  return value ?? "-";
+}
+
+function formatPrefixes(prefixes: string[]): string {
+  return prefixes.length > 0 ? prefixes.join(", ") : "-";
+}
+
+function parsePermission(value: string): ApiKeyPermission {
+  if (value === "read" || value === "write" || value === "admin") {
+    return value;
+  }
+  throw new Error(
+    `Invalid permission '${value}'. Use one of: read, write, admin.`,
+  );
+}
+
+function parseExpires(expires?: string): string | undefined {
+  if (expires === undefined) return undefined;
+  if (Number.isNaN(Date.parse(expires))) {
+    throw new Error(
+      `Invalid --expires value '${expires}'. Use an ISO-8601 timestamp.`,
+    );
+  }
+  return expires;
+}
+
+async function readApiError(res: Response, action: string): Promise<string> {
+  const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+  const message =
+    typeof body.message === "string"
+      ? body.message
+      : typeof body.error === "string"
+        ? body.error
+        : res.statusText;
+
+  if (res.status === 401) {
+    return "Not authenticated - please run `hq login`";
+  }
+  if (res.status === 403) {
+    return `Not authorized to ${action}`;
+  }
+  if (res.status === 404) {
+    return message || "API key not found";
+  }
+  if (res.status >= 500) {
+    return `Server error: ${message}`;
+  }
+  return message || `Request failed (${res.status})`;
+}
+
+function renderApiKeysTable(apiKeys: ApiKeyMetadata[]): void {
+  const rows = apiKeys.map((apiKey) => ({
+    keyId: apiKey.keyId,
+    name: apiKey.name,
+    permission: apiKey.scope.permission,
+    prefixes: formatPrefixes(apiKey.scope.allowedPrefixes),
+    status: apiKey.status,
+    lastUsedAt: formatMaybe(apiKey.lastUsedAt),
+    expiresAt: formatMaybe(apiKey.expiresAt),
+  }));
+
+  const keyIdWidth = Math.max(6, ...rows.map((row) => row.keyId.length));
+  const nameWidth = Math.max(4, ...rows.map((row) => row.name.length));
+  const permissionWidth = Math.max(
+    10,
+    ...rows.map((row) => row.permission.length),
+  );
+  const prefixesWidth = Math.max(8, ...rows.map((row) => row.prefixes.length));
+  const statusWidth = Math.max(6, ...rows.map((row) => row.status.length));
+  const lastUsedWidth = Math.max(
+    11,
+    ...rows.map((row) => row.lastUsedAt.length),
+  );
+  const expiresWidth = Math.max(
+    10,
+    ...rows.map((row) => row.expiresAt.length),
+  );
+
+  const header = [
+    "KEY ID".padEnd(keyIdWidth),
+    "NAME".padEnd(nameWidth),
+    "PERMISSION".padEnd(permissionWidth),
+    "PREFIXES".padEnd(prefixesWidth),
+    "STATUS".padEnd(statusWidth),
+    "LAST USED".padEnd(lastUsedWidth),
+    "EXPIRES".padEnd(expiresWidth),
+  ].join("  ");
+  console.log(chalk.bold(header));
+
+  for (const row of rows) {
+    console.log(
+      [
+        row.keyId.padEnd(keyIdWidth),
+        row.name.padEnd(nameWidth),
+        row.permission.padEnd(permissionWidth),
+        row.prefixes.padEnd(prefixesWidth),
+        row.status.padEnd(statusWidth),
+        row.lastUsedAt.padEnd(lastUsedWidth),
+        row.expiresAt.padEnd(expiresWidth),
+      ].join("  "),
+    );
+  }
+}
+
+export function registerApiKeysCommand(program: Command): Command {
+  const apiKeys = program
+    .command("api-keys")
+    .description("Manage vault API keys for CI and automation")
+    .option("--company <slug>", "Company slug (resolves to companyUid)");
+
+  apiKeys
+    .command("create")
+    .description("Create a new API key")
+    .requiredOption("--name <label>", "Human-readable label for the API key")
+    .option(
+      "--scope <prefix>",
+      "Allowed prefix (repeatable)",
+      collectRepeatedOption,
+      [],
+    )
+    .option(
+      "--permission <level>",
+      "Permission level: read | write | admin",
+      "read",
+    )
+    .option("--expires <ISO8601>", "Optional ISO-8601 expiry timestamp")
+    .action(async (opts: CreateApiKeyOptions) => {
+      try {
+        if (opts.scope.length === 0) {
+          console.error(
+            chalk.red("Error: at least one --scope <prefix> is required."),
+          );
+          process.exit(1);
+        }
+
+        const permission = parsePermission(opts.permission);
+        const expiresAt = parseExpires(opts.expires);
+        const token = await ensureCognitoToken();
+        const companyUid = await getCompanyUid(
+          token,
+          (apiKeys.opts() as ApiKeysGroupOptions).company,
+        );
+
+        const res = await vaultApiFetch({
+          token,
+          path: "/v1/api-keys",
+          method: "POST",
+          body: {
+            companyUid,
+            name: opts.name,
+            allowedPrefixes: opts.scope,
+            permission,
+            ...(expiresAt ? { expiresAt } : {}),
+          },
+        });
+
+        if (!res.ok) {
+          throw new Error(await readApiError(res, "create API keys"));
+        }
+
+        const data = (await res.json()) as CreateApiKeyResponse;
+        console.log(chalk.green("API key created."));
+        console.log(
+          chalk.yellow("Store this key now - it won't be shown again:"),
+        );
+        console.log(`\n  ${data.key.value}\n`);
+        console.log(chalk.bold("Metadata"));
+        console.log(`  Key ID: ${data.apiKey.keyId}`);
+        console.log(`  Name: ${data.apiKey.name}`);
+        console.log(`  Company: ${data.apiKey.companyUid}`);
+        console.log(`  Permission: ${data.apiKey.scope.permission}`);
+        console.log(
+          `  Prefixes: ${formatPrefixes(data.apiKey.scope.allowedPrefixes)}`,
+        );
+        console.log(`  Status: ${data.apiKey.status}`);
+        console.log(`  Created: ${data.apiKey.createdAt}`);
+        console.log(`  Last used: ${formatMaybe(data.apiKey.lastUsedAt)}`);
+        console.log(`  Expires: ${formatMaybe(data.apiKey.expiresAt)}`);
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  apiKeys
+    .command("list")
+    .description("List API keys for a company")
+    .action(async () => {
+      try {
+        const token = await ensureCognitoToken();
+        const companyUid = await getCompanyUid(
+          token,
+          (apiKeys.opts() as ApiKeysGroupOptions).company,
+        );
+
+        const res = await vaultApiFetch({
+          token,
+          path: "/v1/api-keys",
+          query: { companyUid },
+        });
+
+        if (!res.ok) {
+          throw new Error(await readApiError(res, "list API keys"));
+        }
+
+        const data = (await res.json()) as ListApiKeysResponse;
+        if (data.apiKeys.length === 0) {
+          console.log(chalk.dim("No API keys found."));
+          return;
+        }
+
+        renderApiKeysTable(data.apiKeys);
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  apiKeys
+    .command("revoke <keyId>")
+    .description("Revoke an API key")
+    .action(async (keyId: string) => {
+      try {
+        const token = await ensureCognitoToken();
+        const res = await vaultApiFetch({
+          token,
+          path: `/v1/api-keys/${encodeURIComponent(keyId)}/revoke`,
+          method: "POST",
+        });
+
+        if (!res.ok) {
+          throw new Error(await readApiError(res, "revoke this API key"));
+        }
+
+        const data = (await res.json()) as RevokeApiKeyResponse;
+        console.log(chalk.green(`Revoked API key '${data.apiKey.keyId}'`));
+      } catch (err) {
+        console.error(
+          chalk.red("Error:"),
+          err instanceof Error ? err.message : String(err),
+        );
+        process.exit(1);
+      }
+    });
+
+  return apiKeys;
+}

package/src/index.ts

@@ -28,6 +28,7 @@ import { registerPublishCommand } from "./commands/publish.js";
 import { registerCreatorsCommand } from "./commands/creators.js";
 import { registerTeamSyncCommand } from "./commands/team-sync.js";
 import { registerAuthCommands } from "./commands/auth.js";
+import { registerApiKeysCommand } from "./commands/api-keys.js";
 import { registerSecretsCommand } from "./commands/secrets.js";
 import { registerRunCommand } from "./commands/run.js";
 import { registerGroupsCommand } from "./commands/groups.js";
@@ -144,6 +145,9 @@ registerAuthCommands(program);
 // Secrets management (subcommand group — hq secrets set|get|list|delete|exec|generate-link|cache)
 registerSecretsCommand(program);
 
+// API key management (subcommand group — hq api-keys create|list|revoke)
+registerApiKeysCommand(program);
+
 // Schema-driven dev runner — hq run [options] -- <cmd>
 registerRunCommand(program);