@cabane/cli 0.1.3 → 0.1.4

package/README.md

@@ -1,34 +1,68 @@
 # cabane CLI
 
-Run a self-hosted Cabane on your own machine — **no docker, no repo**. `@cabane/cli`
-is a thin public supervisor/installer (no product source): it fetches the built
-server artifact, runs the whole stack, and keeps it updated.
+Run a self-hosted [Cabane](https://cabane.ai) on your own machine. `@cabane/cli`
+installs the Cabane server, runs the whole stack — server, embedded Postgres,
+and the house bridge — and keeps it updated.
+
+Two terms you'll see throughout:
+
+- The **house bridge** is what makes your agents answer: it runs each agent
+  turn on your machine, through an executor.
+- An **executor** is a coding-agent harness installed on your machine —
+  **Claude Code**, **Codex**, or **opencode**. Cabane ships no model of its own
+  and requires no particular provider; the house bridge runs whichever executor
+  (and credentials) you have.
+
+The short version:
 
 ```sh
 npm i -g @cabane/cli                 # install the CLI (bin: `cabane`)
-cabane init                          # first-run wizard: data location, port, executor key
-cabane install --token cabdist_…     # fetch + sha256-verify + unpack the gated server artifact
-cabane up --daemon                   # supervise Postgres + server + house bridge (no flags — uses your config)
+cabane init                          # first-run wizard
+cabane install --token cabdist_…     # fetch + verify + unpack the server
+cabane up --daemon                   # run the stack
 # open http://localhost:3000, sign up
-cabane setup-agent                   # register the house bridge + put your agent on it (prompts for a cab_… token)
+cabane setup-agent                   # connect your agent to the house bridge
 ```
 
-`cabane init` is the interactive first-run wizard: it asks where your data lives
-(and **shows the resolved paths** — `data/storage` for uploads, `data/pg` for the
-database), the port, an optional public URL, and your executor credential entered
-**password-style**. It persists everything to config, so a later `cabane up` needs
-no flags. Re-run it any time to reconfigure. You can still skip it and pass flags
-directly if you prefer.
+Each step, in order, below.
+
+## Requirements
+
+- **Node ≥ 22.**
+- **An executor the house bridge can run** — Claude Code, Codex, or opencode —
+  with its credentials reachable (see [Credentials](#credentials)).
+
+## Getting started
+
+1. **Install the CLI.** `npm i -g @cabane/cli` — installs the `cabane` binary.
 
-Every secret is entered at a hidden prompt, never on the command line — the
-`cabdist_…` distribution grant (`cabane install`), the executor key (`cabane init`
-/ `cabane set-env KEY`), and the `cab_…` access token (`cabane setup-agent`) — so
-none of them land in your shell history or on screen.
+2. **Run `cabane init`** — the interactive first-run wizard. It asks where your
+   data lives (and shows the resolved paths — `data/storage` for uploads,
+   `data/pg` for the database), the port, an optional public URL, and your
+   executor credential if you use API-key billing (on a Claude subscription
+   login there's nothing to enter — see [Credentials](#credentials)). Everything
+   persists to config, so a later `cabane up` needs no flags. Re-run it any time
+   to reconfigure, or skip it and pass flags directly if you prefer.
 
-The house bridge runs whatever executor you have (Claude Code, or another
-supported harness) — see [Credentials](#credentials) for making its login
-reachable. On a Claude subscription there's nothing to do; on API-key billing,
-export or persist your key.
+3. **Run `cabane install --token cabdist_…`** — fetches the server artifact with
+   your distribution token, verifies its sha256, and unpacks it. (Have a local
+   tarball instead? `cabane install --from <artifact.tgz>` works offline.)
+
+4. **Run `cabane up --daemon`** — starts and supervises the stack: embedded
+   Postgres, the server, and the house bridge. Leave off `--daemon` to run it in
+   the foreground.
+
+5. **Sign up.** Open <http://localhost:3000> and create your account and first
+   workspace.
+
+6. **Run `cabane setup-agent`** — the step that connects your agent to your
+   executor. Mint an access token in the app (**Settings → Developer**), then
+   run `cabane setup-agent` and paste the `cab_…` token at the prompt. That
+   registers the house bridge and puts your agent on it — your agent now
+   answers in chat.
+
+For the fuller picture of what you just stood up — agents, bridges, workspaces,
+files — see the [Cabane docs](https://app.cabane.ai/docs).
 
 ## What it supervises
 
@@ -98,13 +132,13 @@ When something won't start, run `cabane doctor` **first**. It's a standalone
 preflight (no server needed — it's what you reach for precisely when things are
 broken) that checks the common self-host failure classes and prints a legible
 pass/fail/warn report, each with a one-line fix, then exits non-zero if any hard
-check fails. It's strictly local — nothing phones home. v1 checks:
+check fails. It's strictly local — nothing phones home. Checks:
 
 - **Node** ≥ the required version.
-- **Executor** — Claude Code present on PATH, and a credential reachable by the
-  house bridge (subscription login, an `ANTHROPIC_*` env/persisted key, or a
-  managed-policy that would refuse your key — named specifically). Reachability
-  only; it never calls the provider.
+- **Executor** — your executor's binary on PATH (`claude` by default), and a
+  credential reachable by the house bridge (a subscription login, or an
+  `ANTHROPIC_*` env/persisted key). Reachability only; it never calls the
+  provider.
 - **Port** free (or held by a running cabane).
 - **Embedded Postgres** — platform binaries present + data dir healthy.
 - **Storage root** — writable, and where it is.
@@ -114,14 +148,6 @@ check fails. It's strictly local — nothing phones home. v1 checks:
 - **Disk space** for the data dir.
 - **macOS Gatekeeper** — quarantine on the Postgres binaries (macOS only).
 
-## Requirements
-
-- **Node ≥ 22.**
-- **An executor the house bridge can run** — e.g. Claude Code, or another
-  supported harness — with its credentials reachable (see [Credentials](#credentials)).
-  Cabane ships no model of its own and requires no particular provider; the house
-  bridge runs whatever executor you have.
-
 ## Credentials
 
 The house bridge inherits the environment `cabane up` runs under, so your
@@ -149,7 +175,7 @@ executor's credentials reach it — no provider is special-cased:
 
 `set-env` stores generic `KEY=VALUE` pairs in `<CABANE_HOME>/config.json` and composes
 them into the bridge on every `up`, so it serves any executor's credentials (a
-proxy `ANTHROPIC_BASE_URL`, an `ANTHROPIC_AUTH_TOKEN`, a future harness's key) —
+proxy `ANTHROPIC_BASE_URL`, an `ANTHROPIC_AUTH_TOKEN`, another harness's key) —
 not just Anthropic. A bare `cabane set-env KEY` (no `=value`) prompts for the value
 without echoing, so a secret never lands on the command line. Inspect with `cabane
 set-env --list` (values masked), remove with `cabane set-env --unset KEY`. A live shell export takes precedence over a
@@ -159,7 +185,6 @@ class) always win over both. Apply a change to an already-running stack with
 
 ## Notes
 
-- **macOS Gatekeeper** on the unsigned Postgres binaries is a known open question
-  (CT453) — documented, not yet solved. If pg fails to exec on first run, clear
-  the quarantine xattr and retry.
-- **Install the _server_ artifact from a local build** with `cabane install --from <artifact.tgz>` instead of a distribution token — handy for an offline or air-gapped install.
+- **macOS Gatekeeper** may quarantine the unsigned Postgres binaries. If pg
+  fails to exec on first run, clear the quarantine xattr and retry —
+  `cabane doctor` detects this and prints the fix.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cabane/cli",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
-  "description": "The cabane CLI — install, supervise (server + embedded Postgres + house bridge), and update a self-hosted Cabane on your own machine. No docker, no repo.",
+  "description": "The cabane CLI — install, run, and update a self-hosted Cabane on your own machine (server + embedded Postgres + house bridge).",
   "license": "UNLICENSED",
   "homepage": "https://cabane.ai",
   "repository": {
@@ -13,8 +13,7 @@
   "keywords": [
     "cabane",
     "self-host",
-    "cli",
-    "supervisor"
+    "cli"
   ],
   "bin": {
     "cabane": "dist/cli.js"