@headband/cli 0.2.0 → 0.3.0

package/dist/index.js

@@ -31,11 +31,18 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  CLI_VERSION: () => CLI_VERSION,
+  main: () => main,
   parseArgv: () => parseArgv,
-  run: () => run
+  parseExpires: () => parseExpires,
+  parsePermissions: () => parsePermissions,
+  run: () => run,
+  stdinIsInteractive: () => stdinIsInteractive
 });
 module.exports = __toCommonJS(index_exports);
-var import_fs8 = require("fs");
+var import_fs10 = require("fs");
+var import_fs11 = require("fs");
+var import_path9 = require("path");
 var import_prompts2 = __toESM(require("prompts"));
 var import_picocolors3 = __toESM(require("picocolors"));
 
@@ -235,20 +242,79 @@ var import_os2 = require("os");
 var import_picocolors2 = __toESM(require("picocolors"));
 
 // src/errors.ts
+var EXIT_CODES = {
+  ok: 0,
+  generic: 1,
+  usage: 2,
+  auth: 3,
+  permission: 4,
+  notFound: 5,
+  conflict: 6,
+  rateLimited: 7,
+  server: 8,
+  interrupted: 130
+};
+function exitCodeForStatus(status) {
+  if (status === 400 || status === 413 || status === 422) return EXIT_CODES.usage;
+  if (status === 401) return EXIT_CODES.auth;
+  if (status === 402 || status === 403) return EXIT_CODES.permission;
+  if (status === 404 || status === 410) return EXIT_CODES.notFound;
+  if (status === 409) return EXIT_CODES.conflict;
+  if (status === 429) return EXIT_CODES.rateLimited;
+  if (status >= 500) return EXIT_CODES.server;
+  return EXIT_CODES.generic;
+}
 var CliError = class extends Error {
-  constructor(message) {
+  constructor(message, options = {}) {
     super(message);
     this.name = "CliError";
+    this.exitCode = options.exitCode ?? EXIT_CODES.generic;
+    this.code = options.code;
+  }
+};
+var UsageError = class extends CliError {
+  constructor(message, code = "usage_error") {
+    super(message, { exitCode: EXIT_CODES.usage, code });
+    this.name = "UsageError";
+  }
+};
+var AuthError = class extends CliError {
+  constructor(message) {
+    super(message, { exitCode: EXIT_CODES.auth, code: "not_authenticated" });
+    this.name = "AuthError";
   }
 };
 var ApiError = class extends CliError {
-  constructor(message, status, code) {
-    super(message);
+  constructor(message, status, code, details) {
+    super(message, { exitCode: exitCodeForStatus(status), code });
     this.name = "ApiError";
     this.status = status;
-    this.code = code;
+    this.details = details;
   }
 };
+var DEFAULT_CODES = {
+  [EXIT_CODES.generic]: "error",
+  [EXIT_CODES.usage]: "usage_error",
+  [EXIT_CODES.auth]: "not_authenticated",
+  [EXIT_CODES.permission]: "permission_denied",
+  [EXIT_CODES.notFound]: "not_found",
+  [EXIT_CODES.conflict]: "conflict",
+  [EXIT_CODES.rateLimited]: "rate_limited",
+  [EXIT_CODES.server]: "server_error",
+  [EXIT_CODES.interrupted]: "interrupted"
+};
+function errorExitCode(error) {
+  return error instanceof CliError ? error.exitCode : EXIT_CODES.generic;
+}
+function errorPayload(error) {
+  const exitCode = errorExitCode(error);
+  return {
+    error: error instanceof Error ? error.message : String(error),
+    code: error instanceof CliError && error.code || DEFAULT_CODES[exitCode] || "error",
+    status: error instanceof ApiError ? error.status : null,
+    exitCode
+  };
+}
 function partialFailureSummary(failure) {
   const first = failure.errors[0];
   if (!first) return failure.message;
@@ -261,6 +327,7 @@ var import_fs2 = require("fs");
 var import_path3 = require("path");
 var import_os = require("os");
 var DEFAULT_URL = "https://headband.dev";
+var DEFAULT_PROFILE = "default";
 function normalizeUrl(url) {
   return url.replace(/\/+$/, "");
 }
@@ -270,66 +337,168 @@ function getConfigDir() {
 function getCredentialsPath() {
   return (0, import_path3.join)(getConfigDir(), "credentials.json");
 }
+var PROFILE_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+function validateProfileName(name) {
+  if (!PROFILE_NAME.test(name)) {
+    throw new UsageError(
+      "Profile names use letters, digits, dot, dash and underscore (max 64 characters)."
+    );
+  }
+  return name;
+}
+function profileNameForUrl(url) {
+  const normalized = normalizeUrl(url);
+  if (normalized === DEFAULT_URL) return DEFAULT_PROFILE;
+  try {
+    const { host } = new URL(normalized);
+    const slug = host.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^[^A-Za-z0-9]+/, "");
+    return slug || DEFAULT_PROFILE;
+  } catch {
+    return DEFAULT_PROFILE;
+  }
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function migrateCredentials(raw) {
+  const parsed = isRecord(raw) ? raw : {};
+  const rawProfiles = isRecord(parsed.profiles) ? parsed.profiles : {};
+  const profiles = {};
+  let migratedDefault;
+  let migratedCount = 0;
+  for (const [key, value] of Object.entries(rawProfiles)) {
+    if (!isRecord(value)) continue;
+    if (typeof value.url === "string") {
+      profiles[key] = value;
+      continue;
+    }
+    const url = normalizeUrl(key);
+    const base = profileNameForUrl(url);
+    let name = base;
+    for (let n = 2; profiles[name] || rawProfiles[name]; n += 1) name = `${base}-${n}`;
+    profiles[name] = { ...value, url };
+    migratedCount += 1;
+    if (url === DEFAULT_URL) migratedDefault = name;
+  }
+  let current = typeof parsed.current === "string" ? parsed.current : void 0;
+  if (current && !profiles[current]) current = void 0;
+  if (!current && migratedCount > 0) {
+    const names = Object.keys(profiles);
+    current = names.length === 1 ? names[0] : migratedDefault;
+  }
+  return { version: 2, ...current ? { current } : {}, profiles };
+}
 function readCredentials() {
-  const path = getCredentialsPath();
-  if (!(0, import_fs2.existsSync)(path)) {
-    return { profiles: {} };
+  const path2 = getCredentialsPath();
+  if (!(0, import_fs2.existsSync)(path2)) {
+    return { version: 2, profiles: {} };
   }
   try {
-    const parsed = JSON.parse((0, import_fs2.readFileSync)(path, "utf-8"));
-    return {
-      profiles: parsed.profiles && typeof parsed.profiles === "object" ? parsed.profiles : {}
-    };
+    return migrateCredentials(JSON.parse((0, import_fs2.readFileSync)(path2, "utf-8")));
   } catch {
-    throw new CliError(`Could not read credentials at ${path}`);
+    throw new CliError(`Could not read credentials at ${path2}`);
   }
 }
 function writeCredentials(credentials) {
-  const path = getCredentialsPath();
-  (0, import_fs2.mkdirSync)((0, import_path3.dirname)(path), { recursive: true, mode: 448 });
-  (0, import_fs2.writeFileSync)(path, `${JSON.stringify(credentials, null, 2)}
+  const path2 = getCredentialsPath();
+  if (Object.keys(credentials.profiles).length === 0) {
+    if ((0, import_fs2.existsSync)(path2)) (0, import_fs2.rmSync)(path2);
+    return;
+  }
+  (0, import_fs2.mkdirSync)((0, import_path3.dirname)(path2), { recursive: true, mode: 448 });
+  (0, import_fs2.writeFileSync)(path2, `${JSON.stringify(credentials, null, 2)}
 `, {
     encoding: "utf-8",
     mode: 384
   });
-  (0, import_fs2.chmodSync)(path, 384);
+  (0, import_fs2.chmodSync)(path2, 384);
 }
-function saveProfile(url, profile) {
+function saveProfile(name, profile) {
+  validateProfileName(name);
   const credentials = readCredentials();
-  credentials.profiles[normalizeUrl(url)] = profile;
+  credentials.profiles[name] = { ...profile, url: normalizeUrl(profile.url) };
+  credentials.current = name;
   writeCredentials(credentials);
 }
-function removeProfile(url) {
+function removeProfile(name) {
   const credentials = readCredentials();
-  const normalized = normalizeUrl(url);
-  const existing = credentials.profiles[normalized];
-  delete credentials.profiles[normalized];
-  if (Object.keys(credentials.profiles).length === 0) {
-    const path = getCredentialsPath();
-    if ((0, import_fs2.existsSync)(path)) {
-      (0, import_fs2.rmSync)(path);
-    }
-    return existing;
-  }
+  const existing = credentials.profiles[name];
+  delete credentials.profiles[name];
+  if (credentials.current === name) delete credentials.current;
   writeCredentials(credentials);
   return existing;
 }
-function resolveUrl(explicitUrl) {
-  if (explicitUrl) return normalizeUrl(explicitUrl);
+function setCurrentProfile(name) {
   const credentials = readCredentials();
-  const urls = Object.keys(credentials.profiles);
-  if (urls.length === 1) return urls[0];
-  return DEFAULT_URL;
-}
-function getProfile(url) {
-  const resolvedUrl = resolveUrl(url);
-  const profile = readCredentials().profiles[resolvedUrl];
+  const profile = credentials.profiles[name];
   if (!profile) {
-    throw new CliError(
-      `Not logged in for ${resolvedUrl}. Run: headband login --url ${resolvedUrl}`
+    throw new CliError(`No profile named ${name}. Run: headband profiles list`, {
+      exitCode: 5,
+      code: "profile_not_found"
+    });
+  }
+  credentials.current = name;
+  writeCredentials(credentials);
+  return profile;
+}
+function selectProfile(selectors = {}) {
+  const env = selectors.env ?? process.env;
+  const credentials = readCredentials();
+  const urlOverride = selectors.url || env.HEADBAND_URL;
+  const wantedUrl = urlOverride ? normalizeUrl(urlOverride) : void 0;
+  const explicit = selectors.profile || env.HEADBAND_PROFILE;
+  if (explicit) {
+    const profile = credentials.profiles[explicit];
+    if (!profile) {
+      throw new AuthError(`No profile named ${explicit}. Run: headband profiles list`);
+    }
+    if (wantedUrl && normalizeUrl(profile.url) !== wantedUrl) {
+      throw new UsageError(
+        `Profile ${explicit} is for ${profile.url}, not ${wantedUrl}. Drop --url, or log in to that URL with: headband login --url ${wantedUrl} --profile <name>`
+      );
+    }
+    return { name: explicit, profile };
+  }
+  const entries = Object.entries(credentials.profiles);
+  const matches = (p) => !wantedUrl || normalizeUrl(p.url) === wantedUrl;
+  const current = credentials.current ? credentials.profiles[credentials.current] : void 0;
+  if (current && credentials.current && matches(current)) {
+    return { name: credentials.current, profile: current };
+  }
+  if (wantedUrl) {
+    const found = entries.find(([, p]) => matches(p));
+    return found ? { name: found[0], profile: found[1] } : void 0;
+  }
+  if (entries.length === 1) return { name: entries[0][0], profile: entries[0][1] };
+  return void 0;
+}
+function resolveAuth(selectors = {}) {
+  const env = selectors.env ?? process.env;
+  const urlOverride = selectors.url || env.HEADBAND_URL;
+  const token = selectors.token || env.HEADBAND_API_KEY;
+  if (token) {
+    const explicitProfile = selectors.profile || env.HEADBAND_PROFILE;
+    const fromProfile = explicitProfile && !urlOverride ? selectProfile(selectors) : void 0;
+    return {
+      url: normalizeUrl(urlOverride || fromProfile?.profile.url || DEFAULT_URL),
+      apiKey: token.trim(),
+      source: selectors.token ? "flag" : "env"
+    };
+  }
+  const selected = selectProfile(selectors);
+  if (!selected) {
+    const target = urlOverride ? normalizeUrl(urlOverride) : DEFAULT_URL;
+    throw new AuthError(
+      `Not logged in for ${target}. Run: headband login --url ${target}, or set HEADBAND_API_KEY.`
     );
   }
-  return { url: resolvedUrl, profile };
+  return {
+    url: normalizeUrl(selected.profile.url),
+    apiKey: selected.profile.apiKey,
+    source: "profile",
+    profileName: selected.name,
+    profile: selected.profile
+  };
 }
 
 // src/api.ts
@@ -342,7 +511,7 @@ async function readJson(response) {
     return text;
   }
 }
-async function apiRequest(baseUrl, path, init2 = {}) {
+async function apiRequest(baseUrl, path2, init2 = {}) {
   const headers = new Headers(init2.headers);
   headers.set("accept", "application/json");
   if (init2.body !== void 0 && !headers.has("content-type")) {
@@ -351,30 +520,42 @@ async function apiRequest(baseUrl, path, init2 = {}) {
   if (init2.apiKey) {
     headers.set("authorization", `Bearer ${init2.apiKey}`);
   }
-  const response = await fetch(`${normalizeUrl(baseUrl)}${path}`, {
-    ...init2,
-    headers,
-    body: init2.body === void 0 || typeof init2.body === "string" ? init2.body : JSON.stringify(init2.body)
-  });
+  const base = normalizeUrl(baseUrl);
+  let response;
+  try {
+    response = await fetch(`${base}${path2}`, {
+      ...init2,
+      headers,
+      body: init2.body === void 0 || typeof init2.body === "string" ? init2.body : JSON.stringify(init2.body)
+    });
+  } catch (error) {
+    const cause = error?.cause;
+    const detail = cause?.code || cause?.message || (error instanceof Error ? error.message : "");
+    throw new CliError(`Could not reach ${base}${detail ? ` (${detail})` : ""}.`, {
+      exitCode: EXIT_CODES.server,
+      code: "network_error"
+    });
+  }
   const body = await readJson(response);
   if (!response.ok) {
     const errorBody = body && typeof body === "object" ? body : {};
     throw new ApiError(
       errorBody.error || `Request failed with status ${response.status}`,
       response.status,
-      errorBody.code
+      errorBody.code,
+      body
     );
   }
   return body;
 }
 function createApiClient(url, profile) {
-  const request = (path, init2 = {}) => apiRequest(url, path, { ...init2, apiKey: profile.apiKey });
+  const request = (path2, init2 = {}) => apiRequest(url, path2, { ...init2, apiKey: profile.apiKey });
   return {
     url: normalizeUrl(url),
-    get: (path) => request(path, { method: "GET" }),
-    post: (path, body) => request(path, { method: "POST", body }),
-    patch: (path, body) => request(path, { method: "PATCH", body }),
-    delete: (path) => request(path, { method: "DELETE" })
+    get: (path2) => request(path2, { method: "GET" }),
+    post: (path2, body) => request(path2, { method: "POST", body }),
+    patch: (path2, body) => request(path2, { method: "PATCH", body }),
+    delete: (path2) => request(path2, { method: "DELETE" })
   };
 }
 
@@ -438,8 +619,11 @@ async function runDeviceFlow(url, io, options = {}) {
   throw new CliError("Login expired. Re-run headband login.");
 }
 async function login(url, io, options = {}) {
-  const token = await runDeviceFlow(url, io, options);
-  saveProfile(url, {
+  const baseUrl = normalizeUrl(url);
+  const profile = validateProfileName(options.profileName || profileNameForUrl(baseUrl));
+  const token = await runDeviceFlow(baseUrl, io, options);
+  saveProfile(profile, {
+    url: baseUrl,
     apiKey: token.apiKey,
     keyId: token.keyId,
     keyPrefix: token.keyPrefix,
@@ -447,7 +631,17 @@ async function login(url, io, options = {}) {
     orgName: token.orgName,
     createdAt: (/* @__PURE__ */ new Date()).toISOString()
   });
-  io.stdout(import_picocolors2.default.green(`Logged in to ${normalizeUrl(url)} as ${token.orgName} (${token.keyPrefix})`));
+  io.stdout(
+    import_picocolors2.default.green(`Logged in to ${baseUrl} as ${token.orgName} (${token.keyPrefix}), profile ${profile}`)
+  );
+  return {
+    profile,
+    url: baseUrl,
+    orgId: token.orgId,
+    orgName: token.orgName,
+    keyId: token.keyId,
+    keyPrefix: token.keyPrefix
+  };
 }
 
 // src/config-load.ts
@@ -464,8 +658,8 @@ var CONFIG_FILENAMES = [
 ];
 function findConfigFile(cwd) {
   for (const name of CONFIG_FILENAMES) {
-    const path = (0, import_path4.join)(cwd, name);
-    if ((0, import_fs3.existsSync)(path)) return path;
+    const path2 = (0, import_path4.join)(cwd, name);
+    if ((0, import_fs3.existsSync)(path2)) return path2;
   }
   return void 0;
 }
@@ -473,8 +667,8 @@ function isSyncConfig(value) {
   return typeof value === "object" && value !== null && Array.isArray(value.indexes);
 }
 async function loadHeadbandConfig(cwd) {
-  const path = findConfigFile(cwd);
-  if (!path) {
+  const path2 = findConfigFile(cwd);
+  if (!path2) {
     throw new CliError(
       `No headband.config.ts found in ${cwd}. Run "headband init" or create one that exports a Headband sync config.`
     );
@@ -486,27 +680,27 @@ async function loadHeadbandConfig(cwd) {
   });
   let mod;
   try {
-    mod = await jiti.import(path);
+    mod = await jiti.import(path2);
   } catch (err) {
     throw new CliError(
-      `Failed to load ${path}: ${err instanceof Error ? err.message : String(err)}`
+      `Failed to load ${path2}: ${err instanceof Error ? err.message : String(err)}`
     );
   }
   const candidate = mod.default ?? mod;
   if (!isSyncConfig(candidate)) {
-    throw new CliError(`${path} does not export a valid Headband sync config (missing "indexes").`);
+    throw new CliError(`${path2} does not export a valid Headband sync config (missing "indexes").`);
   }
   const adapter = mod.adapter;
-  return { config: candidate, adapter, path };
+  return { config: candidate, adapter, path: path2 };
 }
 
 // src/docs.ts
 var import_path5 = require("path");
 var import_fs4 = require("fs");
 var DOCS_BATCH_SIZE = 1e3;
-function parseDocumentsFile(path) {
-  const content = (0, import_fs4.readFileSync)(path, "utf-8");
-  const ext = (0, import_path5.extname)(path).toLowerCase();
+function parseDocumentsFile(path2) {
+  const content = (0, import_fs4.readFileSync)(path2, "utf-8");
+  const ext = (0, import_path5.extname)(path2).toLowerCase();
   if (ext === ".jsonl") {
     return content.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((line) => JSON.parse(line));
   }
@@ -529,6 +723,49 @@ async function pushDocuments(client, index, documents, io) {
   }
   return pushed;
 }
+var EXPORT_BATCH_SIZE = 1e3;
+var TYPESENSE_MAX_PAGE = 250;
+async function defaultExportBatchSize(client, index) {
+  try {
+    const list = await client.get("/v1/indexes");
+    const row = list.results?.find((r) => r.uid === index);
+    return row?.engine === "typesense" ? TYPESENSE_MAX_PAGE : EXPORT_BATCH_SIZE;
+  } catch {
+    return EXPORT_BATCH_SIZE;
+  }
+}
+async function exportDocuments(client, options) {
+  const { index, format, batchSize, write } = options;
+  let offset = 0;
+  let exported = 0;
+  let pending;
+  if (format === "json") await write("[");
+  for (; ; ) {
+    const page = await client.get(
+      `/v1/documents?index=${encodeURIComponent(index)}&limit=${batchSize}&offset=${offset}`
+    );
+    const results = Array.isArray(page.results) ? page.results : [];
+    for (const doc of results) {
+      const line = JSON.stringify(doc);
+      if (format === "jsonl") {
+        await write(line);
+      } else {
+        if (pending !== void 0) await write(`  ${pending},`);
+        pending = line;
+      }
+    }
+    exported += results.length;
+    offset += results.length;
+    options.onPage?.(exported, typeof page.total === "number" ? page.total : null);
+    if (results.length < batchSize) break;
+    if (typeof page.total === "number" && offset >= page.total) break;
+  }
+  if (format === "json") {
+    if (pending !== void 0) await write(`  ${pending}`);
+    await write("]");
+  }
+  return exported;
+}
 
 // ../../src/lib/density/catalog-constants.ts
 function formatMemory(mb) {
@@ -537,7 +774,48 @@ function formatMemory(mb) {
 
 // ../../src/lib/density/snippets.ts
 var ADMIN_NOTE = "Creating an index and adding a document need an admin key. A search key can only search.";
+function visorSnippets(endpoint) {
+  return {
+    packageName: "built-in fetch",
+    install: "# Nothing to install. Node 20 and later have fetch built in.",
+    node: [
+      `const base = "${endpoint}";`,
+      "const headers = {",
+      "  Authorization: `Bearer ${process.env.HEADBAND_API_KEY}`,",
+      '  "Content-Type": "application/json",',
+      "};",
+      "",
+      `// ${ADMIN_NOTE}`,
+      "// Creating the index is safe to repeat: an existing index is kept as it is.",
+      'await fetch(`${base}/v1/indexes/movies`, { method: "PUT", headers, body: JSON.stringify({ primaryKey: "id" }) });',
+      'await fetch(`${base}/v1/indexes/movies/documents`, { method: "POST", headers, body: JSON.stringify([{ id: 1, title: "The Matrix" }]) });',
+      "",
+      'const res = await fetch(`${base}/v1/indexes/movies/search`, { method: "POST", headers, body: JSON.stringify({ q: "matrix" }) });',
+      "console.log((await res.json()).hits);"
+    ].join("\n"),
+    curl: [
+      `# ${ADMIN_NOTE}`,
+      "# On a second run the index already exists and PUT keeps it. That is fine.",
+      `curl -X PUT "${endpoint}/v1/indexes/movies" \\`,
+      '  -H "Authorization: Bearer $HEADBAND_API_KEY" \\',
+      '  -H "Content-Type: application/json" \\',
+      `  -d '{"primaryKey":"id"}'`,
+      "",
+      "# Writes are searchable when they return. There is nothing to wait for.",
+      `curl "${endpoint}/v1/indexes/movies/documents" \\`,
+      '  -H "Authorization: Bearer $HEADBAND_API_KEY" \\',
+      '  -H "Content-Type: application/json" \\',
+      `  -d '[{"id":1,"title":"The Matrix"}]'`,
+      "",
+      `curl "${endpoint}/v1/indexes/movies/search" \\`,
+      '  -H "Authorization: Bearer $HEADBAND_API_KEY" \\',
+      '  -H "Content-Type: application/json" \\',
+      `  -d '{"q":"matrix"}'`
+    ].join("\n")
+  };
+}
 function connectSnippets(engine, endpoint) {
+  if (engine === "visor") return visorSnippets(endpoint);
   if (engine === "elasticsearch") {
     return {
       packageName: "@elastic/elasticsearch",
@@ -718,27 +996,30 @@ function summarizeHit(hit) {
 }
 
 // src/instances.ts
-var ENGINES = ["meilisearch", "elasticsearch", "typesense"];
+var ENGINES = ["meilisearch", "elasticsearch", "typesense", "visor"];
 var CLIENTS = ["node", "curl"];
 var COLUMNS = ["id", "name", "engine", "lane", "memory", "region", "state"];
 var INSTANCES_USAGE = [
   "Usage:",
   "  headband instances list [--json]",
-  "  headband instances create <meilisearch|elasticsearch|typesense> [--name <name>] [--lane <serverless|always_on>]",
+  "  headband instances create <meilisearch|elasticsearch|typesense|visor> [--name <name>] [--lane <serverless|always_on>]",
   "                            [--memory <512m|1g|...>] [--region <region>] [--idle-timeout <seconds>] [--json]",
   "  headband instances show <id> [--json]",
   "  headband instances wake <id> [--json]",
   "  headband instances park <id> [--json]",
+  "  headband instances update <id> [--name <name>] [--lane <serverless|always_on>] [--memory <512m|1g|...>]",
+  "                               [--idle-timeout <seconds>] [--json]   (--size is an alias for --memory)",
+  "  headband instances wakes <id> [--limit <n>] [--json]",
   "  headband instances delete <id> [--yes] [--json]",
-  "  headband instances connect <id> [--client <node|curl>]"
+  "  headband instances connect <id> [--client <node|curl>] [--json]"
 ].join("\n");
 function parseMemory(raw) {
   const m = /^(\d+(?:\.\d+)?)\s*(m|mb|g|gb)?$/i.exec(raw.trim());
-  if (!m) throw new CliError("--memory must look like 512m, 1g or 2048");
+  if (!m) throw new UsageError("--memory must look like 512m, 1g or 2048");
   const value = Number(m[1]);
   const mb = (m[2] ?? "m").toLowerCase().startsWith("g") ? value * 1024 : value;
   if (!Number.isInteger(mb) || mb <= 0)
-    throw new CliError("--memory must be a whole number of megabytes");
+    throw new UsageError("--memory must be a whole number of megabytes");
   return mb;
 }
 function formatMemoryMb(mb) {
@@ -747,13 +1028,13 @@ function formatMemoryMb(mb) {
 function parseLane(raw) {
   const lane = raw.replace(/-/g, "_");
   if (lane !== "serverless" && lane !== "always_on")
-    throw new CliError("--lane must be serverless or always_on");
+    throw new UsageError("--lane must be serverless or always_on");
   return lane;
 }
 function parsePositiveInt(raw, name) {
   const value = Number(raw);
   if (!Number.isInteger(value) || value <= 0)
-    throw new CliError(`${name} must be a positive integer`);
+    throw new UsageError(`${name} must be a positive integer`);
   return value;
 }
 function stateLabel(i) {
@@ -773,17 +1054,21 @@ function summaryRow(i) {
 }
 function requireId(args) {
   const id = args[1];
-  if (!id) throw new CliError("Missing engine id");
+  if (!id) throw new UsageError("Missing engine id");
   return id;
 }
 function friendly(err) {
   if (err instanceof ApiError) {
     if (err.status === 404 && err.code === "not_found") {
-      throw new CliError("Dedicated engines are not enabled for this organization yet.");
+      throw new CliError("Dedicated engines are not enabled for this organization yet.", {
+        exitCode: 5,
+        code: "not_found"
+      });
     }
     if (err.status === 403 && err.code === "permission_denied") {
       throw new CliError(
-        "This CLI key cannot manage engines. Run headband login again to get a key that can."
+        "This CLI key cannot manage engines. Run headband login again to get a key that can.",
+        { exitCode: 4, code: "permission_denied" }
       );
     }
   }
@@ -792,8 +1077,8 @@ function friendly(err) {
 async function runInstances(args, flags, io, client, confirm) {
   const action = args[0];
   const json = flags["--json"] === true;
-  const str = (name) => typeof flags[name] === "string" ? flags[name] : void 0;
-  const path = (id, suffix = "") => `/v1/instances/${encodeURIComponent(id)}${suffix}`;
+  const str2 = (name) => typeof flags[name] === "string" ? flags[name] : void 0;
+  const path2 = (id, suffix = "") => `/v1/instances/${encodeURIComponent(id)}${suffix}`;
   try {
     if (action === "list") {
       const res = await client.get("/v1/instances");
@@ -815,14 +1100,14 @@ async function runInstances(args, flags, io, client, confirm) {
     if (action === "create") {
       const engine = args[1];
       if (!engine || !ENGINES.includes(engine)) {
-        throw new CliError("Engine must be one of: meilisearch, elasticsearch, typesense");
+        throw new UsageError("Engine must be one of: meilisearch, elasticsearch, typesense, visor");
       }
       const body = { engine };
-      const name = str("--name");
-      const lane = str("--lane");
-      const memory = str("--memory");
-      const region = str("--region");
-      const idle = str("--idle-timeout");
+      const name = str2("--name");
+      const lane = str2("--lane");
+      const memory = str2("--memory");
+      const region = str2("--region");
+      const idle = str2("--idle-timeout");
       if (name) body.name = name;
       if (lane) body.lane = parseLane(lane);
       if (memory) body.memoryMb = parseMemory(memory);
@@ -837,7 +1122,7 @@ async function runInstances(args, flags, io, client, confirm) {
     }
     if (action === "show") {
       const id = requireId(args);
-      const res = await client.get(path(id));
+      const res = await client.get(path2(id));
       if (json) return printJson(io, res);
       const i = res.data;
       const lines = [
@@ -860,7 +1145,7 @@ async function runInstances(args, flags, io, client, confirm) {
     }
     if (action === "wake") {
       const id = requireId(args);
-      const res = await client.post(path(id, "/wake"));
+      const res = await client.post(path2(id, "/wake"));
       if (json) return printJson(io, res);
       const { wake } = res.data;
       io.stdout(
@@ -870,18 +1155,66 @@ async function runInstances(args, flags, io, client, confirm) {
     }
     if (action === "park") {
       const id = requireId(args);
-      const res = await client.post(path(id, "/park"));
+      const res = await client.post(path2(id, "/park"));
       if (json) return printJson(io, res);
       io.stdout(`Engine ${id} is ${res.data.state}.`);
       return;
     }
+    if (action === "update") {
+      const id = requireId(args);
+      const body = {};
+      const name = str2("--name");
+      const lane = str2("--lane");
+      const memory = str2("--memory") ?? str2("--size");
+      const idle = str2("--idle-timeout");
+      if (name) body.name = name;
+      if (lane) body.lane = parseLane(lane);
+      if (memory) body.memoryMb = parseMemory(memory);
+      if (idle) body.idleTimeoutS = parsePositiveInt(idle, "--idle-timeout");
+      if (Object.keys(body).length === 0) {
+        throw new UsageError(
+          "Nothing to update. Pass at least one of --name, --lane, --memory (or --size), --idle-timeout."
+        );
+      }
+      const res = await client.patch(path2(id), body);
+      if (json) return printJson(io, res);
+      printTable(io, [summaryRow(res.data)], COLUMNS);
+      if (res.data.pendingChanges) {
+        io.stdout(
+          "The engine applies the change in the background. Check it with: headband instances show " + id
+        );
+      }
+      return;
+    }
+    if (action === "wakes") {
+      const id = requireId(args);
+      const limit = str2("--limit");
+      const query = limit ? `?limit=${parsePositiveInt(limit, "--limit")}` : "";
+      const res = await client.get(path2(id, `/wakes${query}`));
+      if (json) return printJson(io, res);
+      if (res.data.length === 0) {
+        io.stdout(`No wakes recorded for engine ${id}.`);
+        return;
+      }
+      printTable(
+        io,
+        res.data.map((w) => ({
+          requestedAt: w.requestedAt,
+          via: w.via,
+          outcome: w.outcome,
+          ready: w.readyMs === null ? "" : `${w.readyMs} ms`
+        })),
+        ["requestedAt", "via", "outcome", "ready"]
+      );
+      return;
+    }
     if (action === "delete") {
       const id = requireId(args);
       if (!await confirm(`Delete engine ${id}? This removes its data and backups.`)) {
         io.stdout("Cancelled.");
         return;
       }
-      const res = await client.delete(path(id));
+      const res = await client.delete(path2(id));
       if (json) return printJson(io, res);
       io.stdout(
         res.data.deleted ? `Deleted engine ${id}.` : `Engine ${id} is being deleted. It finishes in the background.`
@@ -890,10 +1223,20 @@ async function runInstances(args, flags, io, client, confirm) {
     }
     if (action === "connect") {
       const id = requireId(args);
-      const which = str("--client");
-      if (which && !CLIENTS.includes(which)) throw new CliError("--client must be node or curl");
-      const res = await client.get(path(id));
+      const which = str2("--client");
+      if (which && !CLIENTS.includes(which)) throw new UsageError("--client must be node or curl");
+      const res = await client.get(path2(id));
       const s = connectSnippets(res.data.engine, res.data.endpoint);
+      if (json) {
+        return printJson(io, {
+          id: res.data.id,
+          engine: res.data.engine,
+          endpoint: res.data.endpoint,
+          install: s.install,
+          ...!which || which === "node" ? { node: s.node } : {},
+          ...!which || which === "curl" ? { curl: s.curl } : {}
+        });
+      }
       io.stdout(`Endpoint: ${res.data.endpoint}`);
       io.stdout("");
       io.stdout(
@@ -912,7 +1255,7 @@ async function runInstances(args, flags, io, client, confirm) {
       return;
     }
     io.stdout(INSTANCES_USAGE);
-    throw new CliError("Unknown instances command");
+    throw new UsageError("Unknown instances command");
   } catch (err) {
     friendly(err);
   }
@@ -979,15 +1322,15 @@ function generateMigrationFile(dir, ops, meta, now = () => /* @__PURE__ */ new D
   const nextVersion = existing.length === 0 ? 1 : existing[existing.length - 1].version + 1;
   const safeSlug = sanitizeSlug(meta.slug);
   const fileName = `${String(nextVersion).padStart(4, "0")}_${safeSlug}.json`;
-  const path = (0, import_path6.join)(dir, fileName);
+  const path2 = (0, import_path6.join)(dir, fileName);
   const file = {
     version: nextVersion,
     createdAt: now().toISOString(),
     parentHashes: meta.parentHashes,
     ops
   };
-  (0, import_fs5.writeFileSync)(path, JSON.stringify(file, null, 2));
-  return path;
+  (0, import_fs5.writeFileSync)(path2, JSON.stringify(file, null, 2));
+  return path2;
 }
 function readMigrations(dir) {
   let entries;
@@ -1000,15 +1343,15 @@ function readMigrations(dir) {
   for (const entry of entries) {
     const match = FILE_NAME_RE.exec(entry);
     if (!match) continue;
-    const path = (0, import_path6.join)(dir, entry);
-    const raw = (0, import_fs5.readFileSync)(path, "utf-8");
+    const path2 = (0, import_path6.join)(dir, entry);
+    const raw = (0, import_fs5.readFileSync)(path2, "utf-8");
     let parsed;
     try {
       parsed = JSON.parse(raw);
     } catch {
-      throw new Error(`Malformed migration file: ${path}`);
+      throw new Error(`Malformed migration file: ${path2}`);
     }
-    files.push({ ...parsed, path });
+    files.push({ ...parsed, path: path2 });
   }
   files.sort((a, b) => a.version - b.version);
   for (let i = 0; i < files.length; i++) {
@@ -1102,11 +1445,11 @@ var HttpError = class extends Error {
     this.name = "HttpError";
   }
 };
-function isRecord(v) {
+function isRecord2(v) {
   return typeof v === "object" && v !== null;
 }
 function parsePartialFailureItem(raw) {
-  const item = isRecord(raw) ? raw : {};
+  const item = isRecord2(raw) ? raw : {};
   const status = typeof item.status === "number" ? item.status : void 0;
   return {
     id: typeof item.id === "string" || typeof item.id === "number" ? String(item.id) : null,
@@ -1147,7 +1490,7 @@ var HeadbandClient = class {
       { ids },
       { allowPartialFailure: true }
     );
-    return isRecord(result) && "partialFailure" in result ? { partialFailure: result.partialFailure } : {};
+    return isRecord2(result) && "partialFailure" in result ? { partialFailure: result.partialFailure } : {};
   }
   async createIndex(uid, opts) {
     const body = { uid };
@@ -1169,11 +1512,11 @@ var HeadbandClient = class {
   async reportRun(run2) {
     await this.request("POST", "/v1/connectors/runs", run2);
   }
-  async request(method, path, body, opts = {}) {
+  async request(method, path2, body, opts = {}) {
     let attempt = 0;
     for (; ; ) {
       attempt += 1;
-      const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
+      const response = await this.fetchImpl(`${this.baseUrl}${path2}`, {
         method,
         headers: {
           Authorization: `Bearer ${this.adminKey}`,
@@ -1230,10 +1573,10 @@ function printOpsTable(io, ops) {
   printTable(io, opRows(ops), ["op", "index", "detail"]);
 }
 function readAppliedMarker(dir) {
-  const path = (0, import_path7.join)(dir, APPLIED_MARKER_FILE);
-  if (!(0, import_fs6.existsSync)(path)) return 0;
+  const path2 = (0, import_path7.join)(dir, APPLIED_MARKER_FILE);
+  if (!(0, import_fs6.existsSync)(path2)) return 0;
   try {
-    const parsed = JSON.parse((0, import_fs6.readFileSync)(path, "utf-8"));
+    const parsed = JSON.parse((0, import_fs6.readFileSync)(path2, "utf-8"));
     return typeof parsed.version === "number" ? parsed.version : 0;
   } catch {
     return 0;
@@ -1243,11 +1586,9 @@ function writeAppliedMarker(dir, version) {
   (0, import_fs6.mkdirSync)(dir, { recursive: true });
   (0, import_fs6.writeFileSync)((0, import_path7.join)(dir, APPLIED_MARKER_FILE), JSON.stringify({ version }, null, 2));
 }
-async function runSchemaDiff(deps) {
+async function planSchemaDiff(deps) {
   const applied = await deps.client.getSchemaState();
-  const ops = planMigration(deps.config, applied, { allowDestructive: deps.allowDestructive });
-  printOpsTable(deps.io, ops);
-  return ops.length > 0 ? 1 : 0;
+  return planMigration(deps.config, applied, { allowDestructive: deps.allowDestructive });
 }
 async function runSchemaGenerate(deps) {
   const applied = await deps.client.getSchemaState();
@@ -1261,20 +1602,19 @@ async function runSchemaGenerate(deps) {
   for (const op of ops) {
     parentHashes[op.index] = appliedByUid.get(op.index)?.schemaHash ?? "";
   }
-  const path = generateMigrationFile(
+  const path2 = generateMigrationFile(
     deps.dir,
     ops,
     { parentHashes, slug: deps.slug ?? "migration" },
     deps.now
   );
-  deps.io.stdout(`Wrote ${path}`);
+  deps.io.stdout(`Wrote ${path2}`);
   printOpsTable(deps.io, ops);
-  return path;
+  return path2;
 }
 function isConflictError(err) {
   if (!(err instanceof Error)) return false;
-  const shaped = err;
-  return shaped.status === 409 || shaped.code === "index_already_exists";
+  return err.code === "index_already_exists";
 }
 async function createIndexIdempotent(ctx, uid, opts) {
   try {
@@ -1482,6 +1822,7 @@ async function runSchemaStatus(deps) {
   const localVersion = readAppliedMarker(deps.dir);
   const localHead = files.length > 0 ? files[files.length - 1].version : 0;
   deps.io.stdout(`Local migrations applied: ${localVersion}/${localHead}`);
+  return { indexes: rows, localApplied: localVersion, localHead };
 }
 
 // src/sync.ts
@@ -1900,11 +2241,11 @@ function runSyncInit(deps) {
   const ddl = outboxDDL(deps.table);
   deps.io.stdout(ddl);
   if (deps.write) {
-    const path = (0, import_path8.join)(deps.cwd ?? process.cwd(), OUTBOX_SQL_RELATIVE_PATH);
+    const path2 = (0, import_path8.join)(deps.cwd ?? process.cwd(), OUTBOX_SQL_RELATIVE_PATH);
     (0, import_fs7.mkdirSync)((0, import_path8.join)(deps.cwd ?? process.cwd(), "headband"), { recursive: true });
-    (0, import_fs7.writeFileSync)(path, `${ddl}
+    (0, import_fs7.writeFileSync)(path2, `${ddl}
 `);
-    deps.io.stdout(`Wrote ${path}`);
+    deps.io.stdout(`Wrote ${path2}`);
   }
   return ddl;
 }
@@ -2027,136 +2368,1265 @@ async function runSyncRetryDeadLetters(deps) {
   return rows.length;
 }
 function runSyncScaffoldDocker(deps) {
-  const path = (0, import_path8.join)(deps.cwd, DOCKERFILE_NAME);
-  if ((0, import_fs7.existsSync)(path) && !deps.force) {
-    throw new CliError(`${DOCKERFILE_NAME} already exists at ${path}. Pass --force to overwrite.`);
+  const path2 = (0, import_path8.join)(deps.cwd, DOCKERFILE_NAME);
+  if ((0, import_fs7.existsSync)(path2) && !deps.force) {
+    throw new CliError(`${DOCKERFILE_NAME} already exists at ${path2}. Pass --force to overwrite.`);
   }
-  (0, import_fs7.writeFileSync)(path, DOCKERFILE_CONTENT);
-  deps.io.stdout(`Wrote ${path}`);
+  (0, import_fs7.writeFileSync)(path2, DOCKERFILE_CONTENT);
+  deps.io.stdout(`Wrote ${path2}`);
   deps.io.stdout("Add this service to your docker-compose.yml:");
   deps.io.stdout(COMPOSE_SNIPPET);
-  return path;
+  return path2;
 }
 
-// src/index.ts
-var ENGINES2 = /* @__PURE__ */ new Set(["meilisearch", "typesense", "elasticsearch"]);
-var KEY_TYPES = /* @__PURE__ */ new Set(["admin", "search"]);
-var VALUE_FLAGS = /* @__PURE__ */ new Set([
-  "--url",
-  "--engine",
-  "--primary-key",
-  "--file",
-  "--index",
-  "--limit",
-  "--filter",
-  "--type",
-  "--project",
-  "--dir",
-  "--slug",
-  "--table",
-  "--scaffold",
-  "--budget-ms",
-  "--batch-size",
-  "--reconcile-every",
-  "--name",
-  "--lane",
-  "--memory",
-  "--region",
-  "--idle-timeout",
-  "--client",
-  "--instance"
-]);
-var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
-  "--json",
-  "--yes",
-  "-y",
-  "--help",
-  "-h",
-  "--allow-destructive",
-  "--write",
-  "--force",
-  "--fix",
-  "--loop"
-]);
-var DEFAULT_MIGRATIONS_DIR = "headband/migrations";
-function parseArgv(argv) {
-  const flags = {};
-  const positional = [];
-  for (let index = 0; index < argv.length; index += 1) {
-    const arg = argv[index];
-    if (!arg.startsWith("-")) {
-      positional.push(arg);
-      continue;
-    }
-    const equalsIndex = arg.indexOf("=");
-    const flagName = equalsIndex === -1 ? arg : arg.slice(0, equalsIndex);
-    const inlineValue = equalsIndex === -1 ? void 0 : arg.slice(equalsIndex + 1);
-    if (VALUE_FLAGS.has(flagName)) {
-      const value = inlineValue ?? argv[index + 1];
-      if (!value || value.startsWith("-")) {
-        throw new CliError(`Missing value for ${flagName}`);
-      }
-      flags[flagName] = value;
-      if (inlineValue === void 0) index += 1;
-      continue;
-    }
-    if (BOOLEAN_FLAGS.has(flagName)) {
-      flags[flagName === "-y" ? "--yes" : flagName === "-h" ? "--help" : flagName] = true;
-      continue;
-    }
-    throw new CliError(`Unknown option: ${arg}`);
-  }
-  return { flags, positional };
+// src/sync-indexes.ts
+var import_fs9 = require("fs");
+
+// src/sync-sources.ts
+var import_fs8 = require("fs");
+var import_pg2 = require("pg");
+
+// ../../src/lib/sync/copy.ts
+var BROAD_ROLE_CONSENT = "BataDB sources currently use a broad role: it can read and write every table in this database. Sync only reads, inside read-only transactions, but the role itself is not limited. A narrower replication role replaces it when BataDB ships one.";
+
+// src/scram.ts
+var import_node_crypto2 = require("crypto");
+var SCRAM_ITERATIONS = 4096;
+var TOKEN = ":'sync_password'";
+var VERIFIER_RE = /^SCRAM-SHA-256\$[1-9][0-9]*:[A-Za-z0-9+/]+={0,2}\$[A-Za-z0-9+/]+={0,2}:[A-Za-z0-9+/]+={0,2}$/;
+function scramVerifier(password, salt = (0, import_node_crypto2.randomBytes)(16), iterations = SCRAM_ITERATIONS) {
+  if (!/^[\x20-\x7e]{1,1024}$/.test(password))
+    throw new Error("The password must be printable ASCII.");
+  const salted = (0, import_node_crypto2.pbkdf2Sync)(password, salt, iterations, 32, "sha256");
+  const clientKey = (0, import_node_crypto2.createHmac)("sha256", salted).update("Client Key").digest();
+  const storedKey = (0, import_node_crypto2.createHash)("sha256").update(clientKey).digest();
+  const serverKey = (0, import_node_crypto2.createHmac)("sha256", salted).update("Server Key").digest();
+  return `SCRAM-SHA-256$${iterations}:${salt.toString("base64")}$${storedKey.toString("base64")}:${serverKey.toString("base64")}`;
 }
-function stringFlag(flags, name) {
-  const value = flags[name];
-  return typeof value === "string" ? value : void 0;
+function newSyncPassword() {
+  return (0, import_node_crypto2.randomBytes)(24).toString("base64url");
 }
-function boolFlag(flags, name) {
-  return flags[name] === true;
+function replaceToken(sql, value) {
+  const parts = sql.split(TOKEN);
+  if (parts.length !== 2)
+    throw new Error("The setup SQL must contain the password token exactly once.");
+  return `${parts[0]}'${value}'${parts[1]}`;
 }
-function requiredFlag(flags, name) {
-  const value = stringFlag(flags, name);
-  if (!value) throw new CliError(`Missing required option: ${name}`);
-  return value;
+function withVerifier(sql, verifier) {
+  if (!VERIFIER_RE.test(verifier))
+    throw new Error("withVerifier takes a SCRAM-SHA-256 verifier, never a plain password.");
+  return replaceToken(sql, verifier);
 }
-function parseLimit(flags) {
-  const raw = stringFlag(flags, "--limit");
-  if (!raw) return void 0;
-  const limit = Number(raw);
-  if (!Number.isInteger(limit) || limit <= 0) {
-    throw new CliError("--limit must be a positive integer");
+function withoutPasswordChange(sql) {
+  return replaceToken(sql, "");
+}
+
+// src/sync-sources.ts
+var SOURCE_USAGE = [
+  "Usage:",
+  "  headband sync source add <name> [--db-url <url>] [--tls-mode verify-full|require] [--ca-file <pem>] [--json]",
+  "  headband sync source add <name> --kind batadb --batadb-project <id> --batadb-branch <id> --batadb-compute <id> --accept-broad-role",
+  "  headband sync source list [--json]",
+  "  headband sync source show <id> [--json]",
+  "  headband sync source test <id> [--json]",
+  "  headband sync source setup-sql <id> [--provider generic|rds|batadb] [--json]",
+  "  headband sync source setup <id> [--owner-url <url>] [--provider generic|rds|batadb] [--yes] [--json]",
+  "  headband sync source set-ca <id> (--ca-file <pem> | --none) [--tls-mode verify-full|require] [--json]",
+  "  headband sync source remove <id> [--yes] [--json]",
+  "",
+  "The source URL can come from HEADBAND_SYNC_DB_URL and the owner URL from HEADBAND_SYNC_OWNER_URL,",
+  "which keeps them out of your shell history. Leave the password out of the source URL: setup makes one.",
+  "A BataDB API key is read from HEADBAND_BATADB_API_KEY only.",
+  "",
+  "--ca-file names a PEM file of CA certificates the source's certificate is verified against, for a",
+  "provider whose CA is not in the system roots. It needs --tls-mode verify-full, the default. On a",
+  "require source, set-ca --ca-file <pem> --tls-mode verify-full changes both in one step.",
+  "",
+  "setup runs the SQL on your machine as the tables' owner, in one transaction. The owner URL never",
+  "leaves this machine. When the SQL creates or changes the Sync role, the owner URL's user must be",
+  "another role. Without sslmode in the owner URL, setup uses TLS and verifies the server's",
+  "certificate, except on localhost."
+].join("\n");
+function readCaFile(deps, file) {
+  let text;
+  try {
+    text = (deps.readFile ?? ((p) => (0, import_fs8.readFileSync)(p, "utf8")))(file);
+  } catch {
+    throw new CliError("Cannot read the --ca-file.");
   }
-  return limit;
+  if (/PRIVATE KEY/.test(text)) {
+    throw new CliError(
+      "The --ca-file holds a private key. Give only the CA certificates. Nothing was sent."
+    );
+  }
+  return text;
 }
-function validateEngine(engine) {
-  if (!ENGINES2.has(engine)) {
-    throw new CliError("Engine must be one of: meilisearch, typesense, elasticsearch");
+var MIN_SERVER_VERSION_NUM = 14e4;
+var OwnerSqlError = class extends CliError {
+  constructor(message, opts) {
+    super(message);
+    this.name = "OwnerSqlError";
+    this.sqlstate = opts.sqlstate;
+    this.hint = opts.hint;
+    this.stage = opts.stage;
+    this.nothingChanged = opts.nothingChanged;
+  }
+};
+var SESSION_PARAMS = [
+  "options",
+  "statement_timeout",
+  "lock_timeout",
+  "idle_in_transaction_session_timeout",
+  "replication"
+];
+var TLS_PARAMS = ["ssl", "sslmode", "sslcert", "sslkey", "sslrootcert", "sslnegotiation"];
+var POOLER_HOST_RE = /pooler|pgbouncer|\.proxy-/;
+var POOLER_PORTS = /* @__PURE__ */ new Set([6543, 6432, 25061]);
+var LOOPBACK = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1"]);
+var URL_IN_TEXT_RE = /postgres(?:ql)?:\/\/\S*/gi;
+var VERIFIER_IN_TEXT_RE = /SCRAM-SHA-256\$\S*/g;
+function decodePart(part) {
+  try {
+    return decodeURIComponent(part);
+  } catch {
+    return part;
   }
-  return engine;
 }
-function validateKeyType(type) {
-  if (!KEY_TYPES.has(type)) {
-    throw new CliError("Key type must be one of: admin, search");
+function parseOwnerUrl(ownerUrl, env) {
+  let url;
+  try {
+    url = new URL(ownerUrl);
+  } catch {
+    throw new CliError("The owner URL is not a valid postgres:// URL.");
   }
-  return type;
+  if (url.protocol !== "postgres:" && url.protocol !== "postgresql:") {
+    throw new CliError("The owner URL must start with postgres:// or postgresql://.");
+  }
+  for (const name of SESSION_PARAMS) {
+    if (url.searchParams.has(name)) {
+      throw new CliError(
+        `Remove ${name} from the owner URL: setup sets nothing on the session, and poolers refuse it.`
+      );
+    }
+  }
+  const host = (url.searchParams.get("host") || decodePart(url.hostname)).replace(/^\[|\]$/g, "").toLowerCase() || "localhost";
+  const port = Number(url.searchParams.get("port") || url.port || 5432);
+  const database = decodePart(url.pathname.replace(/^\//, "")) || null;
+  const user = url.searchParams.get("user") || decodePart(url.username) || env.PGUSER || env.USER || env.USERNAME || null;
+  return { url, host, port, database, user };
 }
-function encode(value) {
-  return encodeURIComponent(value);
+function ownerClientConfig(ownerUrl, env = process.env) {
+  const target = parseOwnerUrl(ownerUrl, env);
+  for (const name of ["PGOPTIONS", "PGREPLICATION"]) {
+    if (env[name]) {
+      throw new CliError(
+        `${name} is set in your environment. Unset it: setup sets nothing on the session.`
+      );
+    }
+  }
+  const urlChoosesTls = TLS_PARAMS.some((p) => target.url.searchParams.has(p)) || Boolean(env.PGSSLMODE);
+  const local = target.host.startsWith("/") || LOOPBACK.has(target.host);
+  return {
+    connectionString: ownerUrl,
+    connectionTimeoutMillis: 15e3,
+    keepAlive: true,
+    ...urlChoosesTls || local ? {} : { ssl: true }
+  };
 }
-function clientFromFlags(flags) {
-  const { url, profile } = getProfile(stringFlag(flags, "--url"));
-  return createApiClient(url, profile);
+function looksLikePooler(host, port) {
+  return POOLER_HOST_RE.test(host) || POOLER_PORTS.has(port);
 }
-async function confirmOrSkip(message, flags) {
-  if (boolFlag(flags, "--yes")) return true;
-  const answer = await (0, import_prompts2.default)({
-    type: "confirm",
-    name: "confirmed",
-    message,
-    initial: false
+function scrubSecrets(text, secrets) {
+  let out = text;
+  const known = secrets.filter((s) => Boolean(s)).sort((a, b) => b.length - a.length);
+  for (const s of known) out = out.split(s).join("[hidden]");
+  return out.replace(URL_IN_TEXT_RE, "[connection URL]").replace(VERIFIER_IN_TEXT_RE, "[verifier]");
+}
+function ownerSecrets(ownerUrl, env) {
+  const out = [ownerUrl, env.PGPASSWORD ?? ""];
+  try {
+    const u = new URL(ownerUrl);
+    out.push(u.password, decodePart(u.password), u.searchParams.get("password") ?? "");
+  } catch {
+  }
+  return out;
+}
+function checkServerVersion(versionNum) {
+  if (!Number.isInteger(versionNum) || versionNum < MIN_SERVER_VERSION_NUM) {
+    const major = Number.isInteger(versionNum) ? Math.floor(versionNum / 1e4) : "unknown";
+    throw new OwnerSqlError(
+      `This server runs Postgres ${major}. Sync needs Postgres 14 or later.`,
+      { stage: "connect", nothingChanged: true }
+    );
+  }
+}
+function connectHint(message) {
+  if (/certificate|self[- ]signed|altnames/i.test(message)) {
+    return "Setup verifies the server's certificate, as sslmode=verify-full does. Trust your provider's CA with NODE_EXTRA_CA_CERTS=<file>, or add sslrootcert=<file> to the owner URL.";
+  }
+  if (/does not support SSL/i.test(message)) {
+    return "Add sslmode=disable to the owner URL only if this connection runs on a network you trust.";
+  }
+  return void 0;
+}
+function toOwnerSqlError(err, stage, secrets) {
+  const e = typeof err === "object" && err !== null ? err : {};
+  const fromServer = typeof e.code === "string" && /^[0-9A-Z]{5}$/.test(e.code) && typeof e.severity === "string";
+  const message = scrubSecrets(
+    // Node's AggregateError (both addresses of localhost refused) has an empty message.
+    typeof e.message === "string" && e.message ? e.message : String(e.errors?.[0]?.message ?? (typeof e.code === "string" ? e.code : err)),
+    secrets
+  );
+  const serverHint = typeof e.hint === "string" && e.hint ? scrubSecrets(e.hint, secrets) : void 0;
+  return new OwnerSqlError(message, {
+    sqlstate: fromServer ? e.code : void 0,
+    hint: serverHint ?? (stage === "connect" ? connectHint(message) : void 0),
+    stage,
+    // An ERROR aborts the transaction, and the rollback follows. A FATAL or a dropped connection
+    // mid-run is unknown: a FATAL (57P01 waiting for a synchronous standby) can follow a local commit.
+    nothingChanged: stage === "connect" || fromServer && e.severity === "ERROR"
+  });
+}
+async function runOwnerSqlWithPg(ownerUrl, sqlText) {
+  const config = ownerClientConfig(ownerUrl);
+  const secrets = ownerSecrets(ownerUrl, process.env);
+  let client;
+  try {
+    client = new import_pg2.Client(config);
+  } catch (err) {
+    throw toOwnerSqlError(err, "connect", secrets);
+  }
+  client.on("error", () => void 0);
+  let connected = false;
+  let stage = "connect";
+  try {
+    await client.connect();
+    connected = true;
+    await client.query("BEGIN");
+    await client.query("SET LOCAL statement_timeout = '60s'");
+    const version = await client.query(
+      "SELECT current_setting('server_version_num')::int AS num"
+    );
+    checkServerVersion(Number(version.rows[0]?.num));
+    stage = "run";
+    await client.query(sqlText);
+    await client.query("COMMIT");
+  } catch (err) {
+    if (connected) await client.query("ROLLBACK").catch(() => void 0);
+    throw err instanceof OwnerSqlError ? err : toOwnerSqlError(err, stage, secrets);
+  } finally {
+    await client.end().catch(() => void 0);
+  }
+}
+function friendlySyncError(err) {
+  if (err instanceof ApiError) {
+    if (err.status === 404 && err.code === "not_found") {
+      throw new CliError("Sync is not enabled for this organization yet.");
+    }
+    if (err.status === 403 && err.code === "permission_denied") {
+      throw new CliError(
+        "This CLI key cannot manage Sync. Run headband login again to get a key that can."
+      );
+    }
+  }
+  throw err;
+}
+var SOURCE_ID_RE = /^src_[a-z0-9]{12}$/;
+var SOURCE_NAME_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+var PROVIDERS = ["generic", "rds", "batadb"];
+var TLS_MODES = ["verify-full", "require"];
+var str = (flags, name) => typeof flags[name] === "string" ? flags[name] : void 0;
+var sourcePath = (id, suffix = "") => `/v1/sync/sources/${encodeURIComponent(id)}${suffix}`;
+var setupSqlPath = (id, provider) => sourcePath(id, `/setup-sql${provider ? `?provider=${encodeURIComponent(provider)}` : ""}`);
+var mark = (ok) => ok ? "ok  " : "FAIL";
+var plural = (n, word) => `${n} ${word}${n === 1 ? "" : "s"}`;
+function choiceFlag(flags, name, choices) {
+  const value = str(flags, name);
+  if (value !== void 0 && !choices.includes(value)) {
+    throw new CliError(
+      `${name} must be ${choices.slice(0, -1).join(", ")} or ${choices[choices.length - 1]}.`
+    );
+  }
+  return value;
+}
+function checkedId(value, re, shape, listCommand) {
+  if (!re.test(value)) {
+    throw new CliError(
+      `Expected ${shape}, and got something else. Run ${listCommand} to see them.`
+    );
+  }
+  return value;
+}
+var SOURCE_ID_SHAPE = "a source id like src_ followed by 12 lowercase letters or digits";
+var SOURCE_ID_PATTERN = SOURCE_ID_RE;
+function requireSourceId(args) {
+  const id = args[1];
+  if (!id) throw new CliError("Missing source id (headband sync source list shows them).");
+  return checkedId(id, SOURCE_ID_RE, SOURCE_ID_SHAPE, "headband sync source list");
+}
+function printChecks(io, checks) {
+  const width = Math.max(4, ...checks.map((c) => c.name.length));
+  for (const c of checks) io.stdout(`${mark(c.ok)}  ${c.name.padEnd(width)}  ${c.detail}`);
+}
+function lastTested(s) {
+  if (!s.lastTest) return "never";
+  const failed = s.lastTest.checks.filter((c) => !c.ok).length;
+  return failed === 0 ? `passed ${s.lastTest.at}` : `${failed} failed ${s.lastTest.at}`;
+}
+function roleKey(url) {
+  try {
+    const u = new URL(url);
+    const port = u.port ? Number(u.port) : 5432;
+    return {
+      host: u.hostname.toLowerCase().replace(/^\[|\]$/g, ""),
+      port,
+      username: decodeURIComponent(u.username)
+    };
+  } catch {
+    return null;
+  }
+}
+async function runAdd(args, flags, deps, env) {
+  const { io, client } = deps;
+  const name = args[1];
+  if (!name) throw new CliError("Missing source name.");
+  if (!SOURCE_NAME_RE.test(name)) {
+    throw new CliError(
+      "A source name is 1 to 64 lowercase letters, digits, _ or -, starting with a letter or digit."
+    );
+  }
+  const url = str(flags, "--db-url") ?? env.HEADBAND_SYNC_DB_URL;
+  if (!url) {
+    throw new CliError("Give the source's connection URL with --db-url or HEADBAND_SYNC_DB_URL.");
+  }
+  const kind = str(flags, "--kind") ?? "postgres";
+  if (kind !== "postgres" && kind !== "batadb")
+    throw new CliError("--kind must be postgres or batadb.");
+  const ids = {
+    projectId: str(flags, "--batadb-project"),
+    branchId: str(flags, "--batadb-branch"),
+    computeId: str(flags, "--batadb-compute")
+  };
+  const body = { name, url };
+  const tlsMode = choiceFlag(flags, "--tls-mode", TLS_MODES);
+  if (tlsMode) body.tlsMode = tlsMode;
+  const caFile = str(flags, "--ca-file");
+  if (caFile) body.tlsCaPem = readCaFile(deps, caFile);
+  if (kind === "batadb") {
+    if (flags["--accept-broad-role"] !== true) {
+      io.stderr(BROAD_ROLE_CONSENT);
+      throw new CliError(
+        "A BataDB source needs your consent to that role: add --accept-broad-role."
+      );
+    }
+    if (!ids.projectId || !ids.branchId || !ids.computeId) {
+      throw new CliError(
+        "A BataDB source needs --batadb-project, --batadb-branch and --batadb-compute."
+      );
+    }
+    body.kind = "batadb";
+    body.batadb = {
+      ...ids,
+      acceptBroadRole: true,
+      ...env.HEADBAND_BATADB_API_KEY ? { apiKey: env.HEADBAND_BATADB_API_KEY } : {}
+    };
+  } else {
+    if (ids.projectId || ids.branchId || ids.computeId) {
+      throw new CliError("The --batadb-* options are for --kind batadb.");
+    }
+    const key = roleKey(url);
+    if (key) {
+      const existing = (await client.get("/v1/sync/sources")).data;
+      const other = existing.find(
+        (s2) => s2.kind === "postgres" && s2.host === key.host && s2.port === key.port && s2.username === key.username
+      );
+      if (other) {
+        throw new CliError(
+          `Source ${other.id} (${other.name}) already uses the user ${key.username} on ${key.host}:${key.port}. Each source needs its own role, and setup never changes a role made for another source: give this source a user name no other source uses on that server.`
+        );
+      }
+    }
+  }
+  const res = await client.post("/v1/sync/sources", body);
+  if (flags["--json"] === true) return printJson(io, res);
+  const s = res.data;
+  io.stdout(
+    `Created source ${s.id} (${s.name}): ${s.host}:${s.port}/${s.database} as ${s.username}.`
+  );
+  if (s.kind === "postgres" && s.hasPassword) {
+    io.stderr(
+      `Note: the URL has a password, so setup keeps it and makes no new one. The setup SQL creates a missing role only with a password, so ${s.username} must already be Headband's role for this source. Otherwise run the setup SQL yourself with that password (headband sync source setup-sql ${s.id} shows the psql command), or add the source again without a password.`
+    );
+  }
+  io.stdout("Next: create the role and publication as the tables' owner:");
+  io.stdout(`  headband sync source setup ${s.id} --owner-url <owner URL>`);
+  io.stdout(`or print the SQL to run yourself: headband sync source setup-sql ${s.id}`);
+}
+function roleEffect(user, provider, mode) {
+  const attrs = provider === "rds" ? "LOGIN and membership in rds_replication" : "LOGIN REPLICATION";
+  if (mode === "none") return `creates and changes no role: BataDB manages ${user}.`;
+  const guard = `Any other role named ${user} stops the SQL, and nothing changes.`;
+  if (mode === "new") {
+    return `creates the role ${user} (${attrs}) with a new password, or, when ${user} exists and Headband Sync created it for this source, gives it that new password and ${attrs}. ${guard}`;
+  }
+  return `creates no role and keeps the password Headband has: it gives ${user} ${attrs} only when Headband Sync created ${user} for this source. A missing role stops the SQL too. ${guard}`;
+}
+function confirmQuestion(owner, user, pub, mode) {
+  const as = `Run it now as ${owner}?`;
+  if (mode === "none")
+    return `${as} It creates or updates the publication ${pub} and changes no role.`;
+  if (mode === "new") {
+    return `${as} It creates the role ${user}, or updates ${user} only if Headband Sync created it for this source.`;
+  }
+  return `${as} It creates no role, and updates ${user} only if Headband Sync created it for this source.`;
+}
+function ownerFailure(err, ctx, secrets) {
+  const info = err instanceof OwnerSqlError ? err : void 0;
+  const reason = scrubSecrets(err instanceof Error ? err.message : String(err), secrets);
+  const lines = [
+    info?.stage === "connect" ? `Could not run the setup SQL as the owner: ${reason}` : `The setup SQL failed on your database: ${reason}`
+  ];
+  let advice;
+  const state = info?.sqlstate;
+  if (state === "42710" && reason.includes("was not created by Headband Sync")) {
+    advice = `Sync changes only a role it created for this source, so ${ctx.user} stays as it is. Each source needs its own role: use a user name that does not exist on this server yet (add a new source with it), then run its setup.`;
+  } else if (state === "42710" && reason.includes("carries the Headband Sync marker")) {
+    advice = `${ctx.user} is Headband's role for this source, but another role is its member or admin, or it has SUPERUSER, CREATEROLE or BYPASSRLS. It needs none of these: remove them, then run setup again.`;
+  } else if (state === "22023" && reason.includes("does not exist yet") && ctx.mode === "keep") {
+    advice = `This source's URL has a password, so setup keeps it and makes no new one, and the SQL creates a missing role only with a password. Run the setup SQL yourself with psql and that password (headband sync source setup-sql ${ctx.id} shows the command), or add the source again without a password so setup makes one.`;
+  } else if (state === "42501") {
+    advice = "Run setup as the tables' owner, a role that can also create roles and publications.";
+  } else if (state === "55P03") {
+    advice = "Another transaction held a lock on one of these tables for over 5 seconds. Run setup again when it is quiet.";
+  }
+  if (advice) lines.push(advice);
+  else if (info?.hint) lines.push(`Hint: ${scrubSecrets(info.hint, secrets)}`);
+  if (info && !info.nothingChanged) {
+    lines.push(
+      "The connection failed while the SQL ran. Postgres rolls back a transaction that does not commit, and Headband was not updated. Run setup again: it is safe to repeat."
+    );
+  } else if (info?.stage === "connect") {
+    lines.push("Nothing changed on your database or in Headband.");
+  } else {
+    lines.push("Nothing changed: the transaction rolled back, and Headband was not updated.");
+  }
+  return new CliError(lines.join("\n"));
+}
+async function runSetup(args, flags, deps, env) {
+  const { client } = deps;
+  const json = flags["--json"] === true;
+  const io = json ? { stdout: deps.io.stderr, stderr: deps.io.stderr } : deps.io;
+  const id = requireSourceId(args);
+  const ownerUrl = str(flags, "--owner-url") ?? env.HEADBAND_SYNC_OWNER_URL;
+  if (!ownerUrl) {
+    throw new CliError(
+      "Give the tables' owner URL with --owner-url or HEADBAND_SYNC_OWNER_URL. It never leaves this machine."
+    );
+  }
+  ownerClientConfig(ownerUrl, env);
+  const owner = parseOwnerUrl(ownerUrl, env);
+  const provider = choiceFlag(flags, "--provider", PROVIDERS);
+  const source = (await client.get(sourcePath(id))).data;
+  if (source.state === "deleting") throw new CliError(`Source ${id} is being removed.`);
+  const setup = (await client.get(setupSqlPath(id, provider))).data;
+  if (setup.needsPassword && owner.user === source.username) {
+    throw new CliError(
+      `The owner URL logs in as ${source.username}, the user Sync reads with. The setup SQL creates or updates that role, so run it as the tables' owner, a different role.`
+    );
+  }
+  if (looksLikePooler(owner.host, owner.port)) {
+    io.stderr(
+      `Warning: the owner host (${owner.host}:${owner.port}) looks like a connection pooler. Setup runs one transaction and sets nothing on the session, but if the pooler refuses it, use the database's direct host.`
+    );
+  }
+  if (owner.host !== source.host) {
+    io.stderr(
+      `Note: the owner URL's host (${owner.host}) differs from the source's (${source.host}). Make sure both reach the same database.`
+    );
+  }
+  let password = null;
+  let verifier = null;
+  let mode;
+  let sqlText;
+  try {
+    if (!setup.needsPassword) {
+      mode = "none";
+      sqlText = setup.sql;
+    } else if (source.hasPassword) {
+      mode = "keep";
+      sqlText = withoutPasswordChange(setup.sql);
+    } else {
+      mode = "new";
+      password = (deps.newPassword ?? newSyncPassword)();
+      verifier = scramVerifier(password);
+      sqlText = withVerifier(setup.sql, verifier);
+    }
+  } catch {
+    throw new CliError(
+      "Headband's setup SQL is not in the shape this CLI expects. Update @headband/cli and try again."
+    );
+  }
+  const ownerName = owner.user ?? "the owner URL's user";
+  const where = `${owner.host}:${owner.port}${owner.database ? `/${owner.database}` : ""}`;
+  io.stdout(`Setup runs Headband's SQL on ${where} as ${ownerName}, in one transaction. It:`);
+  io.stdout(`  - ${roleEffect(source.username, setup.provider, mode)}`);
+  if (setup.needsPassword && setup.tables.length > 0) {
+    io.stdout(
+      `  - grants ${source.username} SELECT on ${setup.tables.join(", ")}, and USAGE on their schemas.`
+    );
+  }
+  io.stdout(
+    setup.tables.length > 0 ? `  - creates the publication ${source.publicationName} when it is missing, and sets it to exactly these tables: ${setup.tables.join(", ")}.` : `  - creates the publication ${source.publicationName} when it is missing. No synced index reads a table yet, so it lists none.`
+  );
+  io.stdout(
+    mode === "new" ? "Only the new password goes to Headband. The owner URL stays on this machine." : "Nothing goes to Headband but the test that follows. The owner URL stays on this machine."
+  );
+  for (const n of setup.notes) io.stderr(`Note: ${n}`);
+  if (!await deps.confirm(confirmQuestion(ownerName, source.username, source.publicationName, mode))) {
+    throw new CliError("Cancelled. Nothing changed.");
+  }
+  const secrets = [
+    ...ownerSecrets(ownerUrl, env),
+    password,
+    verifier,
+    env.HEADBAND_SYNC_DB_URL,
+    env.HEADBAND_BATADB_API_KEY
+  ];
+  try {
+    await (deps.runOwnerSql ?? runOwnerSqlWithPg)(ownerUrl, sqlText);
+  } catch (err) {
+    throw ownerFailure(err, { id, user: source.username, mode }, secrets);
+  }
+  io.stdout("Setup SQL applied.");
+  if (password) {
+    try {
+      await client.patch(sourcePath(id), { password });
+    } catch (err) {
+      io.stderr(
+        "The role is set up, but Headband did not take its password. Run this setup again: it is safe to repeat."
+      );
+      throw err;
+    }
+  }
+  let res;
+  try {
+    res = await client.post(sourcePath(id, "/test"), {});
+  } catch (err) {
+    io.stderr(
+      `Setup is done, but the source test did not run. Run it with: headband sync source test ${id}`
+    );
+    throw err;
+  }
+  io.stdout(`Tested from ${res.data.boxId}:`);
+  printChecks(io, res.data.checks);
+  const failed = res.data.checks.filter((c) => !c.ok).length;
+  if (failed > 0) {
+    throw new CliError(
+      `${plural(failed, "check")} failed. Fix them, then run headband sync source test ${id}.`
+    );
+  }
+  io.stdout(
+    res.data.activated ? "The source is ready and active. Its synced indexes start backfilling." : "The source is ready."
+  );
+  if (json) {
+    printJson(deps.io, {
+      data: {
+        id,
+        provider: setup.provider,
+        password: mode,
+        boxId: res.data.boxId,
+        activated: res.data.activated,
+        checks: res.data.checks
+      }
+    });
+  }
+}
+async function runSyncSource(args, flags, deps) {
+  const { io, client } = deps;
+  const env = deps.env ?? process.env;
+  const json = flags["--json"] === true;
+  const action = args[0];
+  try {
+    if (action === "add") return await runAdd(args, flags, deps, env);
+    if (action === "setup") return await runSetup(args, flags, deps, env);
+    if (action === "list") {
+      const res = await client.get("/v1/sync/sources");
+      if (json) return printJson(io, res);
+      if (res.data.length === 0) {
+        io.stdout("No sources yet. Add one with: headband sync source add <name> --db-url <url>");
+        return;
+      }
+      printTable(
+        io,
+        res.data.map((s) => ({
+          id: s.id,
+          name: s.name,
+          kind: s.kind,
+          host: s.host,
+          state: s.state,
+          "last test": lastTested(s)
+        })),
+        ["id", "name", "kind", "host", "state", "last test"]
+      );
+      return;
+    }
+    if (action === "show") {
+      const res = await client.get(sourcePath(requireSourceId(args)));
+      if (json) return printJson(io, res);
+      const s = res.data;
+      const lines = [
+        ["id", s.id],
+        ["name", s.name],
+        ["kind", s.kind],
+        ["host", `${s.host}:${s.port}`],
+        ["database", s.database],
+        ["user", `${s.username}${s.hasPassword ? "" : " (no password yet)"}`],
+        ["tls", s.tlsMode],
+        ["ca bundle", s.tlsCaPem ? "set" : "system roots"],
+        ["capture", s.captureMode],
+        ["publication", s.publicationName],
+        ["state", s.error ? `${s.state}: ${s.error}` : s.state],
+        ["postgres", s.serverVersion === null ? "unknown" : String(s.serverVersion)],
+        ["last test", lastTested(s)]
+      ];
+      const width = Math.max(...lines.map(([k]) => k.length));
+      for (const [k, v] of lines) io.stdout(`${k.padEnd(width)}  ${v}`);
+      if (s.lastTest) printChecks(io, s.lastTest.checks);
+      return;
+    }
+    if (action === "test") {
+      const id = requireSourceId(args);
+      const res = await client.post(sourcePath(id, "/test"), {});
+      const failed = res.data.checks.filter((c) => !c.ok).length;
+      if (json) {
+        printJson(io, res);
+        if (failed > 0) throw new CliError(`${plural(failed, "check")} failed.`);
+        return;
+      }
+      io.stdout(`Tested from ${res.data.boxId}:`);
+      printChecks(io, res.data.checks);
+      if (failed > 0) {
+        io.stdout(
+          `Fix the failed checks, then test again. The setup SQL: headband sync source setup-sql ${id}`
+        );
+        throw new CliError(`${plural(failed, "check")} failed.`);
+      }
+      io.stdout(
+        res.data.activated ? "All checks passed. The source is active, and its synced indexes start backfilling." : "All checks passed."
+      );
+      return;
+    }
+    if (action === "setup-sql") {
+      const id = requireSourceId(args);
+      const res = await client.get(
+        setupSqlPath(id, choiceFlag(flags, "--provider", PROVIDERS))
+      );
+      if (json) return printJson(io, res);
+      io.stdout(res.data.sql.trimEnd());
+      for (const n of res.data.notes) io.stderr(`Note: ${n}`);
+      return;
+    }
+    if (action === "set-ca") {
+      const id = requireSourceId(args);
+      const caFile = str(flags, "--ca-file");
+      const none = flags["--none"] === true;
+      if (Boolean(caFile) === none)
+        throw new CliError("Give exactly one of --ca-file <pem> or --none.");
+      const tlsMode = choiceFlag(flags, "--tls-mode", TLS_MODES);
+      if (caFile && tlsMode === "require") {
+        throw new CliError(
+          "A CA bundle verifies the source's certificate, so it needs --tls-mode verify-full."
+        );
+      }
+      const body = {
+        tlsCaPem: none ? null : readCaFile(deps, caFile)
+      };
+      if (tlsMode) body.tlsMode = tlsMode;
+      const res = await client.patch(sourcePath(id), body);
+      if (json) return printJson(io, res);
+      const mode = tlsMode ? `, and set its TLS mode to ${tlsMode}` : "";
+      io.stdout(
+        !none ? `Set the CA bundle of ${id}${mode}. The box reconnects with it.` : tlsMode === "require" ? `Cleared the CA bundle of ${id}${mode}. The box reconnects encrypted, without verifying the certificate.` : `Cleared the CA bundle of ${id}${mode}. The box verifies against the system roots.`
+      );
+      return;
+    }
+    if (action === "remove") {
+      const id = requireSourceId(args);
+      if (!await deps.confirm(`Remove source ${id}? Sync drops its replication slots.`)) {
+        throw new CliError("Cancelled. Nothing changed.");
+      }
+      const res = await client.delete(sourcePath(id));
+      if (json) return printJson(io, res);
+      io.stdout(
+        res.data.deleted ? `Removed source ${id}.` : `Removing source ${id}: its pipelines are stopping.`
+      );
+      io.stdout("Run this as the tables' owner to finish:");
+      io.stdout(res.dropPublicationSql.trimEnd());
+      return;
+    }
+    io.stdout(SOURCE_USAGE);
+    throw new CliError("Unknown sync source command");
+  } catch (err) {
+    friendlySyncError(err);
+  }
+}
+
+// src/sync-indexes.ts
+var INDEX_USAGE = [
+  "Usage:",
+  "  headband sync index create -f <file.sync.json> [--json]",
+  "  headband sync index list [--source <id>] [--instance <id>] [--json]",
+  "  headband sync index show <id> [--version <n>] [--json]",
+  "  headband sync index update <id> -f <file.sync.json> [--rebuild] [--json]",
+  "  headband sync index validate -f <file.sync.json> [--index <id>] [--json]",
+  "  headband sync index preview <id> [--ids <id,id,...>] [-f <file.sync.json>] [--json]",
+  "  headband sync index rebuild|pause|resume|check <id> [--yes] [--json]",
+  "  headband sync index remove <id> [--drop-index] [--yes] [--json]",
+  "  headband sync status [--json]"
+].join("\n");
+var SYNC_INDEX_ID_RE = /^sx_[a-z0-9]{12}$/;
+var INSTANCE_ID_RE = /^i[a-z0-9]{12}$/;
+var PREVIEW_MAX_IDS = 20;
+var ATTENTION_INDEX = /* @__PURE__ */ new Set(["error", "needs_rebuild", "awaiting_setup", "degraded"]);
+var ATTENTION_SOURCE = /* @__PURE__ */ new Set(["error", "awaiting_setup"]);
+var path = (id, suffix = "") => `/v1/sync/indexes/${encodeURIComponent(id)}${suffix}`;
+function readDefinition(file, readFile = (p) => (0, import_fs9.readFileSync)(p, "utf8")) {
+  let text;
+  try {
+    text = readFile(file);
+  } catch {
+    throw new CliError(`Cannot read ${file}.`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new CliError(`${file} is not valid JSON.`);
+  }
+}
+function printIssues(io, issues) {
+  for (const i of issues) io.stderr(`${i.path ? `${i.path}: ` : ""}${i.message} (${i.code})`);
+}
+function issuesOf(err) {
+  if (!(err instanceof ApiError) || typeof err.details !== "object" || err.details === null)
+    return [];
+  const issues = err.details.issues;
+  return Array.isArray(issues) ? issues : [];
+}
+var INDEX_ID_SHAPE = "a synced index id like sx_ followed by 12 lowercase letters or digits";
+var LIST_INDEXES = "headband sync index list";
+function requireIndexId(args) {
+  const id = args[1];
+  if (!id) throw new CliError(`Missing synced index id (${LIST_INDEXES} shows them).`);
+  return checkedId(id, SYNC_INDEX_ID_RE, INDEX_ID_SHAPE, LIST_INDEXES);
+}
+function idFlag(flags, name, re, shape, listCommand) {
+  const value = str(flags, name);
+  return value === void 0 ? void 0 : checkedId(value, re, shape, listCommand);
+}
+function indexApiError(err, id) {
+  if (err instanceof ApiError) {
+    if (err.status === 409 && err.code === "index_managed_by_sync") {
+      throw new CliError(
+        `${err.message} Change its definition with headband sync index update <id> -f <file>.`
+      );
+    }
+    if (err.status === 409 && err.code === "index_dropping" && id) {
+      throw new CliError(
+        `${err.message} Finish with: headband sync index remove ${id} --drop-index`
+      );
+    }
+    if (err.status === 409 && err.code === "not_on_box_yet" && id) {
+      throw new CliError(`${err.message} Watch it start with: headband sync index show ${id}`);
+    }
+  }
+  return friendlySyncError(err);
+}
+function fileFlag(flags, deps, required) {
+  const file = str(flags, "--file");
+  if (!file) {
+    if (required) throw new CliError("Give the definition file with -f <file.sync.json>.");
+    return void 0;
+  }
+  return readDefinition(file, deps.readFile);
+}
+function stateLine(i) {
+  if (i.error) return `${i.state}: ${i.errorCode ?? "error"}: ${i.error}`;
+  if (i.build) return `${i.state} (${i.build.phase}, ${i.build.rendered} rendered)`;
+  return i.state;
+}
+function lag(i) {
+  return i.lagMs === null ? "" : i.lagMs < 1e3 ? `${i.lagMs} ms` : `${Math.round(i.lagMs / 100) / 10} s`;
+}
+function printClassification(io, c) {
+  if (!c) return;
+  io.stdout(`Change: ${c.class}${c.reasons.length ? ` (${c.reasons.join("; ")})` : ""}`);
+}
+async function runSyncIndex(args, flags, deps) {
+  const { io, client } = deps;
+  const json = flags["--json"] === true;
+  const action = args[0];
+  try {
+    if (action === "create") {
+      const definition = fileFlag(flags, deps, true);
+      const res = await client.post("/v1/sync/indexes", definition);
+      if (json) return printJson(io, res);
+      io.stdout(`Created synced index ${res.data.id} (${res.data.name}): ${stateLine(res.data)}.`);
+      if (res.data.state === "awaiting_setup") {
+        io.stdout(
+          `Its tables are not published yet. Run the setup again: headband sync source setup ${res.data.sourceId}`
+        );
+      } else {
+        io.stdout(`Watch it with: headband sync index show ${res.data.id}`);
+      }
+      return;
+    }
+    if (action === "list") {
+      const q = new URLSearchParams();
+      const source = idFlag(
+        flags,
+        "--source",
+        SOURCE_ID_PATTERN,
+        SOURCE_ID_SHAPE,
+        "headband sync source list"
+      );
+      const instance = idFlag(
+        flags,
+        "--instance",
+        INSTANCE_ID_RE,
+        "an engine id like i followed by 12 lowercase letters or digits",
+        "headband instances list"
+      );
+      if (source) q.set("source", source);
+      if (instance) q.set("instance", instance);
+      const qs = q.toString();
+      const res = await client.get(
+        `/v1/sync/indexes${qs ? `?${qs}` : ""}`
+      );
+      if (json) return printJson(io, res);
+      if (res.data.length === 0) {
+        io.stdout(
+          "No synced indexes yet. Create one with: headband sync index create -f <file.sync.json>"
+        );
+        return;
+      }
+      printTable(
+        io,
+        res.data.map((i) => ({
+          id: i.id,
+          name: i.name,
+          source: i.sourceId,
+          instance: i.instanceId,
+          state: stateLine(i),
+          lag: lag(i),
+          documents: i.documents ?? "",
+          pending: i.pendingChanges || i.definitionPending ? "yes" : ""
+        })),
+        ["id", "name", "source", "instance", "state", "lag", "documents", "pending"]
+      );
+      return;
+    }
+    if (action === "show") {
+      const id = requireIndexId(args);
+      const version = str(flags, "--version");
+      if (version !== void 0) {
+        if (!/^[1-9]\d{0,8}$/.test(version))
+          throw new CliError("--version must be a positive whole number.");
+        const res2 = await client.get(
+          path(id, `?version=${version}`)
+        );
+        if (json) return printJson(io, res2);
+        io.stdout(JSON.stringify(res2.data.definition, null, 2));
+        return;
+      }
+      const res = await client.get(path(id));
+      const jobs = await client.get(path(id, "/jobs?limit=5"));
+      if (json) return printJson(io, { data: res.data, jobs: jobs.data });
+      const i = res.data;
+      const lines = [
+        ["id", i.id],
+        ["name", i.name],
+        ["source", i.sourceId],
+        ["instance", i.instanceId],
+        ["state", stateLine(i)],
+        ["desired", i.desired],
+        [
+          "definition",
+          `version ${i.definitionVersion}${i.servingDefinitionVersion !== null && i.servingDefinitionVersion !== i.definitionVersion ? `, serving ${i.servingDefinitionVersion}` : ""}${i.definitionPending ? " (waits for a rebuild)" : ""}`
+        ],
+        ["physical", i.physicalName],
+        ["documents", i.documents === null ? "unknown" : String(i.documents)],
+        ["lag", lag(i) || "unknown"],
+        ["dead letters", String(i.deadLetters)],
+        ["last applied", i.lastAppliedAt ?? "never"],
+        ["pending", i.pendingChanges ? "a change has not reached the box yet" : "no"]
+      ];
+      const width = Math.max(...lines.map(([k]) => k.length));
+      for (const [k, v] of lines) io.stdout(`${k.padEnd(width)}  ${v}`);
+      if (jobs.data.length > 0) {
+        io.stdout("");
+        printTable(
+          io,
+          jobs.data.map((j) => ({
+            job: j.id,
+            kind: j.kind,
+            trigger: j.trigger,
+            state: j.state,
+            started: j.startedAt,
+            error: j.error ?? ""
+          })),
+          ["job", "kind", "trigger", "state", "started", "error"]
+        );
+      }
+      return;
+    }
+    if (action === "update") {
+      const id = requireIndexId(args);
+      const definition = fileFlag(flags, deps, true);
+      const rebuild = flags["--rebuild"] === true;
+      const res = await client.patch(path(id), {
+        definition,
+        ...rebuild ? { rebuild: true } : {}
+      });
+      if (json) return printJson(io, res);
+      if (res.saved) io.stdout(`Saved version ${res.data.definitionVersion}.`);
+      else io.stdout(`No definition change${rebuild ? "; rebuild requested." : "."}`);
+      printClassification(io, res.classification);
+      if (res.saved && rebuild)
+        io.stdout("Rebuild requested: the new version serves once it finishes.");
+      if (res.saved && !rebuild)
+        io.stdout(`It takes effect at the next rebuild: headband sync index rebuild ${id}`);
+      return;
+    }
+    if (action === "validate") {
+      const definition = fileFlag(flags, deps, true);
+      const syncIndexId = idFlag(flags, "--index", SYNC_INDEX_ID_RE, INDEX_ID_SHAPE, LIST_INDEXES);
+      const res = await client.post("/v1/sync/indexes/validate", { definition, ...syncIndexId ? { syncIndexId } : {} });
+      if (json) return printJson(io, res);
+      printIssues(io, res.data.errors);
+      for (const w of res.data.warnings)
+        io.stderr(`Warning: ${w.path ? `${w.path}: ` : ""}${w.message} (${w.code})`);
+      if (!res.data.valid) throw new CliError("The definition is not valid.");
+      io.stdout(`Valid${res.data.checkedOnBox ? ", checked against the source" : ""}.`);
+      printClassification(io, res.data.classification);
+      return;
+    }
+    if (action === "preview") {
+      const id = requireIndexId(args);
+      const rawIds = str(flags, "--ids");
+      const ids = rawIds?.split(",").map((s) => s.trim()).filter(Boolean);
+      if (ids && ids.length > PREVIEW_MAX_IDS)
+        throw new CliError(`Preview renders at most ${PREVIEW_MAX_IDS} ids.`);
+      const definition = fileFlag(flags, deps, false);
+      const res = await client.post(path(id, "/preview"), {
+        ...ids ? { ids } : {},
+        ...definition !== void 0 ? { definition } : {}
+      });
+      const previewFailed = () => new CliError(
+        `The preview has ${res.data.errors.length} error${res.data.errors.length === 1 ? "" : "s"}.`
+      );
+      if (json) {
+        printJson(io, res);
+        if (res.data.errors.length > 0) throw previewFailed();
+        return;
+      }
+      printIssues(io, res.data.errors);
+      for (const w of res.data.warnings) io.stderr(`Warning: ${w.message} (${w.code})`);
+      io.stdout(JSON.stringify(res.data.documents, null, 2));
+      if (res.data.errors.length > 0) throw previewFailed();
+      return;
+    }
+    if (action === "rebuild") {
+      const id = requireIndexId(args);
+      if (!await deps.confirm(
+        `Rebuild ${id}? It renders every row again into a new index, then swaps.`
+      )) {
+        throw new CliError("Cancelled. Nothing changed.");
+      }
+      const res = await client.post(path(id, "/rebuild"), {});
+      if (json) return printJson(io, res);
+      io.stdout(
+        `Rebuild requested for ${id}. Searches keep using the current index until the swap.`
+      );
+      return;
+    }
+    if (action === "pause" || action === "resume" || action === "check") {
+      const id = requireIndexId(args);
+      const res = await client.post(path(id, `/${action}`), {});
+      if (json) return printJson(io, res);
+      io.stdout(
+        action === "pause" ? `Paused ${id}. Changes wait on the source until you resume.` : action === "resume" ? `Resumed ${id}.` : `Check started for ${id}.`
+      );
+      return;
+    }
+    if (action === "remove") {
+      const id = requireIndexId(args);
+      const drop = flags["--drop-index"] === true;
+      const prompt = drop ? `Remove ${id} and delete its engine index? Searches against it stop working.` : `Remove ${id}? Sync stops; the engine index stays and becomes writable.`;
+      if (!await deps.confirm(prompt)) throw new CliError("Cancelled. Nothing changed.");
+      const res = await client.delete(path(id, drop ? "?dropIndex=1" : ""));
+      if (json) return printJson(io, res);
+      io.stdout(
+        res.data.indexDropped ? `Removed ${id} and its engine index.` : drop && res.data.claimed === true ? `Removed ${id}. Deleting its engine index started and did not finish: run this command again to finish.` : drop ? `Removed ${id}. Its engine index is not deleted yet: run this command again to finish, or run it without --drop-index to keep the engine index.` : `Removed ${id}. Its engine index stays.`
+      );
+      return;
+    }
+    io.stdout(INDEX_USAGE);
+    throw new CliError("Unknown sync index command");
+  } catch (err) {
+    const issues = issuesOf(err);
+    if (issues.length > 0) printIssues(io, issues);
+    indexApiError(err, SYNC_INDEX_ID_RE.test(args[1] ?? "") ? args[1] : void 0);
+  }
+}
+async function runSyncStatus(flags, deps) {
+  const { io, client } = deps;
+  try {
+    const sources = await client.get("/v1/sync/sources");
+    const indexes = await client.get("/v1/sync/indexes");
+    if (flags["--json"] === true)
+      return printJson(io, { sources: sources.data, indexes: indexes.data });
+    if (sources.data.length === 0) {
+      io.stdout("No sources yet. Start with: headband sync source add <name> --db-url <url>");
+      return;
+    }
+    printTable(
+      io,
+      sources.data.map((s) => ({ source: s.id, name: s.name, host: s.host, state: s.state })),
+      ["source", "name", "host", "state"]
+    );
+    if (indexes.data.length > 0) {
+      io.stdout("");
+      printTable(
+        io,
+        indexes.data.map((i) => ({
+          index: i.id,
+          name: i.name,
+          source: i.sourceId,
+          state: i.state,
+          lag: lag(i),
+          documents: i.documents ?? ""
+        })),
+        ["index", "name", "source", "state", "lag", "documents"]
+      );
+    }
+    const attention = [];
+    for (const s of sources.data) {
+      if (s.state === "awaiting_setup")
+        attention.push(`${s.id} waits for setup: headband sync source setup ${s.id}`);
+      else if (ATTENTION_SOURCE.has(s.state))
+        attention.push(
+          `${s.id} ${s.state}${s.error ? `: ${s.error}` : ""}. Test it: headband sync source test ${s.id}`
+        );
+    }
+    for (const i of indexes.data) {
+      if (i.state === "awaiting_setup")
+        attention.push(
+          `${i.id} waits for its tables to be published: headband sync source setup ${i.sourceId}`
+        );
+      else if (i.state === "needs_rebuild")
+        attention.push(`${i.id} needs a rebuild: headband sync index rebuild ${i.id}`);
+      else if (ATTENTION_INDEX.has(i.state))
+        attention.push(
+          `${i.id} ${i.state}${i.error ? `: ${i.errorCode ?? "error"}: ${i.error}` : ""}. Details: headband sync index show ${i.id}`
+        );
+    }
+    io.stdout("");
+    if (attention.length === 0) io.stdout("Everything is running.");
+    else {
+      io.stdout("Needs attention:");
+      for (const line of attention) io.stdout(`  ${line}`);
+    }
+  } catch (err) {
+    friendlySyncError(err);
+  }
+}
+
+// src/index.ts
+async function askWithPrompts(message) {
+  let aborted = false;
+  const answer = await (0, import_prompts2.default)(
+    { type: "confirm", name: "confirmed", message, initial: false },
+    {
+      onCancel: () => {
+        aborted = true;
+        return false;
+      }
+    }
+  );
+  return aborted ? void 0 : answer.confirmed === true;
+}
+var ENGINES2 = /* @__PURE__ */ new Set(["meilisearch", "typesense", "elasticsearch", "visor"]);
+var KEY_TYPES = /* @__PURE__ */ new Set(["admin", "search"]);
+var EXPORT_FORMATS = /* @__PURE__ */ new Set(["jsonl", "json"]);
+var VALUE_FLAGS = /* @__PURE__ */ new Set([
+  "--url",
+  "--token",
+  "--profile",
+  "--engine",
+  "--primary-key",
+  "--file",
+  "--index",
+  "--limit",
+  "--filter",
+  "--type",
+  "--project",
+  "--dir",
+  "--slug",
+  "--table",
+  "--scaffold",
+  "--budget-ms",
+  "--batch-size",
+  "--reconcile-every",
+  "--name",
+  "--lane",
+  "--memory",
+  "--size",
+  "--region",
+  "--idle-timeout",
+  "--client",
+  "--instance",
+  "--db-url",
+  "--owner-url",
+  "--tls-mode",
+  "--ca-file",
+  "--kind",
+  "--batadb-project",
+  "--batadb-branch",
+  "--batadb-compute",
+  "--provider",
+  "-f",
+  "--source",
+  "--ids",
+  "--version",
+  "--out",
+  "--format",
+  "--batch",
+  "--permissions",
+  "--expires"
+]);
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
+  "--json",
+  "--yes",
+  "-y",
+  "--help",
+  "-h",
+  "--allow-destructive",
+  "--write",
+  "--force",
+  "--fix",
+  "--loop",
+  "--accept-broad-role",
+  "--rebuild",
+  "--drop-index",
+  "--none",
+  "--no-revoke"
+]);
+var DEFAULT_MIGRATIONS_DIR = "headband/migrations";
+function parseArgv(argv) {
+  const flags = {};
+  const positional = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("-")) {
+      positional.push(arg);
+      continue;
+    }
+    const equalsIndex = arg.indexOf("=");
+    const flagName = equalsIndex === -1 ? arg : arg.slice(0, equalsIndex);
+    const inlineValue = equalsIndex === -1 ? void 0 : arg.slice(equalsIndex + 1);
+    if (VALUE_FLAGS.has(flagName)) {
+      const value = inlineValue ?? argv[index + 1];
+      if (!value || value.startsWith("-")) {
+        throw new UsageError(`Missing value for ${flagName}`);
+      }
+      flags[flagName === "-f" ? "--file" : flagName] = value;
+      if (inlineValue === void 0) index += 1;
+      continue;
+    }
+    if (BOOLEAN_FLAGS.has(flagName)) {
+      flags[flagName === "-y" ? "--yes" : flagName === "-h" ? "--help" : flagName] = true;
+      continue;
+    }
+    throw new UsageError(
+      /^--?[a-z][a-z0-9-]{0,40}$/.test(flagName) ? `Unknown option: ${flagName}` : "Unknown option."
+    );
+  }
+  return { flags, positional };
+}
+function stringFlag(flags, name) {
+  const value = flags[name];
+  return typeof value === "string" ? value : void 0;
+}
+function boolFlag(flags, name) {
+  return flags[name] === true;
+}
+function requiredFlag(flags, name) {
+  const value = stringFlag(flags, name);
+  if (!value) throw new UsageError(`Missing required option: ${name}`);
+  return value;
+}
+function requiredArg(value, what) {
+  if (!value) throw new UsageError(`Missing ${what}`);
+  return value;
+}
+function parseLimit(flags) {
+  const raw = stringFlag(flags, "--limit");
+  if (!raw) return void 0;
+  const limit = Number(raw);
+  if (!Number.isInteger(limit) || limit <= 0) {
+    throw new UsageError("--limit must be a positive integer");
+  }
+  return limit;
+}
+function validateEngine(engine) {
+  if (!ENGINES2.has(engine)) {
+    throw new UsageError("Engine must be one of: meilisearch, typesense, elasticsearch, visor");
+  }
+  return engine;
+}
+function validateKeyType(type) {
+  if (!KEY_TYPES.has(type)) {
+    throw new UsageError("Key type must be one of: admin, search");
+  }
+  return type;
+}
+function encode(value) {
+  return encodeURIComponent(value);
+}
+function chatterIO(io, flags) {
+  return boolFlag(flags, "--json") ? { stdout: io.stderr, stderr: io.stderr } : io;
+}
+function authFromFlags(flags) {
+  return resolveAuth({
+    token: stringFlag(flags, "--token"),
+    url: stringFlag(flags, "--url"),
+    profile: stringFlag(flags, "--profile")
   });
-  return answer.confirmed === true;
+}
+function clientFromFlags(flags) {
+  const auth = authFromFlags(flags);
+  return createApiClient(auth.url, { apiKey: auth.apiKey });
+}
+function stdinIsInteractive() {
+  return process.stdin.isTTY === true;
+}
+async function confirmOrSkip(message, flags, ask = askWithPrompts) {
+  if (boolFlag(flags, "--yes")) return true;
+  if (!stdinIsInteractive()) {
+    throw new UsageError(
+      `Confirmation required: ${message} stdin is not a terminal, so re-run with --yes to confirm.`,
+      "confirmation_required"
+    );
+  }
+  const answer = await ask(message);
+  if (answer === void 0) {
+    throw new CliError("Interrupted.", { exitCode: EXIT_CODES.interrupted, code: "interrupted" });
+  }
+  return answer;
+}
+function cancelled(io, flags) {
+  if (boolFlag(flags, "--json")) printJson(io, { cancelled: true });
+  else io.stdout("Cancelled.");
 }
 function printHelp(io) {
   io.stdout(`@headband/cli
@@ -2166,58 +3636,74 @@ Usage:
 
 Commands:
   init [--yes]
-  login [--url <url>]
-  logout [--url <url>] [--yes]
-  whoami [--url <url>] [--json]
+  login [--url <url>] [--profile <name>] [--json]
+  logout [--profile <name>] [--yes] [--no-revoke] [--json]
+  whoami [--json]
+  profiles list [--json]
+  profiles use <name>
   projects list [--json]
-  projects create <name> --engine <meilisearch|typesense|elasticsearch>
+  projects create <name> --engine <meilisearch|typesense|elasticsearch|visor> [--json]
+  projects delete <id> [--force] [--yes] [--json]
   keys list [--json]
-  keys create <name> --type <admin|search> [--project <id>] [--json]
-  keys revoke <id> [--yes]
+  keys create <name> --type <admin|search> [--project <id>] [--permissions <a,b>] [--expires <30d|ISO date>] [--json]
+  keys revoke <id> [--yes] [--json]
   indexes list [--json]
   indexes create <uid> [--primary-key <pk>] [--engine <engine>] [--instance <id>] [--json]
-  indexes delete <uid> [--yes]
+  indexes delete <uid> [--yes] [--json]
   indexes settings get <uid> [--json]
   indexes settings set <uid> --file <settings.json> [--json]
   indexes stats <uid> [--json]
   instances list [--json]
-  instances create <engine> [--name <name>] [--lane <lane>] [--memory <size>] [--region <region>] [--idle-timeout <s>]
+  instances create <engine> [--name <name>] [--lane <lane>] [--memory <size>] [--region <region>] [--idle-timeout <s>] [--json]
+  instances update <id> [--name <name>] [--lane <lane>] [--memory <size>] [--idle-timeout <s>] [--json]
   instances show|wake|park <id> [--json]
-  instances delete <id> [--yes]
-  instances connect <id> [--client <node|curl>]
-  docs push <file> --index <uid>
-  docs delete <docId> --index <uid>
+  instances wakes <id> [--limit <n>] [--json]
+  instances delete <id> [--yes] [--json]
+  instances connect <id> [--client <node|curl>] [--json]
+  docs push <file> --index <uid> [--json]
+  docs export --index <uid> [--out <file>] [--format <jsonl|json>] [--batch <n>]
+  docs delete <docId> --index <uid> [--json]
   search <index> <query> [--limit N] [--filter <expr>] [--json]
   tasks list [--json]
   tasks get <id> [--json]
-  schema diff [--url <url>]
-  schema generate [--slug <slug>] [--dir <dir>] [--url <url>]
-  schema apply [--allow-destructive] [--dir <dir>] [--yes] [--url <url>]
-  schema status [--dir <dir>] [--url <url>]
-  sync init [--table <name>] [--write]
-  sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>] [--url <url>]
-  sync worker --scaffold docker [--force]
-  sync reconcile [--fix] [--url <url>]
-  sync retry-dead-letters
+  schema diff [--allow-destructive] [--json]
+  schema generate [--slug <slug>] [--dir <dir>] [--allow-destructive] [--json]
+  schema apply [--allow-destructive] [--dir <dir>] [--yes] [--json]
+  schema status [--dir <dir>] [--json]
+  sync init [--table <name>] [--write] [--json]
+  sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>] [--json]
+  sync worker --scaffold docker [--force] [--json]
+  sync reconcile [--fix] [--json]
+  sync retry-dead-letters [--json]
+  sync source add|list|show|test|setup|setup-sql|set-ca|remove (see headband sync source --help)
+  sync index create|list|show|update|validate|preview|rebuild|pause|resume|check|remove (see headband sync index --help)
+  sync status [--json]
 
 Global options:
-  --url <url>    Select profile URL (default: stored single profile, else ${DEFAULT_URL})
-  --json         Print machine-readable JSON for supported commands
-  --yes          Skip confirmation prompts
-  --help         Show help`);
+  --token <key>      API key for this call. Wins over HEADBAND_API_KEY and stored logins.
+  --profile <name>   Stored login to use (else HEADBAND_PROFILE, else the current profile)
+  --url <url>        Headband URL (else HEADBAND_URL, else the profile's, else ${DEFAULT_URL})
+  --json             Print one JSON document on stdout; errors print one JSON object on stderr
+  --yes              Answer yes to confirmations (required when stdin is not a terminal)
+  --help             Show help
+  --version          Show the CLI version
+
+Exit codes: 0 ok, 1 error, 2 usage, 3 auth, 4 permission, 5 not found, 6 conflict,
+7 rate limited, 8 server or engine, 130 interrupted.`);
 }
 function printCommandHelp(command, io) {
   const help = {
-    login: "Usage: headband login [--url <url>]",
-    logout: "Usage: headband logout [--url <url>] [--yes]",
-    whoami: "Usage: headband whoami [--url <url>] [--json]",
-    projects: "Usage:\n  headband projects list [--json]\n  headband projects create <name> --engine <meilisearch|typesense|elasticsearch>",
-    keys: "Usage:\n  headband keys list [--json]\n  headband keys create <name> --type <admin|search> [--project <id>] [--json]\n  headband keys revoke <id> [--yes]",
+    login: "Usage: headband login [--url <url>] [--profile <name>] [--json]",
+    logout: "Usage: headband logout [--profile <name>] [--yes] [--no-revoke] [--json]",
+    whoami: "Usage: headband whoami [--json]",
+    profiles: "Usage:\n  headband profiles list [--json]\n  headband profiles use <name>",
+    projects: "Usage:\n  headband projects list [--json]\n  headband projects create <name> --engine <meilisearch|typesense|elasticsearch|visor> [--json]\n  headband projects delete <id> [--force] [--yes] [--json]\n\n  delete refuses a project that still has indexes; --force deletes its indexes with it.",
+    keys: "Usage:\n  headband keys list [--json]\n  headband keys create <name> --type <admin|search> [--project <id>] [--permissions <a,b>] [--expires <30d|ISO date>] [--json]\n  headband keys revoke <id> [--yes] [--json]",
     indexes: [
       "Usage:",
       "  headband indexes list [--json]",
       "  headband indexes create <uid> [--primary-key <pk>] [--engine <engine>] [--instance <id>] [--json]",
-      "  headband indexes delete <uid> [--yes]",
+      "  headband indexes delete <uid> [--yes] [--json]",
       "  headband indexes settings get <uid> [--json]",
       "  headband indexes settings set <uid> --file <settings.json> [--json]",
       "  headband indexes stats <uid> [--json]",
@@ -2227,55 +3713,121 @@ function printCommandHelp(command, io) {
       "                   The index takes that engine's type; --engine, if given, must match it."
     ].join("\n"),
     instances: INSTANCES_USAGE,
-    docs: "Usage:\n  headband docs push <file> --index <uid>\n  headband docs delete <docId> --index <uid>",
+    docs: "Usage:\n  headband docs push <file> --index <uid> [--json]\n  headband docs export --index <uid> [--out <file>] [--format <jsonl|json>] [--batch <n>] [--json]\n  headband docs delete <docId> --index <uid> [--json]",
     search: "Usage: headband search <index> <query> [--limit N] [--filter <expr>] [--json]",
     tasks: "Usage:\n  headband tasks list [--json]\n  headband tasks get <id> [--json]",
-    schema: "Usage:\n  headband schema diff\n  headband schema generate [--slug <slug>] [--dir <dir>]\n  headband schema apply [--allow-destructive] [--dir <dir>] [--yes]\n  headband schema status [--dir <dir>]",
-    sync: "Usage:\n  headband sync init [--table <name>] [--write]\n  headband sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>]\n  headband sync worker --scaffold docker [--force]\n  headband sync reconcile [--fix]\n  headband sync retry-dead-letters"
+    schema: "Usage:\n  headband schema diff [--allow-destructive] [--json]\n  headband schema generate [--slug <slug>] [--dir <dir>] [--allow-destructive] [--json]\n  headband schema apply [--allow-destructive] [--dir <dir>] [--yes] [--json]\n  headband schema status [--dir <dir>] [--json]",
+    sync: "Usage:\n  headband sync init [--table <name>] [--write] [--json]\n  headband sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>] [--json]\n  headband sync worker --scaffold docker [--force] [--json]\n  headband sync reconcile [--fix] [--json]\n  headband sync retry-dead-letters [--json]\n  headband sync source add|list|show|test|setup|setup-sql|set-ca|remove (see headband sync source --help)\n  headband sync index create|list|show|update|validate|preview|rebuild|pause|resume|check|remove (see headband sync index --help)\n  headband sync status [--json]"
   };
   io.stdout(help[command] || "");
 }
 async function runLogin(flags, io) {
-  await login(stringFlag(flags, "--url") || DEFAULT_URL, io);
+  const url = stringFlag(flags, "--url") || process.env.HEADBAND_URL || DEFAULT_URL;
+  const result = await login(url, chatterIO(io, flags), {
+    profileName: stringFlag(flags, "--profile")
+  });
+  if (boolFlag(flags, "--json")) printJson(io, result);
 }
-async function runLogout(flags, io) {
-  const { url: selectedUrl, profile } = getProfile(stringFlag(flags, "--url"));
-  io.stdout(
-    `Removing local credentials for ${selectedUrl}. Revoke this key with headband keys revoke ${profile.keyId} or in the dashboard if it should stop working.`
-  );
-  if (!boolFlag(flags, "--yes")) {
-    const shouldRevoke = await confirmOrSkip(
-      "Revoke this CLI key server-side before logging out?",
-      flags
-    );
-    if (shouldRevoke) {
-      const client = createApiClient(selectedUrl, profile);
-      await client.delete(`/v1/keys/${encode(profile.keyId)}`);
-      io.stdout("Revoked CLI key.");
+async function runLogout(flags, io, confirm) {
+  const json = boolFlag(flags, "--json");
+  const chatter = chatterIO(io, flags);
+  const selected = selectProfile({
+    url: stringFlag(flags, "--url"),
+    profile: stringFlag(flags, "--profile")
+  });
+  if (!selected) {
+    throw new AuthError("No stored login to log out of. Run: headband profiles list");
+  }
+  const { name, profile } = selected;
+  let revoked = false;
+  const noRevoke = boolFlag(flags, "--no-revoke");
+  if (!noRevoke) {
+    if (!boolFlag(flags, "--yes")) {
+      chatter.stdout(
+        `Removing local credentials for profile ${name} (${profile.url}). Pass --no-revoke to keep the key working.`
+      );
+    }
+    if (await confirm("Revoke this CLI key server-side before logging out?")) {
+      const client = createApiClient(profile.url, profile);
+      try {
+        await client.delete(`/v1/keys/${encode(profile.keyId)}`);
+        revoked = true;
+        chatter.stdout("Revoked CLI key.");
+      } catch (error) {
+        if (!(error instanceof ApiError && (error.status === 401 || error.status === 404))) {
+          throw error;
+        }
+        chatter.stderr("The key was already revoked or no longer exists.");
+      }
     }
   }
-  removeProfile(selectedUrl);
-  io.stdout(`Logged out of ${selectedUrl}.`);
+  removeProfile(name);
+  if (json) printJson(io, { profile: name, url: profile.url, revoked, loggedOut: true });
+  else io.stdout(`Logged out of ${profile.url} (profile ${name}).`);
 }
 async function runWhoami(flags, io) {
-  const { url, profile } = getProfile(stringFlag(flags, "--url"));
-  const client = createApiClient(url, profile);
+  const auth = authFromFlags(flags);
+  const client = createApiClient(auth.url, auth);
   await client.get("/v1/indexes");
   const info = {
-    url,
-    orgName: profile.orgName,
-    orgId: profile.orgId,
-    keyPrefix: profile.keyPrefix,
-    keyId: profile.keyId,
+    url: auth.url,
+    source: auth.source,
+    profile: auth.profileName ?? null,
+    orgName: auth.profile?.orgName ?? null,
+    orgId: auth.profile?.orgId ?? null,
+    keyPrefix: auth.profile?.keyPrefix ?? auth.apiKey.slice(0, 12),
+    keyId: auth.profile?.keyId ?? null,
     valid: true
   };
   if (boolFlag(flags, "--json")) {
     printJson(io, info);
     return;
   }
-  printTable(io, [info], ["url", "orgName", "keyPrefix", "keyId", "valid"]);
+  printTable(
+    io,
+    [info],
+    auth.profile ? ["url", "profile", "orgName", "keyPrefix", "keyId", "valid"] : ["url", "source", "keyPrefix", "valid"]
+  );
+}
+async function runProfiles(args, flags, io) {
+  const action = args[0];
+  if (action === "list") {
+    const credentials = readCredentials();
+    const profiles = Object.entries(credentials.profiles).map(([name, p]) => ({
+      name,
+      current: credentials.current === name,
+      url: p.url,
+      orgName: p.orgName,
+      orgId: p.orgId,
+      keyPrefix: p.keyPrefix,
+      keyId: p.keyId
+    }));
+    if (boolFlag(flags, "--json")) {
+      printJson(io, { data: { current: credentials.current ?? null, profiles } });
+      return;
+    }
+    if (profiles.length === 0) {
+      io.stdout("No stored logins. Run: headband login");
+      return;
+    }
+    printTable(
+      io,
+      profiles.map((p) => ({ ...p, current: p.current ? "*" : "" })),
+      ["current", "name", "url", "orgName", "keyPrefix"]
+    );
+    return;
+  }
+  if (action === "use") {
+    const name = requiredArg(args[1], "profile name");
+    const profile = setCurrentProfile(name);
+    if (boolFlag(flags, "--json")) printJson(io, { current: name, url: profile.url });
+    else io.stdout(`Now using profile ${name} (${profile.url}).`);
+    return;
+  }
+  printCommandHelp("profiles", io);
+  throw new UsageError("Unknown profiles command");
 }
-async function runProjects(args, flags, io) {
+async function runProjects(args, flags, io, confirm) {
   const action = args[0];
   const client = clientFromFlags(flags);
   if (action === "list") {
@@ -2287,8 +3839,7 @@ async function runProjects(args, flags, io) {
     return;
   }
   if (action === "create") {
-    const name = args[1];
-    if (!name) throw new CliError("Missing project name");
+    const name = requiredArg(args[1], "project name");
     const engine = validateEngine(requiredFlag(flags, "--engine"));
     const response = await client.post(
       "/v1/projects",
@@ -2301,10 +3852,58 @@ async function runProjects(args, flags, io) {
     else printTable(io, [response.data.project], ["id", "name", "engine", "prefix", "createdAt"]);
     return;
   }
+  if (action === "delete") {
+    const id = requiredArg(args[1], "project id");
+    const force = boolFlag(flags, "--force");
+    const question = force ? `Delete project ${id} and every index in it?` : `Delete project ${id}?`;
+    if (!await confirm(question)) return cancelled(io, flags);
+    const response = await client.delete(`/v1/projects/${encode(id)}${force ? "?force=true" : ""}`);
+    if (boolFlag(flags, "--json")) printJson(io, response);
+    else io.stdout(`Deleted project ${id}.`);
+    return;
+  }
   printCommandHelp("projects", io);
-  throw new CliError("Unknown projects command");
+  throw new UsageError("Unknown projects command");
+}
+var DURATION = /^(\d+)\s*(h|d|w|y)$/i;
+var DURATION_MS = {
+  h: 60 * 60 * 1e3,
+  d: 24 * 60 * 60 * 1e3,
+  w: 7 * 24 * 60 * 60 * 1e3,
+  y: 365 * 24 * 60 * 60 * 1e3
+};
+function parseExpires(raw, now = Date.now()) {
+  const duration = DURATION.exec(raw.trim());
+  if (duration) {
+    const amount = Number(duration[1]);
+    if (amount <= 0) throw new UsageError("--expires must be in the future");
+    return new Date(now + amount * DURATION_MS[duration[2].toLowerCase()]).toISOString();
+  }
+  if (/^\d{4}-\d{2}-\d{2}/.test(raw.trim())) {
+    const at = Date.parse(raw.trim());
+    if (!Number.isNaN(at)) {
+      if (at <= now) throw new UsageError("--expires must be in the future");
+      return new Date(at).toISOString();
+    }
+  }
+  throw new UsageError(
+    "--expires must be a duration (12h, 30d, 2w, 1y) or an ISO date (2027-01-31)"
+  );
 }
-async function runKeys(args, flags, io) {
+function parsePermissions(raw) {
+  const permissions = [
+    ...new Set(
+      raw.split(",").map((p) => p.trim()).filter(Boolean)
+    )
+  ];
+  if (permissions.length === 0) {
+    throw new UsageError(
+      "--permissions needs at least one permission, such as search,documents.read"
+    );
+  }
+  return permissions;
+}
+async function runKeys(args, flags, io, confirm) {
   const action = args[0];
   const client = clientFromFlags(flags);
   if (action === "list") {
@@ -2317,19 +3916,23 @@ async function runKeys(args, flags, io) {
         "type",
         "keyPrefix",
         "projectId",
-        "lastUsedAt"
+        "lastUsedAt",
+        "expiresAt"
       ]);
     return;
   }
   if (action === "create") {
-    const name = args[1];
-    if (!name) throw new CliError("Missing key name");
+    const name = requiredArg(args[1], "key name");
     const body = {
       name,
       type: validateKeyType(requiredFlag(flags, "--type"))
     };
     const projectId = stringFlag(flags, "--project");
     if (projectId) body.projectId = projectId;
+    const permissions = stringFlag(flags, "--permissions");
+    if (permissions) body.permissions = parsePermissions(permissions);
+    const expires = stringFlag(flags, "--expires");
+    if (expires) body.expiresAt = parseExpires(expires);
     const response = await client.post("/v1/keys", body);
     if (boolFlag(flags, "--json")) {
       printJson(io, response);
@@ -2337,25 +3940,21 @@ async function runKeys(args, flags, io) {
     }
     io.stdout(import_picocolors3.default.yellow("Store this API key now. It will not be shown again."));
     io.stdout(response.data.apiKey);
-    printTable(io, [response.data.key], ["id", "name", "type", "keyPrefix"]);
+    printTable(io, [response.data.key], ["id", "name", "type", "keyPrefix", "expiresAt"]);
     return;
   }
   if (action === "revoke") {
-    const id = args[1];
-    if (!id) throw new CliError("Missing key id");
-    if (!await confirmOrSkip(`Revoke key ${id}?`, flags)) {
-      io.stdout("Cancelled.");
-      return;
-    }
+    const id = requiredArg(args[1], "key id");
+    if (!await confirm(`Revoke key ${id}?`)) return cancelled(io, flags);
     const response = await client.delete(`/v1/keys/${encode(id)}`);
     if (boolFlag(flags, "--json")) printJson(io, response);
     else io.stdout(`Revoked key ${id}.`);
     return;
   }
   printCommandHelp("keys", io);
-  throw new CliError("Unknown keys command");
+  throw new UsageError("Unknown keys command");
 }
-async function runIndexes(args, flags, io) {
+async function runIndexes(args, flags, io, confirm) {
   const action = args[0];
   const client = clientFromFlags(flags);
   if (action === "list") {
@@ -2375,8 +3974,7 @@ async function runIndexes(args, flags, io) {
     return;
   }
   if (action === "create") {
-    const uid = args[1];
-    if (!uid) throw new CliError("Missing index uid");
+    const uid = requiredArg(args[1], "index uid");
     const body = { uid };
     const primaryKey = stringFlag(flags, "--primary-key");
     const engine = stringFlag(flags, "--engine");
@@ -2402,12 +4000,8 @@ async function runIndexes(args, flags, io) {
     return;
   }
   if (action === "delete") {
-    const uid = args[1];
-    if (!uid) throw new CliError("Missing index uid");
-    if (!await confirmOrSkip(`Delete index ${uid}?`, flags)) {
-      io.stdout("Cancelled.");
-      return;
-    }
+    const uid = requiredArg(args[1], "index uid");
+    if (!await confirm(`Delete index ${uid}?`)) return cancelled(io, flags);
     const response = await client.delete(`/v1/indexes/${encode(uid)}`);
     if (boolFlag(flags, "--json")) printJson(io, response);
     else io.stdout(`Deleted index ${uid}.`);
@@ -2415,8 +4009,7 @@ async function runIndexes(args, flags, io) {
   }
   if (action === "settings") {
     const settingsAction = args[1];
-    const uid = args[2];
-    if (!uid) throw new CliError("Missing index uid");
+    const uid = requiredArg(args[2], "index uid");
     if (settingsAction === "get") {
       const response = await client.get(`/v1/indexes/${encode(uid)}/settings`);
       printJson(io, response);
@@ -2424,51 +4017,95 @@ async function runIndexes(args, flags, io) {
     }
     if (settingsAction === "set") {
       const file = requiredFlag(flags, "--file");
-      const settings = JSON.parse((0, import_fs8.readFileSync)(file, "utf-8"));
+      const settings = JSON.parse((0, import_fs11.readFileSync)(file, "utf-8"));
       const response = await client.patch(`/v1/indexes/${encode(uid)}/settings`, settings);
       printJson(io, response);
       return;
     }
   }
   if (action === "stats") {
-    const uid = args[1];
-    if (!uid) throw new CliError("Missing index uid");
+    const uid = requiredArg(args[1], "index uid");
     const response = await client.get(`/v1/indexes/${encode(uid)}/stats`);
     printJson(io, response);
     return;
   }
   printCommandHelp("indexes", io);
-  throw new CliError("Unknown indexes command");
+  throw new UsageError("Unknown indexes command");
 }
-async function runDocs(args, flags, io) {
-  const action = args[0];
+function exportFormat(flags, out) {
+  const raw = stringFlag(flags, "--format") ?? (out?.toLowerCase().endsWith(".json") ? "json" : "jsonl");
+  if (!EXPORT_FORMATS.has(raw)) throw new UsageError("--format must be jsonl or json");
+  return raw;
+}
+async function runDocsExport(flags, context) {
+  const { io } = context;
+  const index = requiredFlag(flags, "--index");
+  const out = stringFlag(flags, "--out");
+  const format = exportFormat(flags, out);
   const client = clientFromFlags(flags);
+  const batchSize = parseIntFlag(flags, "--batch") ?? await defaultExportBatchSize(client, index);
+  if (!out) {
+    const writeLine = context.writeLine ?? ((line) => io.stdout(line));
+    await exportDocuments(client, { index, format, batchSize, write: writeLine });
+    return;
+  }
+  const partial = `${out}.partial`;
+  const fd = (0, import_fs10.openSync)(partial, "w", 384);
+  let exported;
+  try {
+    exported = await exportDocuments(client, {
+      index,
+      format,
+      batchSize,
+      write: (line) => {
+        (0, import_fs10.writeSync)(fd, `${line}
+`);
+      },
+      onPage: (count, total) => io.stderr(`Exported ${count}${total === null ? "" : `/${total}`} documents`)
+    });
+    (0, import_fs10.closeSync)(fd);
+  } catch (error) {
+    (0, import_fs10.closeSync)(fd);
+    (0, import_fs10.rmSync)(partial, { force: true });
+    throw error;
+  }
+  (0, import_fs10.renameSync)(partial, out);
+  if (boolFlag(flags, "--json")) printJson(io, { index, out, format, exported });
+  else io.stdout(`Exported ${exported} documents to ${out}.`);
+}
+async function runDocs(args, flags, context) {
+  const { io } = context;
+  const action = args[0];
+  if (action === "export") {
+    await runDocsExport(flags, context);
+    return;
+  }
   if (action === "push") {
-    const file = args[1];
-    if (!file) throw new CliError("Missing documents file");
+    const file = requiredArg(args[1], "documents file");
     const index = requiredFlag(flags, "--index");
+    const client = clientFromFlags(flags);
     const documents = parseDocumentsFile(file);
-    const count = await pushDocuments(client, index, documents, io);
-    io.stdout(`Pushed ${count} documents.`);
+    const count = await pushDocuments(client, index, documents, chatterIO(io, flags));
+    if (boolFlag(flags, "--json")) printJson(io, { index, pushed: count });
+    else io.stdout(`Pushed ${count} documents.`);
     return;
   }
   if (action === "delete") {
-    const docId = args[1];
-    if (!docId) throw new CliError("Missing document id");
+    const docId = requiredArg(args[1], "document id");
     const index = requiredFlag(flags, "--index");
+    const client = clientFromFlags(flags);
     const response = await client.delete(`/v1/documents/${encode(docId)}?index=${encode(index)}`);
     if (boolFlag(flags, "--json")) printJson(io, response);
     else io.stdout(`Deleted document ${docId}.`);
     return;
   }
   printCommandHelp("docs", io);
-  throw new CliError("Unknown docs command");
+  throw new UsageError("Unknown docs command");
 }
 async function runSearch(args, flags, io) {
-  const index = args[0];
+  const index = requiredArg(args[0], "search index");
   const query = args.slice(1).join(" ");
-  if (!index) throw new CliError("Missing search index");
-  if (!query) throw new CliError("Missing search query");
+  if (!query) throw new UsageError("Missing search query");
   const client = clientFromFlags(flags);
   const body = {
     index,
@@ -2493,40 +4130,56 @@ async function runTasks(args, flags, io) {
   if (action === "list") {
     const response = await client.get("/v1/tasks");
     if (boolFlag(flags, "--json")) printJson(io, response);
-    else printJson(io, response);
+    else
+      printTable(io, response.results ?? [], [
+        "uid",
+        "indexUid",
+        "type",
+        "status",
+        "enqueuedAt",
+        "finishedAt"
+      ]);
     return;
   }
   if (action === "get") {
-    const id = args[1];
-    if (!id) throw new CliError("Missing task id");
+    const id = requiredArg(args[1], "task id");
     const response = await client.get(`/v1/tasks/${encode(id)}`);
     printJson(io, response);
     return;
   }
   printCommandHelp("tasks", io);
-  throw new CliError("Unknown tasks command");
+  throw new UsageError("Unknown tasks command");
 }
-async function runSchema(args, flags, io) {
+async function runSchema(args, flags, io, confirm) {
   const action = args[0];
+  if (!["diff", "generate", "apply", "status"].includes(action)) {
+    printCommandHelp("schema", io);
+    throw new UsageError("Unknown schema command");
+  }
+  const json = boolFlag(flags, "--json");
+  const chatter = chatterIO(io, flags);
   const dir = stringFlag(flags, "--dir") || DEFAULT_MIGRATIONS_DIR;
-  const { url, profile } = getProfile(stringFlag(flags, "--url"));
-  const client = new HeadbandClient({ url, adminKey: profile.apiKey });
+  const auth = authFromFlags(flags);
+  const client = new HeadbandClient({ url: auth.url, adminKey: auth.apiKey });
   const { config, adapter } = await loadHeadbandConfig(process.cwd());
   const allowDestructive = boolFlag(flags, "--allow-destructive");
   if (action === "diff") {
-    const code = await runSchemaDiff({ config, client, io, allowDestructive });
-    if (code !== 0) process.exitCode = code;
+    const ops = await planSchemaDiff({ config, client, allowDestructive });
+    if (json) printJson(io, { inSync: ops.length === 0, ops: opRows(ops) });
+    else printOpsTable(io, ops);
+    if (ops.length > 0) process.exitCode = 1;
     return;
   }
   if (action === "generate") {
-    await runSchemaGenerate({
+    const path2 = await runSchemaGenerate({
       config,
       client,
       dir,
       slug: stringFlag(flags, "--slug"),
-      io,
+      io: chatter,
       allowDestructive
     });
+    if (json) printJson(io, { path: path2 ?? null });
     return;
   }
   if (action === "apply") {
@@ -2535,52 +4188,90 @@ async function runSchema(args, flags, io) {
         "headband.config.ts must export an `adapter` (e.g. drizzleAdapter(...)) for schema apply \u2014 it's needed to backfill documents during a reindex."
       );
     }
-    if (!await confirmOrSkip("Apply pending schema migrations?", flags)) {
-      io.stdout("Cancelled.");
-      return;
+    if (!await confirm("Apply pending schema migrations?")) {
+      return cancelled(io, flags);
     }
-    const result = await runSchemaApply({ config, adapter, client, dir, allowDestructive, io });
-    io.stdout(
-      `Applied ${result.appliedOps} op(s) across ${result.appliedFiles} migration file(s).`
-    );
-    return;
-  }
-  if (action === "status") {
-    await runSchemaStatus({ config, client, dir, io });
+    const result = await runSchemaApply({
+      config,
+      adapter,
+      client,
+      dir,
+      allowDestructive,
+      io: chatter
+    });
+    if (json) printJson(io, result);
+    else
+      io.stdout(
+        `Applied ${result.appliedOps} op(s) across ${result.appliedFiles} migration file(s).`
+      );
     return;
   }
-  printCommandHelp("schema", io);
-  throw new CliError("Unknown schema command");
+  const status = await runSchemaStatus({ config, client, dir, io: chatter });
+  if (json) printJson(io, status);
 }
 function parseIntFlag(flags, name) {
   const raw = stringFlag(flags, name);
   if (!raw) return void 0;
   const value = Number(raw);
   if (!Number.isInteger(value) || value <= 0) {
-    throw new CliError(`${name} must be a positive integer`);
+    throw new UsageError(`${name} must be a positive integer`);
   }
   return value;
 }
-async function runSync(args, flags, io) {
+async function runSync(args, flags, io, confirm) {
   const action = args[0];
-  if (action === "init") {
-    runSyncInit({
+  const json = boolFlag(flags, "--json");
+  const chatter = chatterIO(io, flags);
+  if (action === "source") {
+    await runSyncSource(args.slice(1), flags, {
+      io,
+      client: clientFromFlags(flags),
+      confirm
+    });
+    return;
+  }
+  if (action === "index") {
+    await runSyncIndex(args.slice(1), flags, {
+      io,
+      client: clientFromFlags(flags),
+      confirm
+    });
+    return;
+  }
+  if (action === "status") {
+    await runSyncStatus(flags, {
       io,
+      client: clientFromFlags(flags),
+      confirm
+    });
+    return;
+  }
+  if (action === "init") {
+    const cwd = process.cwd();
+    const write = boolFlag(flags, "--write");
+    const ddl = runSyncInit({
+      io: json ? { stdout: () => void 0, stderr: io.stderr } : io,
       table: stringFlag(flags, "--table"),
-      write: boolFlag(flags, "--write"),
-      cwd: process.cwd()
+      write,
+      cwd
     });
+    if (json) printJson(io, { ddl, path: write ? (0, import_path9.join)(cwd, OUTBOX_SQL_RELATIVE_PATH) : null });
     return;
   }
   if (action === "worker") {
     const scaffold = stringFlag(flags, "--scaffold");
     if (scaffold) {
-      if (scaffold !== "docker") throw new CliError(`Unknown scaffold target: ${scaffold}`);
-      runSyncScaffoldDocker({ cwd: process.cwd(), io, force: boolFlag(flags, "--force") });
+      if (scaffold !== "docker") throw new UsageError(`Unknown scaffold target: ${scaffold}`);
+      const path2 = runSyncScaffoldDocker({
+        cwd: process.cwd(),
+        io: chatter,
+        force: boolFlag(flags, "--force")
+      });
+      if (json) printJson(io, { path: path2 });
       return;
     }
-    const { url, profile } = getProfile(stringFlag(flags, "--url"));
-    const client = new HeadbandClient({ url, adminKey: profile.apiKey });
+    const auth = authFromFlags(flags);
+    const client = new HeadbandClient({ url: auth.url, adminKey: auth.apiKey });
     const { config, adapter } = await loadHeadbandConfig(process.cwd());
     if (!adapter) {
       throw new CliError(
@@ -2591,12 +4282,12 @@ async function runSync(args, flags, io) {
       table: config.sync?.outboxTable
     });
     try {
-      await runSyncWorkerCmd({
+      const report = await runSyncWorkerCmd({
         config,
         adapter,
         client,
         outbox,
-        io,
+        io: chatter,
         // Only override runSyncWorkerCmd's own default (loop unless
         // --budget-ms is set) when the caller explicitly passed --loop —
         // omitting it here keeps the bare `sync worker` default unchanged.
@@ -2610,34 +4301,36 @@ async function runSync(args, flags, io) {
             config,
             adapter,
             client,
-            io,
+            io: chatter,
             getStats: (uid) => apiClient.get(`/v1/indexes/${encode(uid)}/stats`)
           });
         }
       });
+      if (json) printJson(io, report);
     } finally {
       await close();
     }
     return;
   }
   if (action === "reconcile") {
-    const { url, profile } = getProfile(stringFlag(flags, "--url"));
-    const client = new HeadbandClient({ url, adminKey: profile.apiKey });
-    const apiClient = clientFromFlags(flags);
+    const auth = authFromFlags(flags);
+    const client = new HeadbandClient({ url: auth.url, adminKey: auth.apiKey });
+    const apiClient = createApiClient(auth.url, auth);
     const { config, adapter } = await loadHeadbandConfig(process.cwd());
     if (!adapter) {
       throw new CliError(
         "headband.config.ts must export an `adapter` (e.g. drizzleAdapter(...)) for sync reconcile."
       );
     }
-    await runSyncReconcile({
+    const rows = await runSyncReconcile({
       config,
       adapter,
       client,
-      io,
+      io: chatter,
       fix: boolFlag(flags, "--fix"),
       getStats: (uid) => apiClient.get(`/v1/indexes/${encode(uid)}/stats`)
     });
+    if (json) printJson(io, { indexes: rows });
     return;
   }
   if (action === "retry-dead-letters") {
@@ -2646,48 +4339,66 @@ async function runSync(args, flags, io) {
       table: config.sync?.outboxTable
     });
     try {
-      await runSyncRetryDeadLetters({ outbox, io });
+      const requeued = await runSyncRetryDeadLetters({ outbox, io: chatter });
+      if (json) printJson(io, { requeued });
     } finally {
       await close();
     }
     return;
   }
   printCommandHelp("sync", io);
-  throw new CliError("Unknown sync command");
+  throw new UsageError("Unknown sync command");
 }
+var CLI_VERSION = true ? "0.3.0" : "dev";
 async function run(argv, context = { io: defaultIO }) {
+  if (argv.length === 1 && (argv[0] === "--version" || argv[0] === "-v" || argv[0] === "version")) {
+    context.io.stdout(CLI_VERSION);
+    return;
+  }
   const { flags, positional } = parseArgv(argv);
   const command = positional[0];
   const args = positional.slice(1);
   if (boolFlag(flags, "--help") || command === "help") {
-    if (command && command !== "help") printCommandHelp(command, context.io);
+    if (command === "sync" && args[0] === "source") context.io.stdout(SOURCE_USAGE);
+    else if (command === "sync" && args[0] === "index") context.io.stdout(INDEX_USAGE);
+    else if (command && command !== "help") printCommandHelp(command, context.io);
     else printHelp(context.io);
     return;
   }
+  const confirm = (message) => confirmOrSkip(message, flags, context.ask);
   switch (command || "init") {
     case "init":
+      if (!boolFlag(flags, "--yes") && !stdinIsInteractive()) {
+        throw new UsageError(
+          "headband init asks questions, and stdin is not a terminal. Pass --yes to use the defaults.",
+          "confirmation_required"
+        );
+      }
       await init({ yes: boolFlag(flags, "--yes") });
       return;
     case "login":
       await runLogin(flags, context.io);
       return;
     case "logout":
-      await runLogout(flags, context.io);
+      await runLogout(flags, context.io, confirm);
       return;
     case "whoami":
       await runWhoami(flags, context.io);
       return;
+    case "profiles":
+      await runProfiles(args, flags, context.io);
+      return;
     case "projects":
-      await runProjects(args, flags, context.io);
+      await runProjects(args, flags, context.io, confirm);
       return;
     case "keys":
-      await runKeys(args, flags, context.io);
+      await runKeys(args, flags, context.io, confirm);
       return;
     case "indexes":
-      await runIndexes(args, flags, context.io);
+      await runIndexes(args, flags, context.io, confirm);
       return;
     case "docs":
-      await runDocs(args, flags, context.io);
+      await runDocs(args, flags, context);
       return;
     case "search":
       await runSearch(args, flags, context.io);
@@ -2696,37 +4407,61 @@ async function run(argv, context = { io: defaultIO }) {
       await runTasks(args, flags, context.io);
       return;
     case "schema":
-      await runSchema(args, flags, context.io);
+      await runSchema(args, flags, context.io, confirm);
       return;
     case "sync":
-      await runSync(args, flags, context.io);
+      await runSync(args, flags, context.io, confirm);
       return;
     case "instances":
-      await runInstances(
-        args,
-        flags,
-        context.io,
-        clientFromFlags(flags),
-        (message) => confirmOrSkip(message, flags)
-      );
+      await runInstances(args, flags, context.io, clientFromFlags(flags), confirm);
       return;
     default:
       printHelp(context.io);
-      throw new CliError(`Unknown command: ${command}`);
+      throw new UsageError(
+        /^[a-z][a-z-]{0,31}$/.test(command) ? `Unknown command: ${command}` : "Unknown command."
+      );
+  }
+}
+async function main(argv, context = { io: defaultIO }) {
+  const json = argv.includes("--json");
+  try {
+    await run(argv, context);
+    return EXIT_CODES.ok;
+  } catch (error) {
+    if (json) context.io.stderr(JSON.stringify(errorPayload(error)));
+    else
+      context.io.stderr(
+        error instanceof CliError ? error.message : error instanceof Error ? error.message : String(error)
+      );
+    return errorExitCode(error);
   }
 }
+function stdoutLineWriter(line) {
+  if (process.stdout.write(`${line}
+`)) return;
+  return new Promise((resolve) => process.stdout.once("drain", () => resolve()));
+}
 function isDirectRun() {
   return typeof require !== "undefined" && typeof module !== "undefined" && require.main === module;
 }
 if (isDirectRun()) {
-  run(process.argv.slice(2)).catch((error) => {
-    const message = error instanceof ApiError || error instanceof CliError ? error.message : String(error);
-    defaultIO.stderr(message);
-    process.exit(1);
+  process.stdout.on("error", (error) => {
+    if (error.code === "EPIPE") process.exit(EXIT_CODES.ok);
+    throw error;
+  });
+  void main(process.argv.slice(2), { io: defaultIO, writeLine: stdoutLineWriter }).then((code) => {
+    if (code === EXIT_CODES.ok) return;
+    process.exitCode = code;
+    setTimeout(() => process.exit(code), 2e3).unref();
   });
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  CLI_VERSION,
+  main,
   parseArgv,
-  run
+  parseExpires,
+  parsePermissions,
+  run,
+  stdinIsInteractive
 });