@headband/cli 0.6.1 → 0.7.1

package/README.md

@@ -83,6 +83,7 @@ A script, CI job or agent does not need to log in. Give it a key:
 | `HEADBAND_API_KEY` | `--token`   | The API key to send. Used instead of any stored login. |
 | `HEADBAND_URL`     | `--url`     | The Headband URL.                                      |
 | `HEADBAND_PROFILE` | `--profile` | Which stored login to use.                             |
+| `HEADBAND_API_URL` |             | Where `/v1` calls go, if not the default below.        |
 
 Precedence, highest first:
 
@@ -92,6 +93,10 @@ Precedence, highest first:
   name the profile with `--profile`.
 - **Profile:** `--profile`, then `HEADBAND_PROFILE`, then the current profile,
   then the only stored profile when there is one.
+- **API host:** for `https://headband.dev`, every `/v1` call goes to
+  `https://api.headband.dev`, the API host on the servers that run the engines
+  (sign-in stays on `headband.dev`). Any other URL is used as is.
+  `HEADBAND_API_URL` overrides both.
 
 A stored key is only ever sent to the URL it was issued for. `--url` with no
 `--profile` picks the stored profile for that URL; `--url` with a `--profile`
@@ -187,7 +192,8 @@ has its own indexes and its own keys.
 
 ```bash
 headband branch list [--project <id>] [--json]
-headband branch create <name> --empty [--parent <name>] [--expires-in <2h|7d>] [--project <id>] [--json]
+headband branch create <name> [--empty] [--parent <name>] [--expires-in <2h|7d>] [--project <id>] [--json]
+headband branch ensure <name> [--from <parent>] [--expires-in <7d>] [--env-out <file>] [--project <id>] [--json]
 headband branch delete <name> [--project <id>] [--yes] [--json]
 headband branch protect <name> [--project <id>] [--json]
 headband branch unprotect <name> [--project <id>] [--json]
@@ -197,13 +203,25 @@ headband branch checkout <name> [--project <id>] [--json]
 
 - The project comes from `--project`, else the directory's checkout (below).
   With neither, the command is a usage error.
-- `create` makes an empty branch. Without `--empty` it fails with exit `6`
-  (code `fork_not_available`): copying a parent's data into a new branch
-  arrives with bucket storage. Until branches other than main open on the
-  server, every `create` fails with exit `6` (code `branches_not_open`),
-  `--empty` or not. `--parent` records the branch it comes from
-  (default: the primary branch). `--expires-in` deletes the branch on its own
-  after that long.
+- `create` forks the parent (`--parent`, default: the primary branch): the
+  new branch starts with the parent's indexes, documents and settings,
+  copy-on-write. `--empty` makes a branch with no indexes instead. A parent
+  with an index that cannot fork (Typesense, Visor, your own engine) fails
+  with exit `6` (code `fork_not_supported`). Until forking is on for your
+  organization, a fork fails with exit `6` (code `fork_not_available`), and
+  until branches other than main open, every `create` fails with exit `6`
+  (code `branches_not_open`). `--expires-in` deletes the branch on its own
+  after that long. Forking by default is new in CLI 0.7.0: before it,
+  `create` needed `--empty`.
+- `ensure` is for preview deploys, such as a Vercel build step. It forks the
+  branch from `--from` (default: the primary) unless it exists, pushes its
+  expiry `--expires-in` out (default `7d`), mints a search key and an admin
+  key on it, and writes `HEADBAND_URL`, `HEADBAND_PROJECT_ID`,
+  `HEADBAND_BRANCH`, `HEADBAND_BRANCH_ID`, `HEADBAND_SEARCH_KEY`,
+  `HEADBAND_ADMIN_KEY` and one `HEADBAND_<ENGINE>_URL` per engine to
+  `--env-out <file>`, replacing any `HEADBAND_*` lines there. Without
+  `--env-out` it prints them. The name is made branch-safe first, so a git
+  branch name works as is. It refuses the primary branch (CLI 0.7.0).
 - `delete` removes the branch with its indexes, keys and engines. It asks
   first. The primary branch, a protected branch, a branch with live child
   branches and a branch with Sync-owned indexes are refused (exit `6`).
@@ -269,8 +287,7 @@ error, so a name is never matched across projects by accident.
 project of their own and would ignore it. The exception is `keys create`, which
 sends the project in its body (see Keys).
 
-Coming with bucket storage: `branch create` without `--empty` (a copy of its
-parent), `reset`, `rollback`, `restore` and `set-primary`.
+Not available yet: `reset`, `rollback`, `restore` and `set-primary`.
 
 ### Keys
 

package/dist/index.js

@@ -42,8 +42,8 @@ __export(index_exports, {
   syncClientFromFlags: () => syncClientFromFlags
 });
 module.exports = __toCommonJS(index_exports);
-var import_fs11 = require("fs");
 var import_fs12 = require("fs");
+var import_fs13 = require("fs");
 var import_path11 = require("path");
 var import_prompts2 = __toESM(require("prompts"));
 var import_picocolors3 = __toESM(require("picocolors"));
@@ -528,7 +528,7 @@ function errorMessageOf(status, errorBody) {
   }
   return message;
 }
-var defaultSleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+var defaultSleep = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
 async function readJson(response) {
   const text = await response.text();
   if (!text) return {};
@@ -548,7 +548,7 @@ async function apiRequest(baseUrl, path2, init2 = {}) {
     headers.set("authorization", `Bearer ${init2.apiKey}`);
   }
   const base = normalizeUrl(baseUrl);
-  const { rateLimitRetries = 0, sleep = defaultSleep, apiKey: _apiKey, ...fetchInit } = init2;
+  const { rateLimitRetries = 0, sleep: sleep2 = defaultSleep, apiKey: _apiKey, ...fetchInit } = init2;
   void _apiKey;
   let response;
   try {
@@ -561,7 +561,7 @@ async function apiRequest(baseUrl, path2, init2 = {}) {
       const wait = response.status === 429 ? retryAfterSeconds(response) : null;
       if (wait === null || attempt >= rateLimitRetries) break;
       await response.body?.cancel().catch(() => void 0);
-      await sleep(wait * 1e3);
+      await sleep2(wait * 1e3);
     }
   } catch (error) {
     const cause = error?.cause;
@@ -583,8 +583,16 @@ async function apiRequest(baseUrl, path2, init2 = {}) {
   }
   return body;
 }
+var DEFAULT_API_URL = "https://api.headband.dev";
+function apiUrlFor(url, env = process.env) {
+  const override = env.HEADBAND_API_URL?.trim();
+  if (override) return normalizeUrl(override);
+  const normalized = normalizeUrl(url);
+  return normalized === DEFAULT_URL ? DEFAULT_API_URL : normalized;
+}
 function createApiClient(url, profile) {
-  const request = (path2, init2 = {}) => apiRequest(url, path2, {
+  const apiUrl = apiUrlFor(url);
+  const request = (path2, init2 = {}) => apiRequest(apiUrl, path2, {
     ...init2,
     apiKey: profile.apiKey,
     headers: profile.headers,
@@ -600,7 +608,7 @@ function createApiClient(url, profile) {
 }
 
 // src/auth.ts
-var defaultSleep2 = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+var defaultSleep2 = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
 function openBrowser(url) {
   try {
     if (process.platform === "darwin") {
@@ -615,7 +623,7 @@ function openBrowser(url) {
 }
 async function runDeviceFlow(url, io, options = {}) {
   const baseUrl = normalizeUrl(url);
-  const sleep = options.sleep || defaultSleep2;
+  const sleep2 = options.sleep || defaultSleep2;
   const now = options.now || Date.now;
   const device = await apiRequest(baseUrl, "/api/cli/device", {
     method: "POST",
@@ -630,7 +638,7 @@ async function runDeviceFlow(url, io, options = {}) {
   let interval = device.data.interval;
   const deadline = now() + device.data.expiresIn * 1e3;
   while (now() < deadline) {
-    await sleep(interval * 1e3);
+    await sleep2(interval * 1e3);
     try {
       const token = await apiRequest(baseUrl, "/api/cli/token", {
         method: "POST",
@@ -685,6 +693,7 @@ async function login(url, io, options = {}) {
 }
 
 // src/branch.ts
+var import_fs4 = require("fs");
 var import_path5 = require("path");
 
 // src/output.ts
@@ -894,14 +903,22 @@ var PART_2 = /* @__PURE__ */ new Set(["reset", "rollback", "restore", "set-prima
 var BRANCH_USAGE = [
   "Usage:",
   "  headband branch list [--project <id>] [--json]",
-  "  headband branch create <name> --empty [--parent <name>] [--expires-in <2h|7d>] [--project <id>] [--json]",
+  "  headband branch create <name> [--empty] [--parent <name>] [--expires-in <2h|7d>] [--project <id>] [--json]",
+  "  headband branch ensure <name> [--from <parent>] [--expires-in <7d>] [--env-out <file>] [--project <id>] [--json]",
   "  headband branch delete <name> [--project <id>] [--yes] [--json]",
   "  headband branch protect <name> [--project <id>] [--json]",
   "  headband branch unprotect <name> [--project <id>] [--json]",
   "  headband branch expire <name> (--in <2h|7d> | --at <iso> | --clear) [--project <id>] [--json]",
   "  headband branch checkout <name> [--project <id>] [--json]",
-  "  headband branch create <name> (without --empty, a fork)   coming with bucket storage",
-  "  headband branch reset|rollback|restore|set-primary <name>  coming with bucket storage",
+  "  headband branch reset|rollback|restore|set-primary <name>  not available yet",
+  "",
+  "create without --empty forks the parent (default: main): its indexes, documents and settings,",
+  "copy-on-write. --empty makes a branch with no indexes.",
+  "",
+  "ensure is for preview deploys: it forks the branch unless it exists, pushes its expiry out",
+  "(--expires-in, default 7d), mints a search key and an admin key for it, and writes HEADBAND_*",
+  "variables to --env-out (or prints them). The name is made branch-safe first: feature/Foo_Bar",
+  "becomes feature/foo_bar. It refuses the primary branch.",
   "",
   "The project comes from --project, else the directory's checkout (.headband/project.json).",
   "Durations take s, m, h, d or w: 30m, 2h, 7d.",
@@ -1000,10 +1017,7 @@ async function runBranch(args, flags, deps) {
   const action = args[0];
   const json = flags["--json"] === true;
   if (action && PART_2.has(action)) {
-    throw new UsageError(
-      `headband branch ${action} is coming with bucket storage.`,
-      "not_available"
-    );
+    throw new UsageError(`headband branch ${action} is not available yet.`, "not_available");
   }
   const client = createApiClient(auth.url, { apiKey: auth.apiKey });
   const checkout = () => checkoutFor(cwd, auth.profile?.orgId);
@@ -1032,18 +1046,35 @@ async function runBranch(args, flags, deps) {
       if (error instanceof ApiError && error.code === "branches_not_open") {
         throw restate(error, "Branches other than main are not open yet.");
       }
-      if (error instanceof ApiError && error.code === "fork_not_available") {
-        throw restate(
-          error,
-          "Forking arrives with bucket storage. Pass --empty for an empty branch."
-        );
-      }
-      throw error;
+      throw restateCreate(error);
     }
     if (json) printJson(io, response);
     else printTable(io, [response.data], COLUMNS);
     return;
   }
+  if (action === "ensure") {
+    const result = await ensureBranch(client, {
+      name: branchNameFrom(requiredName(args[1])),
+      project: projectFor(flags, checkout),
+      from: stringFlag2(flags, "--from"),
+      expiresInMs: parseDuration(stringFlag2(flags, "--expires-in") ?? "7d"),
+      url: auth.url
+    });
+    const envOut = stringFlag2(flags, "--env-out");
+    if (envOut && envOut !== "-") writeEnvFile((0, import_path5.resolve)(cwd, envOut), result.env);
+    if (json) {
+      printJson(io, { branch: result.branch, created: result.created, env: result.env });
+    } else if (envOut && envOut !== "-") {
+      const engines = result.branch.instances?.length ?? 0;
+      io.stdout(
+        `${result.created ? "Forked" : "Reused"} branch ${result.branch.name} (${engines} engine${engines === 1 ? "" : "s"}), expires ${result.branch.expiresAt}.`
+      );
+      io.stdout(`Wrote ${Object.keys(result.env).length} HEADBAND_* variables to ${envOut}.`);
+    } else {
+      io.stdout(dotenv(result.env));
+    }
+    return;
+  }
   if (action === "delete") {
     const name = requiredName(args[1]);
     const project = projectFor(flags, checkout);
@@ -1115,9 +1146,109 @@ async function runBranch(args, flags, deps) {
   io.stdout(BRANCH_USAGE);
   throw new UsageError("Unknown branch command");
 }
+function restateCreate(error) {
+  if (error instanceof ApiError && error.code === "branches_not_open") {
+    return restate(error, "Branches other than main are not open yet.");
+  }
+  if (error instanceof ApiError && error.code === "fork_not_available") {
+    return restate(error, "Forking is not open yet. Pass --empty for an empty branch.");
+  }
+  return error;
+}
+function branchNameFrom(ref) {
+  const name = ref.trim().toLowerCase().replace(/[^a-z0-9._/-]+/g, "-").slice(0, 63).replace(/^[^a-z0-9]+/, "").replace(/[^a-z0-9]+$/, "");
+  if (!name) throw new UsageError(`"${ref}" has no letters or digits to make a branch name from.`);
+  return name;
+}
+var ENSURE_WAIT_MS = 6e4;
+var ENSURE_POLL_MS = 2e3;
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var engineVar = (engine) => `HEADBAND_${engine.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_URL`;
+async function ensureBranch(client, o, now = Date.now) {
+  var _a;
+  const path2 = `/v1/branches/${encodeURIComponent(o.name)}?project=${encodeURIComponent(o.project)}`;
+  const read = async () => {
+    try {
+      return (await client.get(path2)).data;
+    } catch (error) {
+      if (error instanceof ApiError && error.status === 404 && error.code === "branch_not_found") {
+        return null;
+      }
+      throw error;
+    }
+  };
+  const expiresAt = () => new Date(now() + o.expiresInMs).toISOString();
+  let branch = await read();
+  let created = false;
+  if (!branch) {
+    const body = {
+      name: o.name,
+      projectId: o.project,
+      expiresAt: expiresAt()
+    };
+    if (o.from) body.parent = o.from;
+    try {
+      branch = (await client.post("/v1/branches", body)).data;
+      created = true;
+    } catch (error) {
+      if (!(error instanceof ApiError && error.code === "branch_exists"))
+        throw restateCreate(error);
+      branch = await read();
+      if (!branch) throw error;
+    }
+  }
+  if (branch.primary) {
+    throw new UsageError(
+      `${branch.name} is the primary branch. ensure is for preview branches; run it only on preview builds.`
+    );
+  }
+  for (const until = now() + ENSURE_WAIT_MS; branch.state === "creating" && now() < until; ) {
+    await sleep(ENSURE_POLL_MS);
+    branch = await read() ?? branch;
+  }
+  if (branch.state !== "ready") {
+    throw new CliError(`Branch ${branch.name} is ${branch.state}, not ready. Try again shortly.`, {
+      exitCode: EXIT_CODES.conflict,
+      code: "branch_not_ready"
+    });
+  }
+  if (!created && !branch.protected) {
+    branch = {
+      ...branch,
+      ...(await client.patch(path2, { expiresAt: expiresAt() })).data
+    };
+  }
+  if (!branch.instances)
+    branch = { ...branch, ...(await client.get(path2)).data };
+  const mint = async (type) => (await client.post("/v1/keys", {
+    name: `preview ${branch.name} ${type}`,
+    type,
+    projectId: o.project,
+    branch: branch.id
+  })).data.apiKey;
+  const env = {
+    HEADBAND_URL: o.url,
+    HEADBAND_PROJECT_ID: o.project,
+    HEADBAND_BRANCH: branch.name,
+    HEADBAND_BRANCH_ID: branch.id,
+    HEADBAND_SEARCH_KEY: await mint("search"),
+    HEADBAND_ADMIN_KEY: await mint("admin")
+  };
+  for (const i of branch.instances ?? []) env[_a = engineVar(i.engine)] ?? (env[_a] = i.endpoint);
+  return { branch, created, env };
+}
+var quote = (v) => /^[A-Za-z0-9_./:@+-]*$/.test(v) ? v : JSON.stringify(v);
+function dotenv(env) {
+  return Object.entries(env).map(([k, v]) => `${k}=${quote(v)}`).join("\n");
+}
+function writeEnvFile(file, env) {
+  const kept = (0, import_fs4.existsSync)(file) ? (0, import_fs4.readFileSync)(file, "utf8").split("\n").filter((line) => line.trim() !== "" && !/^\s*(export\s+)?HEADBAND_[A-Z0-9_]*=/.test(line)) : [];
+  (0, import_fs4.writeFileSync)(file, [...kept, dotenv(env)].join("\n") + "\n", { mode: 384 });
+  (0, import_fs4.chmodSync)(file, 384);
+}
 
 // src/config-load.ts
-var import_fs4 = require("fs");
+var import_fs5 = require("fs");
 var import_path6 = require("path");
 var import_url = require("url");
 var import_jiti = require("jiti");
@@ -1253,7 +1384,7 @@ var SYNC_CONFIG_SHAPE = 'a headband.config.ts whose default export is defineConf
 function findConfigFile(cwd) {
   for (const name of CONFIG_FILENAMES) {
     const path2 = (0, import_path6.join)(cwd, name);
-    if ((0, import_fs4.existsSync)(path2)) return path2;
+    if ((0, import_fs5.existsSync)(path2)) return path2;
   }
   return void 0;
 }
@@ -1373,10 +1504,10 @@ function missingAdapterError(command, why) {
 
 // src/docs.ts
 var import_path7 = require("path");
-var import_fs5 = require("fs");
+var import_fs6 = require("fs");
 var DOCS_BATCH_SIZE = 1e3;
 function parseDocumentsFile(path2) {
-  const content = (0, import_fs5.readFileSync)(path2, "utf-8");
+  const content = (0, import_fs6.readFileSync)(path2, "utf-8");
   const ext = (0, import_path7.extname)(path2).toLowerCase();
   if (ext === ".jsonl") {
     return content.split(/\r?\n/).map((line) => line.trim()).filter(Boolean).map((line) => JSON.parse(line));
@@ -1501,7 +1632,7 @@ function refusedWalk(error) {
 var DECLARE_WAIT_MS = 15 * 6e4;
 var DECLARE_POLL_MS = 3e3;
 async function declareExportKey(client, index, io, opts = {}) {
-  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const sleep2 = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   const now = opts.now ?? Date.now;
   const probe = () => client.get(`/v1/documents?index=${encodeURIComponent(index)}&limit=1&cursor=`);
   let refused;
@@ -1547,7 +1678,7 @@ async function declareExportKey(client, index, io, opts = {}) {
         `\`${pk}\` is still not declared on ${index} after ${Math.round((opts.waitMs ?? DECLARE_WAIT_MS) / 6e4)} minutes. Visor may still be rebuilding it: run headband docs export again later.`
       );
     }
-    await sleep(DECLARE_POLL_MS);
+    await sleep2(DECLARE_POLL_MS);
   }
 }
 function exportRefusalAdvice(error, index) {
@@ -1613,6 +1744,7 @@ function documentsMatch(expected, remote, primaryKey) {
 }
 
 // ../../src/lib/density/catalog-constants.ts
+var FREE_ALWAYS_ON_CLOSED_AT = Date.parse("2026-11-10T00:00:00Z");
 function formatMemory(mb) {
   return mb >= 1024 ? `${mb / 1024} GB` : `${mb} MB`;
 }
@@ -2167,7 +2299,7 @@ async function runSwitchEngine(client, opts, io, chatter) {
     );
     return;
   }
-  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const sleep2 = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   let lastPhase = "";
   for (; ; ) {
     if (view.phase !== lastPhase) {
@@ -2175,7 +2307,7 @@ async function runSwitchEngine(client, opts, io, chatter) {
       chatter.stdout(`${opts.uid}: ${PHASES[view.phase] ?? view.phase}`);
     }
     if (view.status === "succeeded" || view.status === "failed") break;
-    await sleep(opts.pollMs ?? 3e3);
+    await sleep2(opts.pollMs ?? 3e3);
     const status = await client.get(path2);
     if (!status.switch || status.switch.switchId !== view.switchId) {
       throw new CliError("The switch is no longer listed for this index.", {
@@ -2312,11 +2444,11 @@ function planMigration(config, applied, opts) {
 }
 
 // src/schema.ts
-var import_fs7 = require("fs");
+var import_fs8 = require("fs");
 var import_path9 = require("path");
 
 // ../sync/src/migrations.ts
-var import_fs6 = require("fs");
+var import_fs7 = require("fs");
 var import_path8 = require("path");
 var FILE_NAME_RE = /^(\d{4})_(.+)\.json$/;
 function sanitizeSlug(slug) {
@@ -2324,7 +2456,7 @@ function sanitizeSlug(slug) {
   return sanitized || "migration";
 }
 function generateMigrationFile(dir, ops, meta, now = () => /* @__PURE__ */ new Date()) {
-  (0, import_fs6.mkdirSync)(dir, { recursive: true });
+  (0, import_fs7.mkdirSync)(dir, { recursive: true });
   const existing = readMigrations(dir);
   const nextVersion = existing.length === 0 ? 1 : existing[existing.length - 1].version + 1;
   const safeSlug = sanitizeSlug(meta.slug);
@@ -2337,13 +2469,13 @@ function generateMigrationFile(dir, ops, meta, now = () => /* @__PURE__ */ new D
     ...meta.targetHashes ? { targetHashes: meta.targetHashes } : {},
     ops
   };
-  (0, import_fs6.writeFileSync)(path2, JSON.stringify(file, null, 2));
+  (0, import_fs7.writeFileSync)(path2, JSON.stringify(file, null, 2));
   return path2;
 }
 function readMigrations(dir) {
   let entries;
   try {
-    entries = (0, import_fs6.readdirSync)(dir);
+    entries = (0, import_fs7.readdirSync)(dir);
   } catch {
     return [];
   }
@@ -2352,7 +2484,7 @@ function readMigrations(dir) {
     const match = FILE_NAME_RE.exec(entry);
     if (!match) continue;
     const path2 = (0, import_path8.join)(dir, entry);
-    const raw = (0, import_fs6.readFileSync)(path2, "utf-8");
+    const raw = (0, import_fs7.readFileSync)(path2, "utf-8");
     let parsed;
     try {
       parsed = JSON.parse(raw);
@@ -2382,7 +2514,7 @@ function pendingMigrations(files, appliedVersion) {
 var BASE_BACKOFF_MS = 500;
 var DEFAULT_MAX_RETRIES = 5;
 function defaultSleep3(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 var SchemaCasError = class extends Error {
   constructor(message) {
@@ -2549,17 +2681,17 @@ function printOpsTable(io, ops) {
 }
 function readAppliedMarker(dir) {
   const path2 = (0, import_path9.join)(dir, APPLIED_MARKER_FILE);
-  if (!(0, import_fs7.existsSync)(path2)) return 0;
+  if (!(0, import_fs8.existsSync)(path2)) return 0;
   try {
-    const parsed = JSON.parse((0, import_fs7.readFileSync)(path2, "utf-8"));
+    const parsed = JSON.parse((0, import_fs8.readFileSync)(path2, "utf-8"));
     return typeof parsed.version === "number" ? parsed.version : 0;
   } catch {
     return 0;
   }
 }
 function writeAppliedMarker(dir, version) {
-  (0, import_fs7.mkdirSync)(dir, { recursive: true });
-  (0, import_fs7.writeFileSync)((0, import_path9.join)(dir, APPLIED_MARKER_FILE), JSON.stringify({ version }, null, 2));
+  (0, import_fs8.mkdirSync)(dir, { recursive: true });
+  (0, import_fs8.writeFileSync)((0, import_path9.join)(dir, APPLIED_MARKER_FILE), JSON.stringify({ version }, null, 2));
 }
 function configHashes(config, index) {
   const def = config.indexes.find((d) => d.name === index);
@@ -3068,7 +3200,7 @@ async function runSchemaForget(deps) {
 }
 
 // src/sync.ts
-var import_fs8 = require("fs");
+var import_fs9 = require("fs");
 var import_path10 = require("path");
 var import_crypto = require("crypto");
 var import_pg = require("pg");
@@ -3359,7 +3491,7 @@ function rowOutcomes(rows, resolved, failures) {
   return { done, retry, deadLetter };
 }
 function defaultSleep4(ms) {
-  return new Promise((resolve2) => setTimeout(resolve2, ms));
+  return new Promise((resolve3) => setTimeout(resolve3, ms));
 }
 function errorMessage(err) {
   if (!(err instanceof Error)) return String(err);
@@ -3399,7 +3531,7 @@ async function runSyncWorker(opts) {
     batchSize = DEFAULT_BATCH_SIZE,
     stopSignal,
     now = Date.now,
-    sleep = defaultSleep4,
+    sleep: sleep2 = defaultSleep4,
     onHeartbeat,
     log = (message) => console.warn(message)
   } = opts;
@@ -3426,7 +3558,7 @@ async function runSyncWorker(opts) {
       log(`[headband] could not record this worker run: ${errorMessage(err)}`);
     }
   };
-  const backoff = (attempt) => sleep(Math.min(failureDelayMs * 2 ** (attempt - 1), MAX_FAILURE_DELAY_MS));
+  const backoff = (attempt) => sleep2(Math.min(failureDelayMs * 2 ** (attempt - 1), MAX_FAILURE_DELAY_MS));
   const processBatch = async (batch) => {
     const changes = batch.map((row) => ({
       model: row.model,
@@ -3468,7 +3600,7 @@ async function runSyncWorker(opts) {
     const rows = await outbox.claim(batchSize);
     if (rows.length === 0) {
       if (!loop) break;
-      await sleep(idleDelayMs);
+      await sleep2(idleDelayMs);
       continue;
     }
     let outcome;
@@ -3627,8 +3759,8 @@ async function runSyncInit(deps) {
   deps.io.stdout(ddl);
   if (deps.write) {
     const path2 = (0, import_path10.join)(deps.cwd ?? process.cwd(), OUTBOX_SQL_RELATIVE_PATH);
-    (0, import_fs8.mkdirSync)((0, import_path10.join)(deps.cwd ?? process.cwd(), "headband"), { recursive: true });
-    (0, import_fs8.writeFileSync)(path2, `${ddl}
+    (0, import_fs9.mkdirSync)((0, import_path10.join)(deps.cwd ?? process.cwd(), "headband"), { recursive: true });
+    (0, import_fs9.writeFileSync)(path2, `${ddl}
 `);
     deps.io.stdout(`Wrote ${path2}`);
   }
@@ -4014,10 +4146,10 @@ async function runSelfHostedSyncStatus(deps) {
 }
 function runSyncScaffoldDocker(deps) {
   const path2 = (0, import_path10.join)(deps.cwd, DOCKERFILE_NAME);
-  if ((0, import_fs8.existsSync)(path2) && !deps.force) {
+  if ((0, import_fs9.existsSync)(path2) && !deps.force) {
     throw new CliError(`${DOCKERFILE_NAME} already exists at ${path2}. Pass --force to overwrite.`);
   }
-  (0, import_fs8.writeFileSync)(path2, dockerfileContent(deps.cliVersion));
+  (0, import_fs9.writeFileSync)(path2, dockerfileContent(deps.cliVersion));
   deps.io.stdout(`Wrote ${path2}`);
   deps.io.stdout("Add this service to your docker-compose.yml:");
   deps.io.stdout(COMPOSE_SNIPPET);
@@ -4194,10 +4326,10 @@ ${CONFIG_NOTE}`,
 };
 
 // src/sync-indexes.ts
-var import_fs10 = require("fs");
+var import_fs11 = require("fs");
 
 // src/sync-sources.ts
-var import_fs9 = require("fs");
+var import_fs10 = require("fs");
 var import_pg2 = require("pg");
 
 // ../../src/lib/sync/copy.ts
@@ -4264,7 +4396,7 @@ var SOURCE_USAGE = [
 function readCaFile(deps, file) {
   let text;
   try {
-    text = (deps.readFile ?? ((p) => (0, import_fs9.readFileSync)(p, "utf8")))(file);
+    text = (deps.readFile ?? ((p) => (0, import_fs10.readFileSync)(p, "utf8")))(file);
   } catch {
     throw new CliError("Cannot read the --ca-file.");
   }
@@ -4905,7 +5037,7 @@ 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_fs10.readFileSync)(p, "utf8")) {
+function readDefinition(file, readFile = (p) => (0, import_fs11.readFileSync)(p, "utf8")) {
   let text;
   try {
     text = readFile(file);
@@ -5324,6 +5456,8 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "--branch",
   "--parent",
   "--expires-in",
+  "--env-out",
+  "--from",
   "--in",
   "--at",
   "--level",
@@ -5453,7 +5587,8 @@ function syncClientFromFlags(flags, cwd, options = {}) {
     return fetch(input, { ...init2, headers: merged });
   } : void 0;
   return new HeadbandClient({
-    url: auth.url,
+    // The sync client calls /v1 only: the same API host as every other /v1 call (api.ts).
+    url: apiUrlFor(auth.url),
     adminKey: auth.apiKey,
     ...fetchImpl ? { fetchImpl } : {}
   });
@@ -5496,12 +5631,13 @@ Commands:
   projects create <name> --engine <meilisearch|typesense|elasticsearch|visor> [--json]
   projects delete <id> [--yes] [--json]
   branch list [--project <id>] [--json]
-  branch create <name> --empty [--parent <name>] [--expires-in <2h|7d>] [--project <id>] [--json]
+  branch create <name> [--empty] [--parent <name>] [--expires-in <2h|7d>] [--project <id>] [--json]
+  branch ensure <name> [--from <parent>] [--expires-in <7d>] [--env-out <file>] [--project <id>] [--json]
   branch delete <name> [--project <id>] [--yes] [--json]
   branch protect|unprotect <name> [--project <id>] [--json]
   branch expire <name> (--in <2h|7d> | --at <iso> | --clear) [--project <id>] [--json]
   branch checkout <name> [--project <id>] [--json]
-  branch reset|rollback|restore|set-primary (coming with bucket storage)
+  branch reset|rollback|restore|set-primary (not available yet)
   keys list [--json]
   keys create <name> --type <admin|search> [--project <id>] [--branch <name>] [--instances <id,id>] [--indexes <uid,uid>] [--permissions <a,b>] [--expires <30d|ISO date>] [--json]
   keys revoke <id> [--yes] [--json]
@@ -6054,7 +6190,7 @@ async function runIndexes(args, flags, io, confirm, cwd) {
     }
     if (settingsAction === "set") {
       const file = requiredFlag(flags, "--file");
-      const settings = JSON.parse((0, import_fs12.readFileSync)(file, "utf-8"));
+      const settings = JSON.parse((0, import_fs13.readFileSync)(file, "utf-8"));
       const response = await client.patch(`/v1/indexes/${encode(uid)}/settings`, settings);
       printJson(io, response);
       return;
@@ -6115,7 +6251,7 @@ async function runDocsExport(flags, context, cwd) {
     return;
   }
   const partial = `${out}.partial`;
-  const fd = (0, import_fs11.openSync)(partial, "w", 384);
+  const fd = (0, import_fs12.openSync)(partial, "w", 384);
   let exported;
   try {
     exported = await exportDocuments(client, {
@@ -6123,26 +6259,26 @@ async function runDocsExport(flags, context, cwd) {
       format,
       batchSize,
       write: (line) => {
-        (0, import_fs11.writeSync)(fd, `${line}
+        (0, import_fs12.writeSync)(fd, `${line}
 `);
       },
       onPage: (count, total) => io.stderr(`Exported ${count}${total === null ? "" : `/${total}`} documents`),
       finishOnError: true
     });
-    (0, import_fs11.closeSync)(fd);
+    (0, import_fs12.closeSync)(fd);
   } catch (error) {
-    (0, import_fs11.closeSync)(fd);
+    (0, import_fs12.closeSync)(fd);
     const kept = error instanceof ExportInterruptedError ? error.exported : 0;
     if (kept > 0) {
       io.stderr(
         `Kept the ${kept} ${kept === 1 ? "document" : "documents"} exported before the error in ${partial}. ${out} was not written.`
       );
     } else {
-      (0, import_fs11.rmSync)(partial, { force: true });
+      (0, import_fs12.rmSync)(partial, { force: true });
     }
     throw exportFailure(error instanceof ExportInterruptedError ? error.cause : error, index);
   }
-  (0, import_fs11.renameSync)(partial, out);
+  (0, import_fs12.renameSync)(partial, out);
   if (boolFlag(flags, "--json")) printJson(io, { index, out, format, exported });
   else io.stdout(`Exported ${exported} documents to ${out}.`);
 }
@@ -6513,7 +6649,7 @@ async function runSync(args, flags, io, confirm, cwd) {
   printCommandHelp("sync", io);
   throw new UsageError("Unknown sync command");
 }
-var CLI_VERSION = true ? "0.6.1" : "dev";
+var CLI_VERSION = true ? "0.7.1" : "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);
@@ -6615,7 +6751,7 @@ async function main(argv, context = { io: defaultIO }) {
 function stdoutLineWriter(line) {
   if (process.stdout.write(`${line}
 `)) return;
-  return new Promise((resolve2) => process.stdout.once("drain", () => resolve2()));
+  return new Promise((resolve3) => process.stdout.once("drain", () => resolve3()));
 }
 function isDirectRun() {
   return typeof require !== "undefined" && typeof module !== "undefined" && require.main === module;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@headband/cli",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "CLI tool for setting up Headband search in any project",
   "bin": {
     "headband": "dist/index.js"