@headroom-cms/cli 0.1.5

package/dist/index.js

@@ -0,0 +1,1596 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/commands/api-keys.ts
+import * as p from "@clack/prompts";
+
+// src/config.ts
+import { readFile, writeFile, mkdir, access } from "fs/promises";
+import { join } from "path";
+import { execSync } from "child_process";
+import { homedir } from "os";
+function tokenFileName(apiUrl) {
+  return apiUrl.replace(/^https?:\/\//, "").replace(/[^a-zA-Z0-9.-]/g, "_");
+}
+function createConfigStore(baseDir) {
+  const configFile = join(baseDir, "config.json");
+  const tokensDir = join(baseDir, "tokens");
+  const gitignoreFile = join(baseDir, ".gitignore");
+  async function ensureDir() {
+    await mkdir(baseDir, { recursive: true });
+    await mkdir(tokensDir, { recursive: true });
+    try {
+      await access(gitignoreFile);
+    } catch {
+      await writeFile(gitignoreFile, "*\n");
+    }
+  }
+  function tokenPath(apiUrl) {
+    return join(tokensDir, `${tokenFileName(apiUrl)}.json`);
+  }
+  return {
+    async loadConfig() {
+      try {
+        const raw = await readFile(configFile, "utf-8");
+        return JSON.parse(raw);
+      } catch {
+        return null;
+      }
+    },
+    async saveConfig(config) {
+      await ensureDir();
+      await writeFile(configFile, JSON.stringify(config, null, 2) + "\n");
+    },
+    async updateConfig(updates) {
+      const existing = await this.loadConfig() ?? {};
+      const merged = { ...existing, ...updates };
+      await this.saveConfig(merged);
+      return merged;
+    },
+    async loadToken(apiUrl) {
+      try {
+        const raw = await readFile(tokenPath(apiUrl), "utf-8");
+        return JSON.parse(raw);
+      } catch {
+        return null;
+      }
+    },
+    async saveToken(apiUrl, token) {
+      await ensureDir();
+      await writeFile(
+        tokenPath(apiUrl),
+        JSON.stringify(token, null, 2) + "\n",
+        { mode: 384 }
+      );
+    }
+  };
+}
+function findGitRoot() {
+  try {
+    return execSync("git rev-parse --show-toplevel", {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim();
+  } catch {
+    return homedir();
+  }
+}
+var _defaultStore = null;
+function getDefaultStore() {
+  if (!_defaultStore) {
+    _defaultStore = createConfigStore(join(findGitRoot(), ".headroom"));
+  }
+  return _defaultStore;
+}
+var loadConfig = (...args) => getDefaultStore().loadConfig(...args);
+var saveConfig = (...args) => getDefaultStore().saveConfig(...args);
+var updateConfig = (...args) => getDefaultStore().updateConfig(...args);
+var loadToken = (...args) => getDefaultStore().loadToken(...args);
+var saveToken = (...args) => getDefaultStore().saveToken(...args);
+
+// src/context.ts
+import { HeadroomAdminClient } from "@headroom-cms/admin-api";
+
+// src/output.ts
+import { HeadroomApiError } from "@headroom-cms/admin-api";
+
+// src/table.ts
+import pc from "picocolors";
+var DEFAULT_MAX_WIDTH = 40;
+function formatTable(rows, columns) {
+  const cellValues = rows.map(
+    (row) => columns.map((col) => {
+      const raw = row[col.key];
+      if (col.format) return col.format(raw);
+      return raw == null ? "" : String(raw);
+    })
+  );
+  const widths = columns.map((col, i) => {
+    const maxContent = Math.max(
+      col.header.length,
+      ...cellValues.map((vals) => vals[i].length)
+    );
+    const limit = col.width ?? DEFAULT_MAX_WIDTH;
+    return Math.min(maxContent, limit);
+  });
+  const truncate = (s, w) => {
+    if (s.length <= w) return s.padEnd(w);
+    return s.slice(0, w - 1) + "\u2026";
+  };
+  const header = columns.map((col, i) => pc.bold(truncate(col.header, widths[i]))).join("  ");
+  const dataLines = cellValues.map(
+    (vals) => vals.map((v, i) => truncate(v, widths[i])).join("  ")
+  );
+  return [header, ...dataLines].join("\n");
+}
+function formatTimestamp(value) {
+  if (typeof value === "number" && value > 0) {
+    return new Date(value).toISOString().slice(0, 10);
+  }
+  return String(value ?? "");
+}
+
+// src/output.ts
+var quietMode = false;
+var debugEnabled = false;
+var tableMode = false;
+function setQuiet(quiet) {
+  quietMode = quiet;
+}
+function setDebug(enabled) {
+  debugEnabled = enabled;
+}
+function setTable(table) {
+  tableMode = table;
+}
+function exitCodeForError(err) {
+  if (err instanceof HeadroomApiError) {
+    if (err.status === 401) return 3;
+    return err.status >= 500 ? 2 : 1;
+  }
+  return 3;
+}
+function outputJson(data) {
+  if (quietMode) return;
+  process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+}
+function outputList(data, columns) {
+  if (quietMode) return;
+  if (tableMode) {
+    process.stdout.write(formatTable(data, columns) + "\n");
+  } else {
+    process.stdout.write(JSON.stringify(data, null, 2) + "\n");
+  }
+}
+function outputError(err) {
+  if (err instanceof Error) {
+    const obj = { error: err.message };
+    if ("status" in err) obj.status = err.status;
+    if ("code" in err) obj.code = err.code;
+    process.stderr.write(JSON.stringify(obj) + "\n");
+  } else {
+    process.stderr.write(JSON.stringify({ error: String(err) }) + "\n");
+  }
+}
+function debugLog(message) {
+  if (!debugEnabled) return;
+  process.stderr.write(`[debug] ${message}
+`);
+}
+
+// src/context.ts
+var RefreshingTokenProvider = class {
+  tokenData;
+  apiUrl;
+  constructor(apiUrl, tokenData) {
+    this.apiUrl = apiUrl;
+    this.tokenData = tokenData;
+  }
+  async getToken() {
+    if (this.tokenData.expiresAt && Date.now() > this.tokenData.expiresAt - 6e4) {
+      await this.refresh();
+    }
+    return this.tokenData.accessToken;
+  }
+  async onUnauthorized() {
+    await this.refresh();
+    return this.tokenData.accessToken;
+  }
+  async refresh() {
+    const res = await fetch(`${this.apiUrl}/auth/refresh`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ refreshToken: this.tokenData.refreshToken })
+    });
+    if (!res.ok) {
+      throw new Error("Token expired. Run: headroom login <api-url>");
+    }
+    const body = await res.json();
+    this.tokenData = {
+      ...this.tokenData,
+      accessToken: body.accessToken,
+      expiresAt: Date.now() + body.expiresIn * 1e3
+    };
+    await saveToken(this.apiUrl, this.tokenData);
+  }
+};
+async function resolveAuth(opts) {
+  const config = await loadConfig();
+  if (!config) {
+    throw new Error("Not logged in. Run: headroom login <api-url>");
+  }
+  const apiUrl = opts.apiUrl ?? config.apiUrl;
+  const tokenData = await loadToken(apiUrl);
+  if (!tokenData) {
+    throw new Error("No token found. Run: headroom login <api-url>");
+  }
+  const tokenProvider = new RefreshingTokenProvider(apiUrl, tokenData);
+  const client = new HeadroomAdminClient(apiUrl, tokenProvider);
+  if (opts.debug) {
+    const origApiFetch = client.apiFetch.bind(client);
+    client.apiFetch = async (path, options) => {
+      const method = options?.method ?? "GET";
+      debugLog(`\u2192 ${method} ${apiUrl}${path}`);
+      if (options?.body) debugLog(`  body: ${String(options.body).slice(0, 500)}`);
+      try {
+        const result = await origApiFetch(path, options);
+        debugLog(`\u2190 OK`);
+        return result;
+      } catch (err) {
+        debugLog(`\u2190 ERROR: ${err instanceof Error ? err.message : String(err)}`);
+        throw err;
+      }
+    };
+  }
+  return { config, token: tokenData, apiUrl, client };
+}
+async function resolveAuthContext(opts) {
+  return resolveAuth(opts);
+}
+async function resolveContext(opts) {
+  const auth = await resolveAuth(opts);
+  const site = opts.site ?? auth.config.activeSite;
+  if (!site) {
+    throw new Error("No site selected. Run: headroom site <host>");
+  }
+  return { ...auth, site };
+}
+
+// src/stdin.ts
+async function readJsonPayload(opts, commandName) {
+  if (opts.data) {
+    try {
+      return JSON.parse(opts.data);
+    } catch {
+      throw new Error(`Invalid JSON in --data: ${opts.data.slice(0, 100)}`);
+    }
+  }
+  if (process.stdin.isTTY) {
+    throw new Error(
+      `No input provided. Pass JSON via --data or pipe to stdin.
+Run: headroom ${commandName} --help`
+    );
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  if (!raw) {
+    throw new Error("Empty stdin \u2014 expected JSON input.");
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new Error(`Invalid JSON from stdin: ${raw.slice(0, 100)}`);
+  }
+}
+
+// src/commands/api-keys.ts
+var API_KEY_COLUMNS = [
+  { key: "keyId", header: "ID", width: 26 },
+  { key: "label", header: "LABEL", width: 30 },
+  { key: "prefix", header: "PREFIX", width: 12 },
+  { key: "createdAt", header: "CREATED", width: 12, format: formatTimestamp }
+];
+function registerApiKeysCommand(program2) {
+  const apiKeys = program2.command("api-keys").description("Manage API keys");
+  apiKeys.command("list").description("List API keys for the active site").action(async () => {
+    const ctx = await resolveContext(apiKeys.optsWithGlobals());
+    const result = await ctx.client.listApiKeys(ctx.site);
+    outputList(result, API_KEY_COLUMNS);
+  });
+  apiKeys.command("create").description("Create a new API key (plaintext key shown only once)").option("--data <json>", 'JSON payload: { label: "key-name" }').action(async (opts) => {
+    const ctx = await resolveContext(apiKeys.optsWithGlobals());
+    const payload = await readJsonPayload(opts, "api-keys create");
+    if (!payload.label) {
+      throw new Error("Payload must include 'label' field.");
+    }
+    const result = await ctx.client.createApiKey(ctx.site, payload.label);
+    outputJson(result);
+  });
+  apiKeys.command("update").description("Update an API key label").argument("<id>", "API key ID").option("--data <json>", 'JSON payload: { label: "new-name" }').action(async (id, opts) => {
+    const ctx = await resolveContext(apiKeys.optsWithGlobals());
+    const payload = await readJsonPayload(opts, "api-keys update");
+    if (!payload.label) {
+      throw new Error("Payload must include 'label' field.");
+    }
+    await ctx.client.updateApiKey(ctx.site, id, payload.label);
+    outputJson({ updated: id });
+  });
+  apiKeys.command("delete").description("Delete an API key").argument("<id>", "API key ID").option("--force", "skip confirmation prompt").action(async (id, opts) => {
+    if (!opts.force) {
+      if (!process.stdin.isTTY) {
+        throw new Error("Use --force to delete non-interactively.");
+      }
+      const confirmed = await p.confirm({
+        message: `Delete API key ${id}? This cannot be undone.`
+      });
+      if (p.isCancel(confirmed) || !confirmed) {
+        process.exit(0);
+      }
+    }
+    const ctx = await resolveContext(apiKeys.optsWithGlobals());
+    await ctx.client.deleteApiKey(ctx.site, id);
+    outputJson({ deleted: id });
+  });
+}
+
+// src/commands/audit.ts
+var AUDIT_COLUMNS = [
+  { key: "action", header: "ACTION", width: 25 },
+  { key: "adminId", header: "ADMIN", width: 30 },
+  { key: "resourceType", header: "RESOURCE", width: 15 },
+  { key: "resourceId", header: "RESOURCE ID", width: 26 },
+  { key: "createdAt", header: "TIME", width: 12, format: formatTimestamp }
+];
+function registerAuditCommand(program2) {
+  const audit = program2.command("audit").description("View audit log");
+  audit.command("list").description("List audit events").option("--action <action>", "filter by action (e.g. content.published)").option("--admin <id>", "filter by admin ID").option("--before <timestamp>", "show events before this epoch-ms timestamp", parseInt).option("--limit <n>", "max results (default 50, max 100)", parseInt).action(async (opts) => {
+    const globalOpts = audit.optsWithGlobals();
+    const ctx = await resolveContext(globalOpts);
+    const result = await ctx.client.listAuditEvents(ctx.site, {
+      action: opts.action,
+      admin: opts.admin,
+      before: opts.before,
+      limit: opts.limit
+    });
+    if (globalOpts.table) {
+      outputList(
+        result.items,
+        AUDIT_COLUMNS
+      );
+      if (result.hasMore) {
+        process.stderr.write(
+          "(more results available \u2014 use --before or JSON mode for pagination)\n"
+        );
+      }
+    } else {
+      outputJson(result);
+    }
+  });
+}
+
+// src/commands/block-types.ts
+import * as p2 from "@clack/prompts";
+
+// src/introspection.ts
+import pc2 from "picocolors";
+function describeField(field) {
+  const opts = field.options ?? {};
+  const type = field.type;
+  let constraints = {};
+  let children;
+  switch (type) {
+    case "text":
+    case "textarea":
+    case "url":
+    case "email":
+    case "date":
+      if (opts.placeholder != null) constraints.placeholder = opts.placeholder;
+      if (opts.maxLength != null) constraints.maxLength = opts.maxLength;
+      break;
+    case "number":
+      if (opts.min != null) constraints.min = opts.min;
+      if (opts.max != null) constraints.max = opts.max;
+      if (opts.step != null) constraints.step = opts.step;
+      break;
+    case "select":
+      if (opts.choices != null) constraints.choices = opts.choices;
+      break;
+    case "media":
+      if (opts.allowedTypes != null) constraints.allowedTypes = opts.allowedTypes;
+      if (opts.folder != null) constraints.folder = opts.folder;
+      if (opts.maxSize != null) constraints.maxSize = opts.maxSize;
+      if (opts.multiple != null) constraints.multiple = opts.multiple;
+      break;
+    case "content":
+      if (opts.collections != null) constraints.collections = opts.collections;
+      if (opts.multiple != null) constraints.multiple = opts.multiple;
+      break;
+    case "array":
+      if (Array.isArray(opts.itemFields)) {
+        children = opts.itemFields.map(describeField);
+      }
+      break;
+    case "container":
+      if (Array.isArray(opts.fields)) {
+        children = opts.fields.map(describeField);
+      }
+      break;
+  }
+  const noRequired = type === "boolean" || type === "blocks";
+  const required = noRequired ? false : !!opts.required;
+  const desc = { name: field.name, type, label: field.label, required, constraints };
+  if (children) desc.children = children;
+  return desc;
+}
+function describeCollection(collection) {
+  const fields = (collection.fields ?? []).map(describeField);
+  const desc = {
+    name: collection.name,
+    label: collection.label,
+    singleton: !!collection.singleton,
+    fields
+  };
+  if (collection.mode) desc.mode = collection.mode;
+  if (collection.relationships && collection.relationships.length > 0) {
+    desc.relationships = collection.relationships.map((r) => ({
+      name: r.name,
+      label: r.label,
+      targetCollection: r.targetCollection,
+      multiple: r.multiple
+    }));
+  }
+  return desc;
+}
+function describeBlockType(blockType) {
+  const fields = (blockType.fields ?? []).map(describeField);
+  return { name: blockType.name, label: blockType.label, fields };
+}
+function generateExample(fields) {
+  const result = {};
+  for (const field of fields) {
+    result[field.name] = exampleValue(field);
+  }
+  return result;
+}
+function exampleValue(field) {
+  const opts = field.options ?? {};
+  switch (field.type) {
+    case "text":
+    case "url":
+    case "email":
+    case "date":
+      return "example";
+    case "textarea":
+      return "example text";
+    case "number":
+      return 0;
+    case "boolean":
+      return false;
+    case "select": {
+      const choices = opts.choices;
+      return choices && choices.length > 0 ? choices[0] : "";
+    }
+    case "media":
+      return "media-id";
+    case "content":
+      return opts.multiple ? ["content-id"] : "content-id";
+    case "blocks":
+      return [];
+    case "array": {
+      const itemFields = opts.itemFields;
+      if (itemFields && itemFields.length > 0) {
+        return [generateExample(itemFields)];
+      }
+      return [];
+    }
+    case "container": {
+      const containerFields = opts.fields;
+      if (containerFields && containerFields.length > 0) {
+        return generateExample(containerFields);
+      }
+      return {};
+    }
+    default:
+      return null;
+  }
+}
+function formatDescribeTable(description) {
+  const rows = [];
+  function addRows(fields, indent) {
+    for (const f of fields) {
+      const constraintStr = Object.entries(f.constraints).map(([k, v]) => `${k}: ${Array.isArray(v) ? v.join(", ") : v}`).join(", ");
+      rows.push({
+        name: indent + f.name,
+        type: f.type,
+        required: f.type === "boolean" || f.type === "blocks" ? "-" : f.required ? "yes" : "no",
+        constraints: constraintStr
+      });
+      if (f.children) {
+        addRows(f.children, indent + "\u21B3 ");
+      }
+    }
+  }
+  addRows(description.fields, "");
+  const cols = [
+    { key: "name", header: "NAME", width: 20 },
+    { key: "type", header: "TYPE", width: 12 },
+    { key: "required", header: "REQUIRED", width: 10 },
+    { key: "constraints", header: "CONSTRAINTS", width: 50 }
+  ];
+  const widths = cols.map((col, i) => {
+    const maxContent = Math.max(
+      col.header.length,
+      ...rows.map((r) => r[col.key].length)
+    );
+    return Math.min(maxContent, col.width);
+  });
+  const truncate = (s, w) => {
+    if (s.length <= w) return s.padEnd(w);
+    return s.slice(0, w - 1) + "\u2026";
+  };
+  const header = cols.map((col, i) => pc2.bold(truncate(col.header, widths[i]))).join("  ");
+  const dataLines = rows.map(
+    (row) => cols.map((col, i) => truncate(row[col.key], widths[i])).join("  ")
+  );
+  return [header, ...dataLines].join("\n");
+}
+
+// src/commands/block-types.ts
+var BLOCK_TYPES_COLUMNS = [
+  { key: "name", header: "NAME", width: 25 },
+  { key: "label", header: "LABEL", width: 30 },
+  { key: "fieldCount", header: "FIELDS", width: 8 }
+];
+function registerBlockTypesCommand(program2) {
+  const blockTypes = program2.command("block-types").description("Manage block types");
+  blockTypes.command("list").description("List all block types").action(async () => {
+    const ctx = await resolveContext(
+      blockTypes.optsWithGlobals()
+    );
+    const result = await ctx.client.listBlockTypes(ctx.site);
+    const rows = result.map((bt) => ({ ...bt, fieldCount: bt.fields?.length ?? 0 }));
+    outputList(rows, BLOCK_TYPES_COLUMNS);
+  });
+  blockTypes.command("get").description("Get block type details").argument("<name>", "block type name").action(async (name) => {
+    const ctx = await resolveContext(
+      blockTypes.optsWithGlobals()
+    );
+    const blockType = await ctx.client.getBlockType(ctx.site, name);
+    outputJson(blockType);
+  });
+  blockTypes.command("create").description("Create a new block type").option("--data <json>", "JSON payload: { name, label, fields }").action(async (opts) => {
+    const ctx = await resolveContext(
+      blockTypes.optsWithGlobals()
+    );
+    const payload = await readJsonPayload(opts, "block-types create");
+    if (!payload.name || !payload.label || !payload.fields) {
+      throw new Error("JSON must include 'name', 'label', and 'fields'.");
+    }
+    const blockType = await ctx.client.createBlockType(ctx.site, payload);
+    outputJson(blockType);
+  });
+  blockTypes.command("update").description("Update a block type").argument("<name>", "block type name to update").option("--data <json>", "JSON payload: { name, label, fields }").action(async (name, opts) => {
+    const ctx = await resolveContext(
+      blockTypes.optsWithGlobals()
+    );
+    const payload = await readJsonPayload(opts, "block-types update");
+    if (!payload.name || !payload.label || !payload.fields) {
+      throw new Error("JSON must include 'name', 'label', and 'fields'.");
+    }
+    const blockType = await ctx.client.updateBlockType(ctx.site, name, payload);
+    outputJson(blockType);
+  });
+  blockTypes.command("delete").description("Delete a block type").argument("<name>", "block type name to delete").option("--force", "skip confirmation prompt").action(async (name, opts) => {
+    if (!opts.force) {
+      if (!process.stdin.isTTY) {
+        throw new Error("Use --force to delete non-interactively.");
+      }
+      const confirmed = await p2.confirm({
+        message: `Delete block type ${name}? This cannot be undone.`
+      });
+      if (p2.isCancel(confirmed) || !confirmed) {
+        process.exit(0);
+      }
+    }
+    const ctx = await resolveContext(
+      blockTypes.optsWithGlobals()
+    );
+    await ctx.client.deleteBlockType(ctx.site, name);
+    outputJson({ deleted: name });
+  });
+  blockTypes.command("describe").description("Show block type field schema").argument("<name>", "block type name").action(async (name) => {
+    const globalOpts = blockTypes.optsWithGlobals();
+    const ctx = await resolveContext(globalOpts);
+    const blockType = await ctx.client.getBlockType(ctx.site, name);
+    const description = describeBlockType(blockType);
+    if (globalOpts.table) {
+      process.stdout.write(formatDescribeTable(description) + "\n");
+    } else {
+      outputJson(description);
+    }
+  });
+}
+
+// src/commands/collections.ts
+import * as p3 from "@clack/prompts";
+var COLLECTIONS_COLUMNS = [
+  { key: "name", header: "NAME", width: 25 },
+  { key: "label", header: "LABEL", width: 30 },
+  { key: "singleton", header: "SINGLETON", width: 10 },
+  { key: "fieldCount", header: "FIELDS", width: 8 }
+];
+function registerCollectionsCommand(program2) {
+  const collections = program2.command("collections").description("Manage collections and inspect schemas");
+  collections.command("list").description("List all collections").action(async () => {
+    const ctx = await resolveContext(
+      collections.optsWithGlobals()
+    );
+    const result = await ctx.client.listCollections(ctx.site);
+    const rows = result.map((c) => ({ ...c, fieldCount: c.fields?.length ?? 0 }));
+    outputList(rows, COLLECTIONS_COLUMNS);
+  });
+  collections.command("get").description("Get collection details").argument("<name>", "collection name").action(async (name) => {
+    const ctx = await resolveContext(
+      collections.optsWithGlobals()
+    );
+    const collection = await ctx.client.getCollection(ctx.site, name);
+    outputJson(collection);
+  });
+  collections.command("create").description("Create a new collection").option("--data <json>", "JSON payload: { name, label, fields, ... }").action(async (opts) => {
+    const ctx = await resolveContext(
+      collections.optsWithGlobals()
+    );
+    const payload = await readJsonPayload(opts, "collections create");
+    if (!payload.name || !payload.label || !payload.fields) {
+      throw new Error("JSON must include 'name', 'label', and 'fields'.");
+    }
+    const collection = await ctx.client.createCollection(ctx.site, payload);
+    outputJson(collection);
+  });
+  collections.command("update").description("Update a collection").argument("<name>", "collection name to update").option("--data <json>", "JSON payload: { name, label, fields, ... }").action(async (name, opts) => {
+    const ctx = await resolveContext(
+      collections.optsWithGlobals()
+    );
+    const payload = await readJsonPayload(opts, "collections update");
+    if (!payload.name || !payload.label || !payload.fields) {
+      throw new Error("JSON must include 'name', 'label', and 'fields'.");
+    }
+    const collection = await ctx.client.updateCollection(ctx.site, name, payload);
+    outputJson(collection);
+  });
+  collections.command("delete").description("Delete a collection").argument("<name>", "collection name to delete").option("--force", "skip confirmation prompt").action(async (name, opts) => {
+    if (!opts.force) {
+      if (!process.stdin.isTTY) {
+        throw new Error("Use --force to delete non-interactively.");
+      }
+      const confirmed = await p3.confirm({
+        message: `Delete collection ${name}? This cannot be undone.`
+      });
+      if (p3.isCancel(confirmed) || !confirmed) {
+        process.exit(0);
+      }
+    }
+    const ctx = await resolveContext(
+      collections.optsWithGlobals()
+    );
+    await ctx.client.deleteCollection(ctx.site, name);
+    outputJson({ deleted: name });
+  });
+  collections.command("describe").description("Show collection field schema").argument("<name>", "collection name").action(async (name) => {
+    const globalOpts = collections.optsWithGlobals();
+    const ctx = await resolveContext(globalOpts);
+    const collection = await ctx.client.getCollection(ctx.site, name);
+    const description = describeCollection(collection);
+    if (globalOpts.table) {
+      process.stdout.write(formatDescribeTable(description) + "\n");
+    } else {
+      outputJson(description);
+    }
+  });
+  collections.command("example").description("Generate example JSON payload for content create").argument("<name>", "collection name").action(async (name) => {
+    const ctx = await resolveContext(
+      collections.optsWithGlobals()
+    );
+    const collection = await ctx.client.getCollection(ctx.site, name);
+    const example = generateExample(collection.fields ?? []);
+    outputJson(example);
+  });
+}
+
+// src/commands/content.ts
+import * as p4 from "@clack/prompts";
+var CONTENT_COLUMNS = [
+  { key: "contentId", header: "ID", width: 26 },
+  { key: "collection", header: "COLLECTION", width: 20 },
+  { key: "title", header: "TITLE", width: 35 },
+  { key: "status", header: "STATUS", width: 12 },
+  { key: "lastDraftAt", header: "UPDATED", width: 12, format: formatTimestamp }
+];
+var VERSIONS_COLUMNS = [
+  { key: "blockId", header: "BLOCK ID", width: 26 },
+  { key: "createdAt", header: "CREATED", width: 12, format: formatTimestamp },
+  { key: "createdBy", header: "CREATED BY", width: 30 }
+];
+var REFERENCES_COLUMNS = [
+  { key: "contentId", header: "CONTENT ID", width: 26 },
+  { key: "collection", header: "COLLECTION", width: 20 },
+  { key: "title", header: "TITLE", width: 30 },
+  { key: "fieldName", header: "FIELD", width: 20 }
+];
+function registerContentCommand(program2) {
+  const content = program2.command("content").description("Manage content lifecycle");
+  content.command("list").description("List content").option("--collection <name>", "filter by collection").option("--status <status>", "filter by status (draft, published, changed, unpublished, scheduled)").option("--tag <tag>", "filter by tag").option("--query <query>", "search query").option("--search <mode>", "search mode: prefix or full (used with --query)").option("--sort <field>", "sort field").option("--related-to <ref>", "filter by relationship (field:contentId)").option("--limit <n>", "max results", parseInt).option("--cursor <token>", "pagination cursor").action(async (opts) => {
+    const globalOpts = content.optsWithGlobals();
+    const ctx = await resolveContext(globalOpts);
+    const result = await ctx.client.listContent(ctx.site, {
+      collection: opts.collection,
+      status: opts.status,
+      tag: opts.tag,
+      q: opts.query,
+      search: opts.search,
+      sort: opts.sort,
+      relatedTo: opts.relatedTo,
+      limit: opts.limit,
+      cursor: opts.cursor
+    });
+    if (globalOpts.table) {
+      const rows = result.items.map((item) => {
+        const r = item;
+        if (!r.status) {
+          const published = r.lastPublishedAt;
+          const drafted = r.lastDraftAt;
+          if (published && drafted && drafted > published) r.status = "changed";
+          else if (published) r.status = "published";
+          else r.status = "draft";
+        }
+        return r;
+      });
+      outputList(rows, CONTENT_COLUMNS);
+      if (result.hasMore) {
+        process.stderr.write(
+          "(more results available \u2014 use --cursor or JSON mode for pagination)\n"
+        );
+      }
+    } else {
+      outputJson(result);
+    }
+  });
+  content.command("get").description("Get content with body").argument("<id>", "content ID").action(async (id) => {
+    const ctx = await resolveContext(content.optsWithGlobals());
+    const item = await ctx.client.getContent(ctx.site, id);
+    outputJson(item);
+  });
+  content.command("create").description("Create new content in a collection").requiredOption("--collection <name>", "target collection").option("--data <json>", "JSON payload (SaveDraftParams)").addHelpText("after", `
+Examples:
+  Discover the schema for a collection:
+    $ headroom collections describe blog_posts
+
+  Generate a JSON template and pipe it into create:
+    $ headroom collections example blog_posts | jq '.title = "Hello"' | headroom content create --collection blog_posts
+`).action(async (opts) => {
+    const ctx = await resolveContext(content.optsWithGlobals());
+    const payload = await readJsonPayload(opts, "content create");
+    const result = await ctx.client.createContent(ctx.site, {
+      collection: opts.collection,
+      params: payload
+    });
+    outputJson(result);
+  });
+  content.command("draft").description("Save draft for existing content").argument("<id>", "content ID").option("--data <json>", "JSON payload (SaveDraftParams)").action(async (id, opts) => {
+    const ctx = await resolveContext(content.optsWithGlobals());
+    const payload = await readJsonPayload(opts, "content draft");
+    const result = await ctx.client.saveDraft(ctx.site, id, payload);
+    outputJson(result);
+  });
+  content.command("publish").description("Publish content").argument("<id>", "content ID").action(async (id) => {
+    const ctx = await resolveContext(content.optsWithGlobals());
+    const result = await ctx.client.publishContent(ctx.site, id);
+    outputJson(result);
+  });
+  content.command("unpublish").description("Unpublish content").argument("<id>", "content ID").action(async (id) => {
+    const ctx = await resolveContext(content.optsWithGlobals());
+    await ctx.client.unpublishContent(ctx.site, id);
+    outputJson({ unpublished: id });
+  });
+  content.command("discard").description("Discard draft and revert to published version").argument("<id>", "content ID").option("--force", "skip confirmation prompt").action(async (id, opts) => {
+    if (!opts.force) {
+      if (!process.stdin.isTTY) {
+        throw new Error("Use --force to discard non-interactively.");
+      }
+      const confirmed = await p4.confirm({
+        message: `Discard draft for ${id}? Draft changes will be permanently lost.`
+      });
+      if (p4.isCancel(confirmed) || !confirmed) {
+        process.exit(0);
+      }
+    }
+    const ctx = await resolveContext(content.optsWithGlobals());
+    await ctx.client.discardDraft(ctx.site, id);
+    outputJson({ discarded: id });
+  });
+  content.command("delete").description("Delete content").argument("<id>", "content ID").option("--force", "skip confirmation prompt").action(async (id, opts) => {
+    if (!opts.force) {
+      if (!process.stdin.isTTY) {
+        throw new Error("Use --force to delete non-interactively.");
+      }
+      const confirmed = await p4.confirm({
+        message: `Delete content ${id}? This cannot be undone.`
+      });
+      if (p4.isCancel(confirmed) || !confirmed) {
+        process.exit(0);
+      }
+    }
+    const ctx = await resolveContext(content.optsWithGlobals());
+    await ctx.client.deleteContent(ctx.site, id);
+    outputJson({ deleted: id });
+  });
+  content.command("versions").description("List version history for content").argument("<id>", "content ID").action(async (id) => {
+    const globalOpts = content.optsWithGlobals();
+    const ctx = await resolveContext(globalOpts);
+    const result = await ctx.client.listVersions(ctx.site, id);
+    if (globalOpts.table) {
+      outputList(
+        result.versions,
+        VERSIONS_COLUMNS
+      );
+    } else {
+      outputJson(result);
+    }
+  });
+  content.command("references").description("Show what references this content").argument("<id>", "content ID").action(async (id) => {
+    const globalOpts = content.optsWithGlobals();
+    const ctx = await resolveContext(globalOpts);
+    const result = await ctx.client.getReferences(ctx.site, id);
+    if (globalOpts.table) {
+      outputList(
+        result.items,
+        REFERENCES_COLUMNS
+      );
+    } else {
+      outputJson(result);
+    }
+  });
+}
+
+// src/commands/login.ts
+import { createInterface } from "readline";
+import * as p5 from "@clack/prompts";
+import pc3 from "picocolors";
+async function apiLogin(apiUrl, email, password2) {
+  const res = await fetch(`${apiUrl}/auth/login`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ email, password: password2 })
+  });
+  if (!res.ok) {
+    const body = await res.json().catch(() => ({}));
+    const detail = body.error ?? `HTTP ${res.status}`;
+    if (res.status === 401) {
+      throw new Error(`Authentication failed: ${detail}`);
+    }
+    if (res.status === 422) {
+      throw new Error(
+        `Account setup required (MFA or password change). Use the admin UI to complete setup, then retry.`
+      );
+    }
+    throw new Error(`Login request failed: ${detail}`);
+  }
+  return res.json();
+}
+async function readStdin() {
+  const rl = createInterface({ input: process.stdin });
+  for await (const line of rl) {
+    rl.close();
+    return line.trim();
+  }
+  throw new Error("No input received on stdin");
+}
+function registerLoginCommand(program2) {
+  program2.command("login").argument("<api-url>", "Headroom API URL (e.g. https://xxx.lambda-url.us-east-1.on.aws)").argument("[site]", "site host to set as active (e.g. mysite.com)").option("--email <email>", "admin email address").option("--password <password>", "admin password (visible in shell history \u2014 prefer --password-stdin)").option("--password-stdin", "read password from stdin (recommended for CI)").description("Authenticate with a Headroom API").addHelpText(
+    "after",
+    `
+Examples:
+  # Interactive login (prompts for email and password)
+  $ headroom login https://your-api.example.com mysite.com
+
+  # Non-interactive login (secure \u2014 password not in shell history)
+  $ echo "$PASSWORD" | headroom login https://your-api.example.com mysite.com \\
+      --email admin@example.com --password-stdin
+
+  # Non-interactive login (convenience, password in shell history)
+  $ headroom login https://your-api.example.com mysite.com \\
+      --email admin@example.com --password 'MyPass123!'
+
+  # Login without setting a site (set it later with 'headroom site')
+  $ headroom login https://your-api.example.com
+
+See also: site, whoami`
+  ).action(async (apiUrl, site, opts) => {
+    await runLogin(apiUrl.replace(/\/+$/, ""), site, opts);
+  });
+}
+async function runLogin(apiUrl, site, opts) {
+  let email = opts.email;
+  let password2 = opts.password;
+  if (opts.passwordStdin) {
+    password2 = await readStdin();
+  }
+  const isTTY = process.stdin.isTTY;
+  if (!email || !password2) {
+    if (!isTTY) {
+      throw new Error(
+        "Non-interactive mode requires --email and (--password or --password-stdin)."
+      );
+    }
+    p5.intro(pc3.bold("Headroom Login"));
+    const values = await p5.group({
+      email: () => email ? Promise.resolve(email) : p5.text({
+        message: "Email:",
+        validate: (v) => v.includes("@") ? void 0 : "Enter a valid email"
+      }),
+      password: () => password2 ? Promise.resolve(password2) : p5.password({ message: "Password:" })
+    });
+    if (p5.isCancel(values)) {
+      p5.cancel("Login cancelled.");
+      process.exit(0);
+    }
+    email = values.email;
+    password2 = values.password;
+  }
+  const { accessToken, refreshToken, expiresIn } = await apiLogin(
+    apiUrl,
+    email,
+    password2
+  );
+  await saveConfig({
+    apiUrl,
+    email,
+    activeSite: site ?? (await loadConfig())?.activeSite
+  });
+  await saveToken(apiUrl, {
+    accessToken,
+    refreshToken,
+    expiresAt: Date.now() + expiresIn * 1e3
+  });
+  const result = {
+    apiUrl,
+    email,
+    ...site ? { site } : {}
+  };
+  if (isTTY) {
+    p5.outro(pc3.green(`Logged in as ${email}`));
+  }
+  outputJson(result);
+}
+
+// src/commands/media.ts
+import * as p6 from "@clack/prompts";
+var MEDIA_COLUMNS = [
+  { key: "mediaId", header: "ID", width: 26 },
+  { key: "filename", header: "FILENAME", width: 30 },
+  { key: "mimeType", header: "TYPE", width: 20 },
+  { key: "size", header: "SIZE", width: 10, format: formatFileSize },
+  { key: "uploadedAt", header: "UPLOADED", width: 12, format: formatTimestamp }
+];
+function formatFileSize(v) {
+  const bytes = Number(v);
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+var FOLDER_COLUMNS = [
+  { key: "folderId", header: "ID", width: 26 },
+  { key: "name", header: "NAME", width: 30 },
+  { key: "count", header: "FILES", width: 8 },
+  { key: "createdAt", header: "CREATED", width: 12, format: formatTimestamp }
+];
+var USAGE_COLUMNS = [
+  { key: "contentId", header: "CONTENT ID", width: 26 },
+  { key: "collection", header: "COLLECTION", width: 20 },
+  { key: "title", header: "TITLE", width: 35 }
+];
+function registerMediaCommand(program2) {
+  const media = program2.command("media").description("Manage media files and folders");
+  media.command("list").description("List media files").option("--folder <id>", "filter by folder ID").option("--tag <tag>", "filter by tag").option("--query <query>", "search by filename").option("--sort <field>", "sort field").option("--limit <n>", "max results", parseInt).option("--cursor <token>", "pagination cursor").action(async (opts) => {
+    const globalOpts = media.optsWithGlobals();
+    const ctx = await resolveContext(globalOpts);
+    const result = await ctx.client.listMedia(ctx.site, {
+      folderId: opts.folder,
+      tag: opts.tag,
+      q: opts.query,
+      sort: opts.sort,
+      limit: opts.limit,
+      cursor: opts.cursor
+    });
+    if (globalOpts.table) {
+      outputList(
+        result.items,
+        MEDIA_COLUMNS
+      );
+      if (result.hasMore) {
+        process.stderr.write(
+          "(more results available \u2014 use --cursor or JSON mode for pagination)\n"
+        );
+      }
+    } else {
+      outputJson(result);
+    }
+  });
+  media.command("get").description("Get media item metadata").argument("<id>", "media ID").action(async (id) => {
+    const ctx = await resolveContext(media.optsWithGlobals());
+    const item = await ctx.client.getMedia(ctx.site, id);
+    outputJson(item);
+  });
+  media.command("update").description("Update media metadata (alt, caption, tags, folder)").argument("<id>", "media ID").option("--data <json>", "JSON payload: { alt?, caption?, userTags?, folderId? }").action(async (id, opts) => {
+    const ctx = await resolveContext(media.optsWithGlobals());
+    const payload = await readJsonPayload(opts, "media update");
+    const result = await ctx.client.updateMedia(ctx.site, id, payload);
+    outputJson(result);
+  });
+  media.command("delete").description("Delete a media item").argument("<id>", "media ID").option("--force", "skip confirmation prompt").action(async (id, opts) => {
+    if (!opts.force) {
+      if (!process.stdin.isTTY) {
+        throw new Error("Use --force to delete non-interactively.");
+      }
+      const confirmed = await p6.confirm({
+        message: `Delete media ${id}? This cannot be undone.`
+      });
+      if (p6.isCancel(confirmed) || !confirmed) {
+        process.exit(0);
+      }
+    }
+    const ctx = await resolveContext(media.optsWithGlobals());
+    await ctx.client.deleteMedia(ctx.site, id);
+    outputJson({ deleted: id });
+  });
+  media.command("upload").description("Upload a local file").argument("<file>", "path to local file").option("--alt <text>", "alt text for the media item").option("--caption <text>", "caption for the media item").option("--folder <id>", "folder ID to place the file in").option("--tags <tags>", "comma-separated tags").action(async (file, opts) => {
+    const ctx = await resolveContext(media.optsWithGlobals());
+    const { constants } = await import("fs");
+    const { access: accessAsync } = await import("fs/promises");
+    await accessAsync(file, constants.R_OK).catch(() => {
+      throw new Error(`File not found or not readable: ${file}`);
+    });
+    const { uploadFile } = await import("@headroom-cms/admin-api/node");
+    debugLog(`Uploading ${file}...`);
+    let result = await uploadFile(ctx.client, ctx.site, file, opts.alt);
+    const updates = {};
+    if (opts.caption) updates.caption = opts.caption;
+    if (opts.folder) updates.folderId = opts.folder;
+    if (opts.tags) updates.userTags = opts.tags.split(",").map((t) => t.trim());
+    if (Object.keys(updates).length > 0) {
+      result = await ctx.client.updateMedia(ctx.site, result.mediaId, updates);
+    }
+    outputJson(result);
+  });
+  media.command("upload-url").description("Upload a file from a remote URL").argument("<url>", "URL to download and upload").option("--filename <name>", "override filename (default: derived from URL)").option("--alt <text>", "alt text for the media item").option("--caption <text>", "caption for the media item").option("--folder <id>", "folder ID to place the file in").option("--tags <tags>", "comma-separated tags").action(async (url, opts) => {
+    const ctx = await resolveContext(media.optsWithGlobals());
+    const filename = opts.filename || new URL(url).pathname.split("/").pop() || "download.bin";
+    debugLog(`Uploading from ${url} as ${filename}...`);
+    let result = await ctx.client.uploadFromUrl(ctx.site, url, filename, opts.alt);
+    const updates = {};
+    if (opts.caption) updates.caption = opts.caption;
+    if (opts.folder) updates.folderId = opts.folder;
+    if (opts.tags) updates.userTags = opts.tags.split(",").map((t) => t.trim());
+    if (Object.keys(updates).length > 0) {
+      result = await ctx.client.updateMedia(ctx.site, result.mediaId, updates);
+    }
+    outputJson(result);
+  });
+  media.command("usage").description("Show content that references this media item").argument("<id>", "media ID").action(async (id) => {
+    const globalOpts = media.optsWithGlobals();
+    const ctx = await resolveContext(globalOpts);
+    const result = await ctx.client.getMediaUsage(ctx.site, id);
+    if (globalOpts.table) {
+      outputList(
+        result.references,
+        USAGE_COLUMNS
+      );
+    } else {
+      outputJson(result);
+    }
+  });
+  media.command("bulk").description("Perform bulk operations on media items").option("--data <json>", "JSON payload: { mediaIds, action, folderId?, tags? }").action(async (opts) => {
+    const ctx = await resolveContext(media.optsWithGlobals());
+    const payload = await readJsonPayload(opts, "media bulk");
+    if (!payload.mediaIds?.length) {
+      throw new Error("Payload must include 'mediaIds' array.");
+    }
+    if (!payload.action) {
+      throw new Error("Payload must include 'action' (delete, move, addTags, removeTags).");
+    }
+    const result = await ctx.client.bulkMediaOperation(ctx.site, payload);
+    outputJson(result);
+  });
+  const folders = media.command("folders").description("Manage media folders");
+  folders.command("list").description("List media folders").action(async () => {
+    const globalOpts = media.optsWithGlobals();
+    const ctx = await resolveContext(globalOpts);
+    const result = await ctx.client.listMediaFolders(ctx.site);
+    outputList(result, FOLDER_COLUMNS);
+  });
+  folders.command("create").description("Create a media folder").option("--data <json>", 'JSON payload: { name: "folder-name" }').action(async (opts) => {
+    const ctx = await resolveContext(media.optsWithGlobals());
+    const payload = await readJsonPayload(opts, "media folders create");
+    if (!payload.name) {
+      throw new Error("Payload must include 'name' field.");
+    }
+    const result = await ctx.client.createMediaFolder(ctx.site, payload.name);
+    outputJson(result);
+  });
+  folders.command("update").description("Rename a media folder").argument("<id>", "folder ID").option("--data <json>", 'JSON payload: { name: "new-name" }').action(async (id, opts) => {
+    const ctx = await resolveContext(media.optsWithGlobals());
+    const payload = await readJsonPayload(opts, "media folders update");
+    if (!payload.name) {
+      throw new Error("Payload must include 'name' field.");
+    }
+    const result = await ctx.client.updateMediaFolder(ctx.site, id, payload.name);
+    outputJson(result);
+  });
+  folders.command("delete").description("Delete a media folder").argument("<id>", "folder ID").option("--force", "skip confirmation prompt").action(async (id, opts) => {
+    if (!opts.force) {
+      if (!process.stdin.isTTY) {
+        throw new Error("Use --force to delete non-interactively.");
+      }
+      const confirmed = await p6.confirm({
+        message: `Delete folder ${id}? Files in the folder will be moved to the root.`
+      });
+      if (p6.isCancel(confirmed) || !confirmed) {
+        process.exit(0);
+      }
+    }
+    const ctx = await resolveContext(media.optsWithGlobals());
+    await ctx.client.deleteMediaFolder(ctx.site, id);
+    outputJson({ deleted: id });
+  });
+}
+
+// src/commands/site.ts
+function registerSiteCommand(program2) {
+  program2.command("site").argument("[host]", "site host to set as active").description("Get or set the active site").addHelpText(
+    "after",
+    `
+Examples:
+  # Show current active site
+  $ headroom site
+
+  # Set active site
+  $ headroom site mysite.com
+
+See also: login, whoami`
+  ).action(async (host) => {
+    if (host) {
+      const config = await updateConfig({ activeSite: host });
+      outputJson({ activeSite: config.activeSite });
+    } else {
+      const config = await loadConfig();
+      if (!config?.activeSite) {
+        throw new Error("No active site. Run: headroom site <host>");
+      }
+      outputJson({ activeSite: config.activeSite });
+    }
+  });
+}
+
+// src/commands/sites.ts
+import * as p7 from "@clack/prompts";
+var SITES_COLUMNS = [
+  { key: "host", header: "HOST", width: 30 },
+  { key: "name", header: "NAME", width: 30 },
+  { key: "status", header: "STATUS", width: 12 },
+  { key: "createdAt", header: "CREATED", width: 12, format: formatTimestamp }
+];
+function registerSitesCommand(program2) {
+  const sites = program2.command("sites").description("Manage sites");
+  sites.command("list").description("List all sites").option("--archived", "include archived sites").action(async (opts) => {
+    const ctx = await resolveAuthContext(
+      sites.optsWithGlobals()
+    );
+    const result = await ctx.client.listSites(!!opts.archived);
+    outputList(result, SITES_COLUMNS);
+  });
+  sites.command("get").description("Get site details").argument("<host>", "site host").action(async (host) => {
+    const ctx = await resolveAuthContext(
+      sites.optsWithGlobals()
+    );
+    const site = await ctx.client.getSite(host);
+    outputJson(site);
+  });
+  sites.command("create").description("Create a new site").option("--data <json>", "JSON payload: { host, name }").action(async (opts) => {
+    const ctx = await resolveAuthContext(
+      sites.optsWithGlobals()
+    );
+    const payload = await readJsonPayload(opts, "sites create");
+    if (!payload.host || !payload.name) {
+      throw new Error("JSON must include 'host' and 'name' fields.");
+    }
+    const site = await ctx.client.createSite(payload.host, payload.name);
+    outputJson(site);
+  });
+  sites.command("update").description("Update a site").argument("<host>", "site host to update").option("--data <json>", "JSON payload: { name?, status? }").action(async (host, opts) => {
+    const ctx = await resolveAuthContext(
+      sites.optsWithGlobals()
+    );
+    const payload = await readJsonPayload(opts, "sites update");
+    const site = await ctx.client.updateSite(host, payload);
+    outputJson(site);
+  });
+  sites.command("delete").description("Delete a site").argument("<host>", "site host to delete").option("--force", "skip confirmation prompt").action(async (host, opts) => {
+    if (!opts.force) {
+      if (!process.stdin.isTTY) {
+        throw new Error("Use --force to delete non-interactively.");
+      }
+      const confirmed = await p7.confirm({
+        message: `Delete site ${host}? This cannot be undone.`
+      });
+      if (p7.isCancel(confirmed) || !confirmed) {
+        process.exit(0);
+      }
+    }
+    const ctx = await resolveAuthContext(
+      sites.optsWithGlobals()
+    );
+    await ctx.client.deleteSite(host);
+    outputJson({ deleted: host });
+  });
+}
+
+// src/commands/site-users.ts
+import * as p8 from "@clack/prompts";
+var SITE_USER_COLUMNS = [
+  { key: "userId", header: "ID", width: 26 },
+  { key: "email", header: "EMAIL", width: 30 },
+  { key: "status", header: "STATUS", width: 10 },
+  { key: "name", header: "NAME", width: 20 },
+  { key: "createdAt", header: "CREATED", width: 12, format: formatTimestamp }
+];
+function registerSiteUsersCommand(program2) {
+  const siteUsers = program2.command("site-users").description("Manage site users");
+  siteUsers.command("list").description("List site users").option("--tag <tag>", "filter by tag").option("--limit <n>", "max results", parseInt).option("--cursor <token>", "pagination cursor").action(async (opts) => {
+    const globalOpts = siteUsers.optsWithGlobals();
+    const ctx = await resolveContext(globalOpts);
+    const result = await ctx.client.listSiteUsers(ctx.site, {
+      tag: opts.tag,
+      limit: opts.limit,
+      cursor: opts.cursor
+    });
+    if (globalOpts.table) {
+      outputList(
+        result.items,
+        SITE_USER_COLUMNS
+      );
+      if (result.hasMore) {
+        process.stderr.write(
+          "(more results available \u2014 use --cursor or JSON mode for pagination)\n"
+        );
+      }
+    } else {
+      outputJson(result);
+    }
+  });
+  siteUsers.command("get").description("Get site user details").argument("<id>", "site user ID").action(async (id) => {
+    const ctx = await resolveContext(siteUsers.optsWithGlobals());
+    const user = await ctx.client.getSiteUser(ctx.site, id);
+    outputJson(user);
+  });
+  siteUsers.command("create").description("Create a site user").option("--data <json>", "JSON payload: { email, name?, tags?, fields? }").action(async (opts) => {
+    const ctx = await resolveContext(siteUsers.optsWithGlobals());
+    const payload = await readJsonPayload(opts, "site-users create");
+    if (!payload.email) {
+      throw new Error("Payload must include 'email' field.");
+    }
+    const result = await ctx.client.createSiteUser(ctx.site, payload);
+    outputJson(result);
+  });
+  siteUsers.command("update").description("Update a site user").argument("<id>", "site user ID").option("--data <json>", "JSON payload: { name?, status?, tags?, fields? }").action(async (id, opts) => {
+    const ctx = await resolveContext(siteUsers.optsWithGlobals());
+    const payload = await readJsonPayload(opts, "site-users update");
+    const result = await ctx.client.updateSiteUser(ctx.site, id, payload);
+    outputJson(result);
+  });
+  siteUsers.command("delete").description("Delete a site user").argument("<id>", "site user ID").option("--force", "skip confirmation prompt").action(async (id, opts) => {
+    if (!opts.force) {
+      if (!process.stdin.isTTY) {
+        throw new Error("Use --force to delete non-interactively.");
+      }
+      const confirmed = await p8.confirm({
+        message: `Delete site user ${id}? This cannot be undone.`
+      });
+      if (p8.isCancel(confirmed) || !confirmed) {
+        process.exit(0);
+      }
+    }
+    const ctx = await resolveContext(siteUsers.optsWithGlobals());
+    await ctx.client.deleteSiteUser(ctx.site, id);
+    outputJson({ deleted: id });
+  });
+  siteUsers.command("update-email").description("Change a site user's email address").argument("<id>", "site user ID").option("--data <json>", 'JSON payload: { email: "new@example.com" }').action(async (id, opts) => {
+    const ctx = await resolveContext(siteUsers.optsWithGlobals());
+    const payload = await readJsonPayload(opts, "site-users update-email");
+    if (!payload.email) {
+      throw new Error("Payload must include 'email' field.");
+    }
+    const result = await ctx.client.changeSiteUserEmail(ctx.site, id, payload);
+    outputJson(result);
+  });
+}
+
+// src/commands/tags.ts
+import * as p9 from "@clack/prompts";
+var TAG_COLUMNS = [
+  { key: "tag", header: "TAG", width: 30 },
+  { key: "count", header: "COUNT", width: 10 }
+];
+function registerTagsCommand(program2) {
+  const tags = program2.command("tags").description("Manage content tags");
+  tags.command("list").description("List all tags with usage counts").action(async () => {
+    const ctx = await resolveContext(tags.optsWithGlobals());
+    const result = await ctx.client.listTags(ctx.site);
+    outputList(result.tags, TAG_COLUMNS);
+  });
+  tags.command("create").description("Create a tag").argument("<tag>", "tag name").action(async (tag) => {
+    const ctx = await resolveContext(tags.optsWithGlobals());
+    await ctx.client.createTag(ctx.site, tag);
+    outputJson({ created: tag });
+  });
+  tags.command("delete").description("Delete a tag").argument("<tag>", "tag name").option("--force", "skip confirmation prompt").action(async (tag, opts) => {
+    if (!opts.force) {
+      if (!process.stdin.isTTY) {
+        throw new Error("Use --force to delete non-interactively.");
+      }
+      const confirmed = await p9.confirm({
+        message: `Delete tag "${tag}"? This will remove it from all content.`
+      });
+      if (p9.isCancel(confirmed) || !confirmed) {
+        process.exit(0);
+      }
+    }
+    const ctx = await resolveContext(tags.optsWithGlobals());
+    await ctx.client.deleteTag(ctx.site, tag);
+    outputJson({ deleted: tag });
+  });
+}
+
+// src/commands/users.ts
+import * as p10 from "@clack/prompts";
+var USER_COLUMNS = [
+  { key: "sub", header: "SUB", width: 38 },
+  { key: "email", header: "EMAIL", width: 30 },
+  { key: "status", header: "STATUS", width: 12 },
+  { key: "mfaEnabled", header: "MFA", width: 5, format: (v) => v ? "yes" : "no" },
+  { key: "createdAt", header: "CREATED", width: 12, format: formatTimestamp }
+];
+function registerUsersCommand(program2) {
+  const users = program2.command("users").description("Manage admin users (global, not site-scoped)");
+  users.command("list").description("List all admin users").action(async () => {
+    const ctx = await resolveAuthContext(users.optsWithGlobals());
+    const result = await ctx.client.listUsers();
+    outputList(result.items, USER_COLUMNS);
+  });
+  users.command("delete").description("Delete an admin user").argument("<sub>", "user sub (Cognito ID)").option("--force", "skip confirmation prompt").action(async (sub, opts) => {
+    if (!opts.force) {
+      if (!process.stdin.isTTY) {
+        throw new Error("Use --force to delete non-interactively.");
+      }
+      const confirmed = await p10.confirm({
+        message: `Delete user ${sub}? This cannot be undone.`
+      });
+      if (p10.isCancel(confirmed) || !confirmed) {
+        process.exit(0);
+      }
+    }
+    const ctx = await resolveAuthContext(users.optsWithGlobals());
+    await ctx.client.deleteUser(sub);
+    outputJson({ deleted: sub });
+  });
+  users.command("disable-mfa").description("Disable MFA for an admin user").argument("<sub>", "user sub (Cognito ID)").action(async (sub) => {
+    const ctx = await resolveAuthContext(users.optsWithGlobals());
+    await ctx.client.disableUserMfa(sub);
+    outputJson({ mfaDisabled: sub });
+  });
+  users.command("resolve").description("Resolve user subs to email addresses").argument("<subs...>", "one or more user subs (Cognito IDs)").action(async (subs) => {
+    const ctx = await resolveAuthContext(users.optsWithGlobals());
+    const result = await ctx.client.resolveAdmins(subs);
+    outputJson(result);
+  });
+}
+
+// src/commands/webhooks.ts
+import * as p11 from "@clack/prompts";
+var WEBHOOK_COLUMNS = [
+  { key: "webhookId", header: "ID", width: 26 },
+  { key: "url", header: "URL", width: 40 },
+  { key: "events", header: "EVENTS", width: 30, format: (v) => Array.isArray(v) ? v.join(", ") : String(v) },
+  { key: "createdAt", header: "CREATED", width: 12, format: formatTimestamp }
+];
+var DELIVERY_COLUMNS = [
+  { key: "deliveryId", header: "ID", width: 26 },
+  { key: "event", header: "EVENT", width: 20 },
+  { key: "statusCode", header: "STATUS", width: 8 },
+  { key: "success", header: "OK", width: 5, format: (v) => v ? "yes" : "no" },
+  { key: "deliveredAt", header: "DELIVERED", width: 12, format: formatTimestamp }
+];
+function registerWebhooksCommand(program2) {
+  const webhooks = program2.command("webhooks").description("Manage webhooks and deliveries");
+  webhooks.command("list").description("List webhooks").action(async () => {
+    const ctx = await resolveContext(webhooks.optsWithGlobals());
+    const result = await ctx.client.listWebhooks(ctx.site);
+    outputList(result, WEBHOOK_COLUMNS);
+  });
+  webhooks.command("get").description("Get webhook details").argument("<id>", "webhook ID").action(async (id) => {
+    const ctx = await resolveContext(webhooks.optsWithGlobals());
+    const webhook = await ctx.client.getWebhook(ctx.site, id);
+    outputJson(webhook);
+  });
+  webhooks.command("create").description("Create a webhook").option("--data <json>", 'JSON payload: { url, events: ["content.published", ...] }').action(async (opts) => {
+    const ctx = await resolveContext(webhooks.optsWithGlobals());
+    const payload = await readJsonPayload(opts, "webhooks create");
+    if (!payload.url || !payload.events?.length) {
+      throw new Error("Payload must include 'url' and 'events' array.");
+    }
+    const result = await ctx.client.createWebhook(ctx.site, payload);
+    outputJson(result);
+  });
+  webhooks.command("update").description("Update a webhook").argument("<id>", "webhook ID").option("--data <json>", "JSON payload: { url?, events? }").action(async (id, opts) => {
+    const ctx = await resolveContext(webhooks.optsWithGlobals());
+    const payload = await readJsonPayload(opts, "webhooks update");
+    const result = await ctx.client.updateWebhook(ctx.site, id, payload);
+    outputJson(result);
+  });
+  webhooks.command("delete").description("Delete a webhook").argument("<id>", "webhook ID").option("--force", "skip confirmation prompt").action(async (id, opts) => {
+    if (!opts.force) {
+      if (!process.stdin.isTTY) {
+        throw new Error("Use --force to delete non-interactively.");
+      }
+      const confirmed = await p11.confirm({
+        message: `Delete webhook ${id}? This cannot be undone.`
+      });
+      if (p11.isCancel(confirmed) || !confirmed) {
+        process.exit(0);
+      }
+    }
+    const ctx = await resolveContext(webhooks.optsWithGlobals());
+    await ctx.client.deleteWebhook(ctx.site, id);
+    outputJson({ deleted: id });
+  });
+  webhooks.command("test").description("Send a test delivery").argument("<id>", "webhook ID").action(async (id) => {
+    const ctx = await resolveContext(webhooks.optsWithGlobals());
+    await ctx.client.testWebhook(ctx.site, id);
+    outputJson({ tested: id });
+  });
+  webhooks.command("rotate-secret").description("Rotate the signing secret (outputs new secret)").argument("<id>", "webhook ID").action(async (id) => {
+    const ctx = await resolveContext(webhooks.optsWithGlobals());
+    const result = await ctx.client.rotateWebhookSecret(ctx.site, id);
+    outputJson(result);
+  });
+  const deliveries = webhooks.command("deliveries").description("Manage webhook deliveries");
+  deliveries.command("list").description("List deliveries for a webhook").argument("<webhookId>", "webhook ID").action(async (webhookId) => {
+    const globalOpts = webhooks.optsWithGlobals();
+    const ctx = await resolveContext(globalOpts);
+    const result = await ctx.client.listWebhookDeliveries(ctx.site, webhookId);
+    if (globalOpts.table) {
+      outputList(
+        result.deliveries,
+        DELIVERY_COLUMNS
+      );
+      if (result.hasMore) {
+        process.stderr.write(
+          "(more results available \u2014 use JSON mode for pagination)\n"
+        );
+      }
+    } else {
+      outputJson(result);
+    }
+  });
+  deliveries.command("get").description("Get delivery details").argument("<webhookId>", "webhook ID").argument("<deliveryId>", "delivery ID").action(async (webhookId, deliveryId) => {
+    const ctx = await resolveContext(webhooks.optsWithGlobals());
+    const delivery = await ctx.client.getWebhookDelivery(ctx.site, webhookId, deliveryId);
+    outputJson(delivery);
+  });
+  deliveries.command("retry").description("Retry a failed delivery").argument("<webhookId>", "webhook ID").argument("<deliveryId>", "delivery ID").action(async (webhookId, deliveryId) => {
+    const ctx = await resolveContext(webhooks.optsWithGlobals());
+    await ctx.client.retryDelivery(ctx.site, webhookId, deliveryId);
+    outputJson({ retried: deliveryId });
+  });
+}
+
+// src/commands/whoami.ts
+function registerWhoamiCommand(program2) {
+  program2.command("whoami").description("Show current user, site, and API URL").addHelpText(
+    "after",
+    `
+Examples:
+  $ headroom whoami
+  {
+    "email": "admin@example.com",
+    "apiUrl": "https://xxx.lambda-url.us-east-1.on.aws",
+    "site": "mysite.com",
+    "authenticated": true
+  }
+
+See also: login, site`
+  ).action(async () => {
+    const config = await loadConfig();
+    if (!config) {
+      throw new Error("Not logged in. Run: headroom login <api-url>");
+    }
+    const token = await loadToken(config.apiUrl);
+    outputJson({
+      email: config.email,
+      apiUrl: config.apiUrl,
+      site: config.activeSite ?? null,
+      authenticated: token !== null
+    });
+  });
+}
+
+// src/cli.ts
+function createProgram() {
+  const program2 = new Command();
+  program2.name("headroom").description("Headroom CMS command-line interface").version("0.1.5").option("--site <host>", "override active site for this command").option("--api-url <url>", "override API URL for this command").option("--debug", "print HTTP request/response details to stderr").option("-q, --quiet", "suppress output, exit code only").option("--table", "output as formatted table instead of JSON").option("--no-color", "disable colored output");
+  program2.hook("preAction", (_thisCommand, actionCommand) => {
+    const opts = actionCommand.optsWithGlobals();
+    setQuiet(!!opts.quiet);
+    setDebug(!!opts.debug);
+    setTable(!!opts.table);
+    if (opts.color === false) {
+      process.env.NO_COLOR = "1";
+    }
+  });
+  registerApiKeysCommand(program2);
+  registerAuditCommand(program2);
+  registerBlockTypesCommand(program2);
+  registerCollectionsCommand(program2);
+  registerContentCommand(program2);
+  registerLoginCommand(program2);
+  registerMediaCommand(program2);
+  registerSiteCommand(program2);
+  registerSitesCommand(program2);
+  registerSiteUsersCommand(program2);
+  registerTagsCommand(program2);
+  registerUsersCommand(program2);
+  registerWebhooksCommand(program2);
+  registerWhoamiCommand(program2);
+  program2.addHelpText("after", getGettingStartedText());
+  return program2;
+}
+function getGettingStartedText() {
+  return `
+Getting Started:
+  1. Authenticate with your Headroom API:
+     $ headroom login https://your-api-url.example.com mysite.com
+
+  2. Verify your session:
+     $ headroom whoami
+
+  3. Discover your collection schemas:
+     $ headroom collections list --table
+     $ headroom collections describe blog_posts
+     $ headroom collections example blog_posts
+
+  4. Create and publish content:
+     $ headroom collections example blog_posts | jq '.title = "Hello"' | headroom content create --collection blog_posts
+     $ headroom content list --collection blog_posts --table
+     $ headroom content publish <id>
+
+  5. Manage media:
+     $ headroom media upload ./photo.jpg --alt "A photo"
+     $ headroom media list --table
+
+Tips:
+  All commands output JSON by default (pipe to jq for filtering).
+  Use --table for human-readable output.
+  Use --help on any command for examples.
+`;
+}
+
+// src/index.ts
+var program = createProgram();
+program.parseAsync(process.argv).catch((err) => {
+  outputError(err);
+  process.exit(exitCodeForError(err));
+});