@headband/cli 0.1.0 → 0.2.0

package/README.md

@@ -1,17 +1,40 @@
 # @headband/cli
 
-Interactive CLI for setting up [Headband](https://headband.dev) search in any project.
+Command-line tools for [Headband](https://headband.dev): project setup, device login,
+API key management, index operations, document pushes, search, and task inspection.
 
 ## Usage
 
 ```bash
+npx @headband/cli --help
 npx @headband/cli init
+npx @headband/cli login
+```
+
+Global flags:
+
+```bash
+--url <url>    Select a Headband profile URL
+--json         Print JSON for supported list/get commands
+--yes          Skip confirmation prompts
+--help         Show help
+```
+
+Credentials are stored in `~/.config/headband/credentials.json` or
+`$XDG_CONFIG_HOME/headband/credentials.json` with file mode `0600`.
+
+## Commands
+
+### Setup
+
+```bash
+headband init [--yes]
 ```
 
 This will:
 
 1. Ask for your Headband URL (default: `https://headband.dev`)
-2. Ask for your search API key (`hb_src_...` or `hb_adm_...`)
+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`
@@ -25,6 +48,105 @@ npx @headband/cli init --yes   # Skip prompts, use defaults
 npx @headband/cli --help       # Show help
 ```
 
+### Auth
+
+```bash
+headband login [--url <url>]
+headband logout [--url <url>] [--yes]
+headband whoami [--url <url>] [--json]
+```
+
+`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.
+
+### Projects
+
+```bash
+headband projects list [--json]
+headband projects create <name> --engine <meilisearch|typesense|elasticsearch>
+```
+
+### Keys
+
+```bash
+headband keys list [--json]
+headband keys create <name> --type <admin|search> [--project <id>] [--json]
+headband keys revoke <id> [--yes]
+```
+
+`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.
+
+### 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]
+```
+
+`--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.
+
+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.
+
+```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>]
+```
+
+`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.
+
+### Documents
+
+```bash
+headband docs push <file.json|file.jsonl> --index <uid>
+headband docs delete <docId> --index <uid>
+```
+
+`docs push` accepts a JSON array or JSONL file and sends documents to
+`/v1/bulk` in batches of 1000.
+
+### Search
+
+```bash
+headband search <index> <query> [--limit N] [--filter <expr>] [--json]
+```
+
+Plain output shows a compact table. `--json` prints the raw API response.
+
+### Tasks
+
+```bash
+headband tasks list [--json]
+headband tasks get <id> [--json]
+```
+
 ## What gets created
 
 **`headband.config.ts`** -- Search configuration that reads from `NEXT_PUBLIC_HEADBAND_KEY` env var with a fallback:
@@ -37,18 +159,17 @@ export const headbandConfig = {
 };
 ```
 
+Do not paste an `hb_adm_` admin key into this flow. The generated config is used
+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:
 
 ```tsx
 "use client";
 
-import {
-  headband,
-  HeadbandProvider,
-  SearchBox,
-  Hits,
-  Stats,
-} from "@headband/react";
+import { headband, HeadbandProvider, SearchBox, Hits, Stats } from "@headband/react";
 import { headbandConfig } from "../headband.config";
 
 const client = headband(headbandConfig.url, headbandConfig.searchKey);