@headband/cli 0.2.0 → 0.6.0

package/README.md

@@ -1,9 +1,9 @@
 # @headband/cli
 
-Command-line tools for [Headband](https://headband.dev): project setup, device login,
-API key management, index operations, document pushes, search, and task inspection.
-
-## Usage
+Command-line tools for [Headband](https://headband.dev): project setup, login,
+branches, API keys, indexes, documents, search, tasks, dedicated engines, schema
+migrations and Sync. Every command works for a person at a terminal and for a
+script or coding agent with no terminal at all.
 
 ```bash
 npx @headband/cli --help
@@ -11,85 +11,349 @@ npx @headband/cli init
 npx @headband/cli login
 ```
 
-Global flags:
+## Contents
+
+- [Global options](#global-options)
+- [Authentication](#authentication)
+- [Scripts and agents](#scripts-and-agents)
+- [Exit codes](#exit-codes)
+- [Command reference](#command-reference)
+- [What `init` creates](#what-init-creates)
+
+## Global options
+
+```text
+--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 https://headband.dev)
+--branch <name>    Work on this branch for one call, in the project from --project <id>,
+                   else the checkout's (see Branches). A branch id (br_...) is sent as it is.
+                   Without --branch or a checkout, calls reach the primary branches.
+--json             Print one JSON document on stdout; errors print one JSON object on stderr
+--yes, -y          Answer yes to confirmations (required when stdin is not a terminal)
+--help, -h         Show help for the CLI or a command
+```
+
+## Authentication
+
+### Interactive login
 
 ```bash
---url <url>    Select a Headband profile URL
---json         Print JSON for supported list/get commands
---yes          Skip confirmation prompts
---help         Show help
+headband login [--url <url>] [--profile <name>] [--json]
+headband logout [--profile <name>] [--yes] [--no-revoke] [--json]
+headband whoami [--json]
+headband profiles list [--json]
+headband profiles use <name>
 ```
 
-Credentials are stored in `~/.config/headband/credentials.json` or
-`$XDG_CONFIG_HOME/headband/credentials.json` with file mode `0600`.
-
-## Commands
+`login` runs Headband's device flow: it prints a code and a link, opens your
+browser, and waits while you approve it in the dashboard. It saves the key it
+receives as a named profile and makes that profile current. The name defaults
+to `default` for headband.dev and to the host name for any other URL, such as
+`localhost-3000`. The full key is never printed; output shows only its prefix.
 
-### Setup
+Log in to several Headband URLs or organizations and switch between them:
 
 ```bash
-headband init [--yes]
+headband login --profile prod
+headband login --url http://localhost:3000 --profile local
+headband profiles list
+headband profiles use prod
+headband indexes list --profile local   # one command, without switching
 ```
 
-This will:
+`logout` revokes the profile's key on the server, then removes it from this
+machine. It asks first at a terminal. `--yes` revokes without asking.
+`--no-revoke` removes the local copy and leaves the key working. If the key is
+already gone on the server, logout still succeeds; any other failure keeps the
+local login so you can retry.
+
+Credentials live in `~/.config/headband/credentials.json`, or
+`$XDG_CONFIG_HOME/headband/credentials.json`, with file mode `0600`. A file
+written by CLI 0.2.0 or earlier (profiles keyed by URL) still works: its
+profiles get names on first read, and the file is saved in the new format the
+next time the CLI writes it.
+
+### Tokens and environment variables
+
+A script, CI job or agent does not need to log in. Give it a key:
 
-1. Ask for your Headband URL (default: `https://headband.dev`)
-2. Ask for your browser-safe search API key (`hb_src_...` only)
-3. Ask for your default search index (e.g. `products`, `movies`)
-4. Detect your package manager (npm, pnpm, yarn, or bun)
-5. Install `@headband/react`
-6. Create `headband.config.ts` with your settings
-7. Create an example `<HeadbandSearch />` component
+| Variable           | Flag        | Meaning                                                |
+| ------------------ | ----------- | ------------------------------------------------------ |
+| `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.                             |
 
-## Options
+Precedence, highest first:
+
+- **Key:** `--token`, then `HEADBAND_API_KEY`, then the stored profile.
+- **URL:** `--url`, then `HEADBAND_URL`, then the profile's URL, then
+  `https://headband.dev`. With a token, the profile's URL counts only when you
+  name the profile with `--profile`.
+- **Profile:** `--profile`, then `HEADBAND_PROFILE`, then the current profile,
+  then the only stored profile when there is one.
+
+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`
+for a different URL is a usage error. A `--profile` name that does not exist is
+an error, never a silent fallback.
 
 ```bash
-npx @headband/cli init --yes   # Skip prompts, use defaults
-npx @headband/cli --help       # Show help
+export HEADBAND_API_KEY=hb_adm_...
+export HEADBAND_URL=https://headband.dev
+headband indexes list --json
 ```
 
-### Auth
+Which key to use: an admin key from `headband keys create <name> --type admin`
+covers indexes, documents, search, engines and Sync. Managing keys, projects,
+branches and schema state needs a key minted by `headband login`, because only
+those carry `keys.manage`, `projects.manage`, `branches.manage` and
+`schema.manage`.
+
+## Scripts and agents
+
+The CLI never waits for input it cannot get.
+
+- **No hanging prompts.** A command that would ask for confirmation fails at
+  once with exit code `2` and code `confirmation_required` when stdin is not a
+  terminal. Pass `--yes` to confirm. `headband init` does the same without
+  `--yes`.
+- **One JSON document.** With `--json`, stdout carries exactly one JSON
+  document and progress lines go to stderr, so `headband ... --json | jq` is
+  safe. `docs export` is the exception by design: its output is the documents.
+- **JSON errors.** With `--json`, a failure prints one line to stderr:
+
+  ```json
+  { "error": "Index not found", "code": "index_not_found", "status": 404, "exitCode": 5 }
+  ```
+
+  `code` is the API's error code when there is one, else a CLI code such as
+  `usage_error`, `not_authenticated`, `confirmation_required` or
+  `network_error`. `status` is the HTTP status, or `null` when no request was
+  made.
+
+- **Rate limits.** A `429` whose `Retry-After` is 10 seconds or less is
+  retried up to twice after that wait (CLI 0.6.0). If it still fails, the
+  command exits `7` and the message keeps the server's hint, such as
+  "Retry after 1s.". A write where some documents were rejected names the
+  first rejected document and the engine's reason.
+- **Branch on exit codes**, not on message text. See the table below.
+
+## Exit codes
+
+| Code  | Meaning          | Typical cause                                                                                                   |
+| ----- | ---------------- | --------------------------------------------------------------------------------------------------------------- |
+| `0`   | Success          |                                                                                                                 |
+| `1`   | Error            | Anything not listed below; also `schema diff` when changes are pending, `sync reconcile` when drift is left     |
+| `2`   | Usage            | Unknown command or option, missing or malformed value, HTTP 400/413/422, confirmation needed without a terminal |
+| `3`   | Authentication   | No key found, a `--profile` that does not exist, HTTP 401                                                       |
+| `4`   | Permission       | HTTP 403, or 402 (the plan does not allow it)                                                                   |
+| `5`   | Not found        | HTTP 404 or 410, `profiles use` with an unknown name                                                            |
+| `6`   | Conflict         | HTTP 409, such as deleting a project that still has indexes                                                     |
+| `7`   | Rate limited     | HTTP 429                                                                                                        |
+| `8`   | Server or engine | HTTP 5xx, or the URL could not be reached                                                                       |
+| `130` | Interrupted      | Ctrl+C                                                                                                          |
+
+## Command reference
+
+### Setup
 
 ```bash
-headband login [--url <url>]
-headband logout [--url <url>] [--yes]
-headband whoami [--url <url>] [--json]
+headband init [--yes]
 ```
 
-`login` uses Headband's device flow and stores only the API key profile locally.
-The full key is never printed during login; success output shows only the key
-prefix. `logout` removes local credentials and can offer to revoke the CLI key
-server-side first.
+Asks for your Headband URL, a browser-safe search key (`hb_src_...` only) and
+a default index, installs `@headband/react`, and writes `headband.config.ts`
+plus an example `<HeadbandSearch />` component. `--yes` skips the questions and
+uses defaults. Running `headband` with no command runs `init`.
 
 ### Projects
 
 ```bash
 headband projects list [--json]
-headband projects create <name> --engine <meilisearch|typesense|elasticsearch>
+headband projects create <name> --engine <meilisearch|typesense|elasticsearch|visor> [--json]
+headband projects delete <id> [--yes] [--json]
+```
+
+`projects delete` refuses a project that still has indexes (exit `6`, code
+`project_not_empty`). Delete its indexes first. Deleting a project
+also deletes the API keys scoped to it.
+
+### Branches
+
+A branch is one environment of a project: its primary branch `main`
+(production), plus others such as `staging` or `preview/pr-123`. Each branch
+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 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]
+```
+
+- 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.
+- `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`).
+- `protect` blocks delete and expiry; `unprotect` lifts it. The primary
+  branch (`main`) serves production and is always protected: `unprotect`,
+  `expire` and `delete` on it are refused (exit `6`, code `branch_is_primary`).
+- `expire` takes exactly one of `--in <duration>`, `--at <ISO time>` (in the
+  future) or `--clear`.
+- Durations are a number and a unit: `s`, `m`, `h`, `d` or `w`, such as `30m`,
+  `2h` or `7d`.
+- Creating, deleting, protecting and expiring need the key from
+  `headband login`. `branch list` works with any admin key that reaches the
+  project.
+
+**Working on a branch.** `checkout` makes a directory work on one branch:
+
+```bash
+headband branch checkout staging --project <project id>
+headband indexes list              # staging's indexes
+headband docs push products.json --index products
+headband search products shoes     # searches staging
 ```
 
+`checkout` writes `.headband/project.json`: `{ "orgId", "projectId", "branch" }`,
+with file mode `0600`. It holds no key. Every later command in that directory,
+or in any directory below it, sends `Headband-Branch: <project id>/<branch>`
+with your login key. That key reaches every branch of your organization, so no
+key is minted. Checking out `main` writes the file too. `checkout` needs a
+stored login (`headband login`), because the file records your login's
+organization. `--token` and `HEADBAND_API_KEY` take the place of a stored
+login, so unset them to check out.
+
+Like git, the CLI uses the nearest `.headband/project.json` in the working
+directory or a parent, up to your home directory (or the filesystem root,
+outside it). `checkout` rewrites that nearest file, or writes one in the
+working directory when there is none. As in git, a file another user owns, or
+one in a `.headband` directory another user owns, is an error: every command
+that would send `Headband-Branch` stops and names the file, and the search goes
+no further. So a file planted in a shared directory such as `/tmp` never steers
+your commands. A symlink is judged by its own owner, as in git, so another
+user's link to your `.headband` is theirs. `checkout` then writes your own file
+in the working directory, and never rewrites the other user's. When the other
+user's file is in the working directory itself, remove it before you check out
+there.
+
+A checkout never falls back to production silently. Every command that would
+send `Headband-Branch` stops with an error when the nearest
+`.headband/project.json` cannot be read, holds a value that is not a valid
+project id, branch name or branch id, or was written for another organization
+than your stored login's. Run `headband branch checkout <name>` again to rewrite
+the file, or delete it to work on production. A token (`--token`,
+`HEADBAND_API_KEY`) names no organization, so the organization check applies
+only to stored logins.
+
+For one command, `--project <id> --branch <name>` picks another branch, and
+`--branch <name>` alone takes the checkout's project. A branch id
+(`--branch br_...`) names its own project, so it is sent as it is and needs no
+`--project`. With no checkout and no `--branch`, commands reach each project's
+primary branch, as before. A branch name with no project at all is a usage
+error, so a name is never matched across projects by accident.
+
+`--project` without `--branch` is a usage error, because these commands send no
+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`.
+
 ### Keys
 
 ```bash
 headband keys list [--json]
-headband keys create <name> --type <admin|search> [--project <id>] [--json]
-headband keys revoke <id> [--yes]
+headband keys create <name> --type <admin|search> [--project <id>] [--branch <name>]
+                     [--instances <id,id>] [--permissions <a,b,...>] [--expires <30d|ISO date>] [--json]
+headband keys revoke <id> [--yes] [--json]
 ```
 
+A key belongs to one branch and reaches only that branch's indexes, for an app
+such as a preview deployment. `keys create` picks the branch in this order:
+
+1. `--branch <name>`, in the project from `--project`, else the checkout's. A
+   branch id (`--branch br_...`) needs no project.
+2. The checked-out branch, unless `--project` names another project.
+3. The primary branch of `--project`.
+
+With none of these, `--type admin` mints an org key, which reaches every branch
+of every project, and `--type search` is refused (exit `2`, code
+`branch_required`), because search keys ship in browsers. A key on the primary
+branch is a live key (`hb_adm_live_`, `hb_src_live_`); a key on any other
+branch is a test key (`hb_adm_test_`, `hb_src_test_`). `keys create` and
+`keys list` show each key's branch and environment.
+
 `keys create` is the only command that prints a raw API key. Store it when it is
-shown because Headband returns raw keys only once.
+shown: Headband returns raw keys only once.
+
+`--instances <id,id>` also limits the key to those dedicated engines. It takes
+one comma-separated list of 1 to 50 ids (from `headband instances list`);
+repeating the flag does not add engines, only the last one counts. An org key then reaches only them, on every
+branch. A branch key reaches its branch's engines among them, and every id must
+sit on that branch. Any other index answers as if it did not exist, and
+endpoints that are not about those engines refuse the key. The list is fixed:
+to change it, create a new key and revoke the old one. `keys list` and
+`keys create` show each key's engines: `all` when it is not limited, the engine
+ids when it is, `none` when its list reaches nothing, and `unknown` when the
+API did not report them (never shown as `all`).
+
+`--permissions` limits the new key to the permissions you list. You can grant
+only permissions your own key holds, and only ones that fit the key type:
+
+| Type     | Grantable permissions                                                                                                                                                                            |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `search` | `search`, `analytics.write`                                                                                                                                                                      |
+| `admin`  | `search`, `documents.read`, `documents.add`, `documents.delete`, `indexes.create`, `indexes.delete`, `settings.update`, `analytics.write`, `connectors.write`, `instances.manage`, `sync.manage` |
+
+Anything else is refused with exit `4` and the names it refused. Without
+`--permissions`, the key gets the type's defaults, cut down to what your key
+holds. `keys.manage`, `projects.manage`, `branches.manage` and
+`schema.manage` are never grantable here; only `headband login` mints them.
+
+`--expires` sets when the key stops working: a duration from now (`12h`,
+`30d`, `2w`, `1y`) or an ISO date (`2027-01-31`). It must be in the future and
+at most one year away. Without it, the key does not expire.
+
+```bash
+headband keys create ci-reader --type admin --permissions search,documents.read --expires 30d --json
+```
 
 ### Indexes
 
 ```bash
 headband indexes list [--json]
 headband indexes create <uid> [--primary-key <pk>] [--engine <engine>] [--instance <id>] [--json]
-headband indexes delete <uid> [--yes]
-headband indexes settings get <uid> [--json]
-headband indexes settings set <uid> --file <settings.json> [--json]
-headband indexes stats <uid> [--json]
+headband indexes delete <uid> [--yes] [--json]
+headband indexes settings get <uid>
+headband indexes settings set <uid> --file <settings.json>
+headband indexes stats <uid>
 ```
 
+`index` is an alias of `indexes` for every command here: `headband index list`
+and `headband index switch-engine <uid>` work the same.
+
+`settings get`, `settings set` and `stats` always print JSON.
+
+`indexes create` prints the project and branch the index went to (CLI 0.6.0).
+With the key from `headband login` and no `--project`, `--branch` or
+checkout, that is the org's Default project, main branch.
+
+Deleting an index that a `schema apply` reindex moved to `<uid>__v2` also
+removes that build's own index row, so nothing is left behind.
+
 `--instance <id>` creates the index on one of your dedicated engines (ids from
 `headband instances list`). The index takes that engine's type, so `--engine` is
 optional; if you pass it, it must match.
@@ -98,58 +362,289 @@ On the engine, the index has a longer name (`engineIndexUid`, such as
 `hbo_<org>_products`). `indexes create` and `indexes list` show it. Use that name,
 not the uid, with the engine's own client on the instance endpoint.
 
-### Engines
-
-Dedicated engines are private Meilisearch, Elasticsearch or Typesense servers for
-your organization, reachable with each engine's own client. They are rolling out
-gradually. Until your organization has access, these commands say so.
+#### Change an index's engine
 
 ```bash
-headband instances list [--json]
-headband instances create <meilisearch|elasticsearch|typesense> [--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 delete <id> [--yes]
-headband instances connect <id> [--client <node|curl>]
+headband indexes switch-engine <uid> --engine <engine> [--instance <id>] [--accept-drops] [--declare-key] [--dry-run] [--wait] [--json]
+headband indexes switch-engine <uid> --status [--json]
 ```
 
-`connect` prints the endpoint and a snippet for the engine's own client. Authenticate
-with an organization-wide key. The snippets create an index and add a document, so
-run them with an admin key (`headband keys create <name> --type admin`); a search
-key can only search.
-Project keys do not work on engine endpoints. Serverless engines are available for
-Meilisearch only for now. If a command says the key cannot manage engines, run
-`headband login` again.
+Moves the index to another engine. The
+uid, keys and URLs stay the same, and searches keep working until the switch.
+Writes are held for about a minute at the end (they answer 503 with `Retry-After`).
+
+- `--dry-run` shows how many documents would be copied, where the new index goes,
+  and which settings would not carry over. It changes nothing.
+- A setting the new engine cannot apply stops the switch with exit code 6 and a
+  list of what would not carry over, with a reason for each. `--accept-drops`
+  switches anyway.
+- `--wait` follows the switch until it ends and prints each phase. Without it the
+  command returns once the switch is queued; `--status` shows how it went.
+- `--declare-key` is for a Visor index over 1000 documents whose primary key is
+  not filterable and sortable: the key is declared while the index is read, which
+  rebuilds it.
 
 ### Documents
 
 ```bash
-headband docs push <file.json|file.jsonl> --index <uid>
-headband docs delete <docId> --index <uid>
+headband docs push <file.json|file.jsonl> --index <uid> [--json]
+headband docs export --index <uid> [--out <file>] [--format <jsonl|json>] [--batch <n>] [--json]
+headband docs delete <docId>... --index <uid> [--json]
 ```
 
-`docs push` accepts a JSON array or JSONL file and sends documents to
+`docs delete` removes one or more documents by id, in one call to
+`DELETE /v1/documents?index=<uid>`.
+
+`docs push` accepts a JSON array or a JSONL file and sends documents to
 `/v1/bulk` in batches of 1000.
 
+`docs export` walks `GET /v1/documents` by cursor and writes every document in
+the index, one page in memory at a time:
+
+```bash
+headband docs export --index products > products.jsonl
+headband docs export --index products --out products.json
+headband docs export --index products | head -5
+```
+
+- Without `--out`, documents stream to stdout and nothing else is printed
+  there. Progress for `--out` goes to stderr.
+- `--format` is `jsonl` (one document per line, the default) or `json` (one
+  array). With `--out`, a `.json` file name picks `json`.
+- `--out` writes to `<file>.partial` and renames it when the export finishes,
+  so a failed export never leaves a truncated file under the real name. If the
+  export stops on an error after some documents were written (CLI 0.6.0), they
+  stay in `<file>.partial`, as a whole JSONL file or a closed JSON array, and
+  stderr says how many. `--json` with `--out` prints a summary:
+  `{index, out, format, exported}`.
+- `--batch` is the page size. The default is 1000, or 250 for an index on
+  Typesense, which refuses larger pages. The server may answer fewer a page.
+- The cursor reaches every document on every engine: Visor past its first
+  1000 and Elasticsearch past its first 10,000. A server without cursors is
+  paged by offset, as before CLI 0.5.0.
+- A Visor index created before 2026-10-21 with more than 1000 documents may
+  not have its primary key declared filterable and sortable. The server then
+  refuses the walk (exit `2`, code `feature_not_supported`), and the CLI prints
+  the fix: `headband indexes settings get <uid> > settings.json`, add the key
+  to the lists it names, `headband indexes settings set <uid> --file
+settings.json` (Visor rebuilds the index), then export again. New Visor
+  indexes declare the key on their own.
+- Export needs an admin key with `documents.read`.
+
 ### Search
 
 ```bash
-headband search <index> <query> [--limit N] [--filter <expr>] [--json]
+headband search <index> [<query>] [--limit N] [--filter <expr>] [--mode <instant|retrieval>] [--json]
 ```
 
+Without a query, or with `""`, search browses the index (CLI 0.6.0): every
+document matches, and `--filter` and `--limit` pick what comes back.
+
+`--mode` picks Visor's ranking: `instant` (the default, typo-tolerant,
+as-you-type) or `retrieval` (BM25F, for longer queries). Indexes on the other
+engines ignore it.
+
 Plain output shows a compact table. `--json` prints the raw API response.
 
 ### Tasks
 
 ```bash
-headband tasks list [--json]
-headband tasks get <id> [--json]
+headband tasks list [--index <uid>] [--limit <n>] [--json]
+headband tasks get <id> [--index <uid>] [--json]
 ```
 
-## What gets created
+`tasks list` prints a table, or the raw response with `--json`. `tasks get`
+prints JSON.
+
+Tasks live on the engine that holds the index. The key `headband login`
+creates is org-wide, so it must name the index with `--index`. So must a key
+of a branch other than production. A project key of the production branch may
+leave it out.
+
+### Engines
+
+Dedicated engines are private Meilisearch, Elasticsearch, Typesense or Visor
+servers for your organization, reachable with each engine's own client (Visor over
+its HTTP API). They are rolling out gradually. Until your organization has access,
+these commands say so. Visor is offered in a region where a dedicated engine host
+runs it; elsewhere `instances create visor` answers `engine_not_available`.
+
+```bash
+headband instances list [--json]
+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 update <id> [--name <name>] [--lane <serverless|always_on>]
+                          [--memory <512m|1g|...>] [--idle-timeout <seconds>] [--json]
+headband instances wake <id> [--json]
+headband instances park <id> [--json]
+headband instances wakes <id> [--limit <n>] [--json]
+headband instances delete <id> [--yes] [--json]
+headband instances connect <id> [--client <node|curl>] [--json]
+```
+
+`update` changes only the settings you pass; `--size` is an alias for
+`--memory`. The engine and region cannot change. A resize applies in the
+background: `instances show` reports the state as "applying changes" until it
+is done. Always-on engines need a paid plan (exit `4` otherwise).
+
+`wakes` lists recent wake-ups, newest first: when each was requested, how it
+woke, the outcome and how long it took to be ready. `--limit` takes up to 200;
+the default is 50.
+
+`connect` prints the endpoint and a snippet for the engine's own client.
+Authenticate with an organization-wide key, a branch key of the engine's branch, or a key limited to that engine. The snippets create an index and add
+a document, so run them with an admin key (`headband keys create <name> --type
+admin`); a search key can only search. A key of another branch does not work on the engine. Serverless engines are available for Meilisearch, and for Typesense
+in early access; Elasticsearch runs always on. If a command says the key cannot
+manage engines, run `headband login` again.
+
+### Schema migrations
+
+For projects that define their indexes in `headband.config.ts` with
+`@headband/sync`. These commands read that file from the current directory:
+its default export is `defineConfig({ url, projectId?, indexes })`, and `apply`
+also needs a named `adapter` export, such as `drizzleAdapter(...)` from
+`@headband/drizzle`, in the same file. When the adapter is exported, the
+config is checked against your tables first, and every misspelled table,
+field, relation or settings attribute is listed with its index.
+`headband schema <command> --help` describes each command.
+
+```bash
+headband schema diff [--allow-destructive] [--json]
+headband schema generate [--slug <slug>] [--dir <dir>] [--allow-destructive] [--json]
+headband schema apply [--project <id>] [--allow-destructive] [--dir <dir>] [--yes] [--json]
+headband schema status [--dir <dir>] [--json]
+headband schema forget <index> [--yes] [--json]
+```
+
+- `diff` compares the config with the schema state on the server. Like
+  `git diff --exit-code`, it exits `1` when changes are pending and `0` when
+  in sync. `--json` prints `{inSync, ops}`.
+- `generate` writes a migration file for the pending changes into `--dir`
+  (default `headband/migrations`). `--json` prints `{path}`, with `null` when
+  there was nothing to generate.
+- `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
+  `{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`.
+  That file is only a local cache: commit it or ignore it.
+- `status` shows each index's applied version and any drift, including
+  `index missing` for an index deleted outside `apply`. `--json` prints
+  `{indexes, localApplied, localHead}`.
+- `forget` removes the recorded schema state of an index deleted outside
+  `apply`, so the next `generate` plans it as new. `headband indexes delete`
+  clears it for you.
+
+Schema commands need a key with `schema.manage`, which only `headband login`
+mints. That key is org-wide: new indexes go to the project named by
+`--project <id>` or the config's `projectId`, else to your org's Default
+project. Your app's own project admin key reaches only its project's indexes,
+so name that project.
+
+The URL comes from `--url`, else `HEADBAND_URL`, else the config's `url`, else
+your login's.
+
+### Sync
+
+Sync keeps search indexes in step with a Postgres database. There are two ways
+to run it.
+
+**Managed Sync** runs on Headband. You register a source database and define
+synced indexes; Headband reads the database's changes and keeps the indexes
+current.
+
+```bash
+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]
+
+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]
+```
+
+Keep connection strings out of shell history: the source URL can come from
+`HEADBAND_SYNC_DB_URL`, the owner URL from `HEADBAND_SYNC_OWNER_URL`, and a
+BataDB API key from `HEADBAND_BATADB_API_KEY` only. `sync source setup` runs
+Headband's setup SQL on your machine as the tables' owner, in one transaction;
+the owner URL never leaves your machine. Run `headband sync source --help` and
+`headband sync index --help` for the details.
+
+Managed Sync is in early access: until your organization has it, these
+commands say "Sync is not enabled for this organization yet."
+
+**Self-hosted Sync** runs a worker in your own infrastructure. Your app writes
+changes to an outbox table, and the worker pushes them to Headband. The
+`@headband/drizzle` README walks through the whole setup.
+
+```bash
+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 retry-dead-letters [--json]
+headband sync status [--json]
+```
 
-**`headband.config.ts`** -- Search configuration that reads from `NEXT_PUBLIC_HEADBAND_KEY` env var with a fallback:
+- `init` prints the outbox table's DDL; `--write` also saves it to
+  `headband/outbox.sql`, and `--apply` runs it against `DATABASE_URL` (it is
+  `CREATE TABLE IF NOT EXISTS`). `--json` prints `{ddl, path, applied}`.
+- `worker` drains the outbox. Without `--budget-ms` it loops until stopped
+  (Ctrl+C or SIGTERM finish the current batch first), so `--loop` changes
+  nothing on its own. With `--budget-ms` it stops after that long, or earlier
+  once the outbox is empty; add `--loop` to keep waiting for changes until the
+  budget ends. `--json` then prints the run report. Each batch that drained
+  rows prints one line to stderr (CLI 0.6.0). In a loop,
+  `--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
+  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.
+- `worker --scaffold docker` writes `Dockerfile.headband-sync`, which runs
+  `npx --yes @headband/cli@<version> sync worker --loop`, and prints a compose
+  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
+  `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.
+- `retry-dead-letters` requeues rows that failed too many times. `--json`
+  prints `{requeued}`.
+- `status`, beside a `headband.config.ts`, shows the outbox's pending rows,
+  dead letters and oldest pending row. Elsewhere it shows managed Sync.
+
+The worker, `retry-dead-letters`, `status` and `init --apply` read the outbox
+database URL from `DATABASE_URL`, falling back to `HEADBAND_DATABASE_URL`. The
+worker and `reconcile` need `headband.config.ts` to export an `adapter`. A
+missing outbox table is reported by name, with how to create it.
+
+## What `init` creates
+
+**`headband.config.ts`**: search configuration that reads from the
+`NEXT_PUBLIC_HEADBAND_KEY` env var with a fallback:
 
 ```typescript
 export const headbandConfig = {
@@ -164,7 +659,8 @@ by a browser component, so the CLI only accepts scoped `hb_src_` search keys.
 Keep admin keys in server-only environments for indexing, settings, and sync
 jobs.
 
-**`components/headband-search.tsx`** (or `src/components/` if your project uses a `src/` directory) -- A ready-to-use search component:
+**`components/headband-search.tsx`** (or `src/components/` if your project uses
+a `src/` directory): a ready-to-use search component:
 
 ```tsx
 "use client";