@headband/cli 0.6.0 → 0.7.0

package/README.md

@@ -187,7 +187,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 +198,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 +282,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
 
@@ -528,8 +540,11 @@ headband schema forget <index> [--yes] [--json]
 - `apply` runs the migration files the server does not have yet, in order. A
   new index is created and backfilled from every source row (rows
   `shouldIndex` rejects are left out). A schema change builds a new index
-  beside the live one, backfills it and switches the name over. Removing an
-  index needs `--allow-destructive`. `--json` prints
+  beside the live one, backfills it and switches the name over. Rows your app
+  writes during the backfill still go to the live index, so `apply` then
+  compares every document of the new index with its source row and writes the
+  ones that differ, once before the switch and once after it (CLI 0.6.1).
+  Removing an index needs `--allow-destructive`. `--json` prints
   `{appliedFiles, appliedOps, projectId}`.
 - `apply` recognises migrations the server already has from its schema state,
   so a fresh checkout or CI applies without `headband/migrations/.applied.json`.
@@ -600,7 +615,7 @@ changes to an outbox table, and the worker pushes them to Headband. The
 headband sync init [--table <name>] [--write] [--apply] [--json]
 headband sync worker [--loop] [--budget-ms <ms>] [--batch-size <n>] [--reconcile-every <n>] [--project <id>] [--json]
 headband sync worker --scaffold docker [--force] [--json]
-headband sync reconcile [--fix] [--json]
+headband sync reconcile [--content] [--fix] [--json]
 headband sync retry-dead-letters [--json]
 headband sync status [--json]
 ```
@@ -617,7 +632,9 @@ headband sync status [--json]
   `--json` sends progress to stderr and prints the report when the worker
   stops. A row that fails is printed with its model, ids and error; a batch
   that fails is retried row by row, so one bad row never fails the others.
-  Rows that keep failing move to the dead letters. Each invocation is recorded
+  Rows that keep failing move to the dead letters. A batch that fails because
+  Headband or the network is unavailable goes back to the queue without
+  counting an attempt, so an outage never fills the dead letters (CLI 0.6.1). Each invocation is recorded
   as one run under the connector `orm-sync` (`GET /v1/connectors/runs`); with
   the org-wide login key that needs `--project <id>` or the config's
   `projectId`. `--reconcile-every <n>` runs `reconcile` after every n-th batch.
@@ -626,8 +643,11 @@ headband sync status [--json]
   service for it. The container needs `DATABASE_URL` and `HEADBAND_API_KEY`.
 - `reconcile` compares the source rows that belong in each index (every row
   `shouldIndex` keeps) with the documents in it, and reports how many are
-  missing and how many are extra (counts, not ids). `--fix` pushes the missing
-  and deletes the extra. It exits
+  missing and how many are extra (counts, not ids). `--content` also compares
+  every document with its freshly resolved source row and counts the stale
+  ones; it reads the whole index, so it takes about as long as a backfill (CLI
+  0.6.1). `--fix` pushes the missing (and with `--content` the stale) and
+  deletes the extra. It exits
   `1` when drift is left. `--json` prints `{indexes, drift}`. The index's ids
   are read by cursor, so a Visor index past 1000 documents is compared id by
   id too.