@turbobase/cli 1.1.7 → 1.1.9

package/README.md

@@ -1,13 +1,17 @@
 # turbobase
 
-The `turbobase` CLI authors, tests, and deploys **TurboBase extensions** — hooks
-and conduits — against a running TurboBase instance. It talks to the instance
-over its HTTP API using a personal access token (PAT); it is **not** a way to
-stand up TurboBase yourself (instances are provisioned and operated as a managed
-service — see [console.turbobase.io](https://console.turbobase.io/)).
+The command-line interface to your [TurboBase](https://turbobase.io/) instance.
 
-Every subcommand wraps the same library functions the in-product authoring MCP
-server uses, so the CLI and the Claude Code surface never drift.
+Build and ship the apps your team uses, author the extensions that run inside
+your instance, promote a reviewed configuration from sandbox to production, and
+give an AI coding agent the context it needs to work against your live data
+model — all from one binary, over your instance's HTTP API.
+
+**Full documentation: [docs.turbobase.io](https://docs.turbobase.io/)**
+
+TurboBase is a managed service: your instance is provisioned and operated for
+you at [console.turbobase.io](https://console.turbobase.io/). This CLI drives an
+instance you already have — it is not a way to run the platform yourself.
 
 ## Install
 
@@ -15,105 +19,261 @@ server uses, so the CLI and the Claude Code surface never drift.
 curl -fsSL https://console.turbobase.io/install-cli.sh | bash
 ```
 
-On Windows: `powershell -c "irm https://console.turbobase.io/install-cli.ps1 | iex"`.
+On Windows:
+
+```powershell
+powershell -c "irm https://console.turbobase.io/install-cli.ps1 | iex"
+```
 
 The installer verifies the download's checksum, installs into `~/.turbobase`,
-and puts `turbobase` on your PATH — no sudo, no package manager. It also fetches
-a private Node.js if the machine has none at v22 or newer.
+and puts `turbobase` on your PATH — no sudo, no package manager. If the machine
+has no suitable Node.js it fetches a private one rather than touching your
+system install.
 
-This npm package is the same CLI for anyone who would rather manage it alongside
-their other global tools:
+This npm package is the same CLI, for anyone who would rather manage it
+alongside their other global tools:
 
 ```sh
 npm install -g @turbobase/cli
 turbobase --version
 ```
 
-`turbobase ext test` and `turbobase ext replay` need two native packages that the
-one-line install leaves out; `turbobase ext extras install` fetches them on demand
-(an npm install already has them as dependencies).
+Requires **Node 22, or 24 and newer**.
 
-## Authenticate
+## Sign in
 
-Mint a PAT in your TurboBase app under **Settings › Access tokens**, then paste
-it. This is the only sign-in path — there is no browser flow today.
+Mint a personal access token in your TurboBase app under **Settings › Access
+tokens**, then hand it to the CLI. This is the only sign-in path.
 
 ```sh
 turbobase auth login --base-url https://acme.turbobase.app --token tb_pat_xxxxxxxx
 ```
 
-**The instance you last signed in to becomes the ACTIVE default** — every
-command uses it when you don't pass `--base-url`, so you never repeat the flag
-for the instance you're working on. `--base-url` is only needed to reach a
-*different* stored instance. On login the CLI probes the instance and warns if
-the base URL doesn't serve the `/v1` API (the local-dev trap of pointing at the
-app dev-server port instead of the instance API) or if the token is rejected —
-pass `--no-verify` to skip the probe.
+The instance you last signed in to becomes the **active default**, so you never
+repeat `--base-url` for the instance you're working on — pass it only to reach a
+*different* stored instance. One machine can hold credentials for many
+instances.
 
 ```sh
-turbobase auth status                 # active instance (*) + every stored sign-in
-turbobase auth use https://beta.turbobase.app   # switch the active default (no PAT re-paste)
-turbobase auth logout                 # remove the active sign-in (--base-url <url> / --all)
+turbobase auth status                           # the active instance (*) and every stored sign-in
+turbobase auth use https://beta.turbobase.app   # switch the default, no token re-paste
+turbobase auth logout                           # drop a sign-in (--base-url <url> / --all)
 ```
 
-Credentials are stored in `~/.turbobase/credentials` (0600) as
-`{ active, tenants: { "<base-url>": { token } } }`. Override the directory with
-`TURBOBASE_HOME`.
+Credentials live in `~/.turbobase/credentials`, written `0600`. Point
+`TURBOBASE_HOME` elsewhere to relocate them. On login the CLI checks that the
+URL really serves the instance API and that the token is accepted, and warns
+loudly if not; `--no-verify` skips the probe.
+
+→ [Access tokens](https://docs.turbobase.io/tenant/access-tokens/)
+
+## What you can do
+
+Eight groups. Run `turbobase --help` for the list, `turbobase <group> --help` to
+go deeper.
+
+| Group | What it does |
+| --- | --- |
+| `auth` | Sign in, switch the active instance, manage stored credentials. |
+| `apps` | Build, preview, and ship hosted apps served inside your TurboBase app. |
+| `ext` | Author, test, deploy, and observe extensions — hooks and conduits — plus the marketplace. |
+| `project` | Scaffold a project and generate the files an AI agent session reads. |
+| `release` | Ship your project from your own CI — deploy, status, rollback, list. |
+| `sandbox` | Ephemeral local sandboxes seeded from a redacted slice of an instance (`create` not available yet). |
+| `kb` | Write findings into your instance's knowledge base. |
+| `mcp` | Run the local authoring MCP server that Claude Code talks to. |
 
-## Author → test → deploy
+## Ship a hosted app
+
+Hosted apps are served from your instance at `/a/<slug>`, so anyone who can open
+your TurboBase app can open them — no separate hosting, no separate login.
+
+Because the app is served same-origin, it inherits your instance's auth: no
+sign-in page to build, no callback, no CORS, no app-owned keys. Visitors who
+aren't signed in are redirected before your bundle loads, and every read runs
+under that user's row-level security.
 
 ```sh
-turbobase project types                          # generate types.ts from the instance catalog
+turbobase apps init reorder-desk ./app      # scaffold locally (Vite + React + TS)
+turbobase apps create reorder-desk          # register the app on your instance
+turbobase apps push reorder-desk ./app      # record the source — no build, nothing goes live
+turbobase apps deploy reorder-desk ./app    # build and cut a new live version
+turbobase apps list
+```
+
+`create` is required before the first deploy — or pass `deploy --create` to fold
+it in. `init` is local-only and touches nothing on the instance. The build runs
+**on your machine**; TurboBase serves the result.
+
+`push` and `deploy` are deliberately separate: `push` records the source on the
+instance so the app can be pulled and refined from another machine (or by a
+coding agent) with `turbobase apps pull`, while `deploy` is what actually goes
+live. Push freely, deploy when ready.
+
+Ship it for review before it goes live. `apps deploy --preview` builds and
+serves the result at its own URL and leaves `/a/<slug>` untouched; promoting
+re-points the app at **the exact bytes that were reviewed**, with no rebuild:
+
+```sh
+turbobase apps deploy reorder-desk ./app --preview
+turbobase apps preview list reorder-desk
+turbobase apps promote reorder-desk <preview-id>
+```
+
+Preview links stop resolving after 7 days; the build stays in deploy history and
+can still be promoted. Set the app's display name and description in
+`turbobase.json` — the manifest is applied on every deploy. The slug is fixed
+once created: it is the URL, and nothing redirects the old one.
+
+→ [Build apps on TurboBase](https://docs.turbobase.io/build-apps/)
+
+## Author and deploy extensions
+
+Extensions run inside your instance. **Hooks** fire on record changes;
+**conduits** move data between a source and your mirror.
+
+```sh
+turbobase project types                                   # types.ts from your live catalog
 turbobase ext new hook --record salesOrder --field memo
-turbobase project samples                   # fixtures from the live catalog
-turbobase ext test hooks/<file>.ts           # dry-run in the production-parity sandbox
-turbobase ext deploy hooks/<file>.ts         # POST /v1/extensions (lands active)
-turbobase ext logs <id>                      # tail the deployed extension's logs
+turbobase project samples                                 # fixtures from the live catalog
+turbobase ext lint hooks/<file>.ts                        # catch semantic foot-guns
+turbobase ext test hooks/<file>.ts                        # run it in a production-parity sandbox
+turbobase ext deploy hooks/<file>.ts                      # ship it
+turbobase ext logs <id> --follow                          # watch it run
+```
+
+→ [Writing hooks](https://docs.turbobase.io/extending/writing-hooks/) ·
+[Writing conduits](https://docs.turbobase.io/extending/writing-conduits/) ·
+[Sandboxes and testing](https://docs.turbobase.io/extending/sandboxes-and-testing/)
+
+## Promote a configuration between environments
+
+Your instance's extension configuration can be snapshotted to a file, reviewed
+as code, diffed against a target, and promoted:
+
+```sh
+turbobase ext export                        # snapshot the live instance to turbobase/bundle.json
+turbobase ext plan --to prod                # diff the local bundle against prod — no writes
+turbobase ext deploy --to prod              # apply the whole bundle
+turbobase ext promote --from sandbox --to prod --confirm acme
 ```
 
-The surface is seven groups: `auth` (sign-in + the credential store), `project`
-(scaffold, types, grounding, adopt), `ext` (author → verify → ship → observe,
-plus the marketplace), `apps` (hosted apps), `kb` (knowledge-base writes),
-`sandbox` (ephemeral local instances), and `mcp` (the authoring server).
+`promote` is fail-closed: you type the exact target instance slug to confirm, or
+nothing happens.
+
+→ [Deploy, plan, promote](https://docs.turbobase.io/extending/deploy-plan-promote/)
+
+## Work with an AI agent
+
+`turbobase project init` scaffolds a project Claude Code can drive — an
+authoring guide, a `.mcp.json` pointing your editor at your instance's MCP
+servers, skills, and a session hook that keeps generated types fresh.
+
+```sh
+turbobase project init
+turbobase project types           # types.ts from the live catalog
+turbobase project grounding       # INSTANCE.md — source primer, record anatomy, KB retrieval
+turbobase project adopt           # what changed in the platform that this project must act on
+```
+
+`grounding` writes the same brief the in-product AI surfaces use, so your editor
+answers questions about your data the way your instance does. `adopt` asks the
+instance what changed in the releases since you last adopted, and leaves the
+file alone when there's nothing new.
+
+The scaffolded `.mcp.json` wires two servers on your instance: an **authoring**
+server (scaffold, generate types, dry-run, deploy, tail logs — the same library
+functions the subcommands call) and a **data** server (catalog, record anatomy,
+knowledge base, RLS-scoped reads). `turbobase mcp` is a separate local stdio
+server, for clients you'd rather point at a process than a URL.
+
+> **`.mcp.json` holds a live access token.** The scaffold writes it `0600` and
+> adds it to `.gitignore`. Keep it out of version control, and rotate the token
+> if it was ever pushed.
+
+→ [Connect Claude Code](https://docs.turbobase.io/build-apps/claude-code/)
+
+## Marketplace
+
+```sh
+turbobase ext install acme-recipes
+turbobase ext publish hooks/<file>.ts --name acme-recipes --pkg-version 1.0.0
+```
+
+Both need a registry credential — set `TURBOBASE_REGISTRY_URL` and
+`TURBOBASE_REGISTRY_TOKEN` from the token TurboBase support issues you. It is
+separate from your instance's access token and is revocable on its own.
+Publishing requires a publisher allowlist.
+
+→ [Marketplace](https://docs.turbobase.io/extending/marketplace/)
+
+## In CI
+
+`turbobase project ci` scaffolds a ready-made GitHub Action that signs in with a
+`releases:write` token from your secrets and ships the checkout:
+
+```sh
+turbobase project ci     # writes .github/workflows/turbobase-release-deploy.yml
+```
+
+It runs in **your** repo on **your** runner and uploads your checkout's bytes —
+TurboBase clones nothing and holds no GitHub App key. The CLI is the equal front
+door if you'd rather drive it yourself:
+
+```sh
+turbobase release deploy --target auto --project . --ref HEAD --follow
+turbobase release list
+turbobase release rollback <id>
+```
+
+`ext lint`, `ext test`, and `ext replay` take `--reporter junit|json`, so
+results land in your CI's test report:
+
+```sh
+turbobase ext lint hooks/ --reporter junit
+turbobase ext test hooks/<file>.ts --reporter junit --ci
+```
 
-Run `turbobase --help` for the groups, `turbobase <group> --help` for what is in
-one.
+These commands need no instance and run fully offline: `ext new`, `ext lint`,
+`ext test`, `ext replay --fixture`, `project init`, and `project ci`. Everything
+else resolves an instance and token from your credential store, and says so
+plainly when you aren't signed in. Sign in non-interactively with
+`turbobase auth login --base-url … --token "$TURBOBASE_PAT"` from a secret.
 
-## Output & interactivity
+`ext test` and `ext replay` execute your extension in a real sandbox, which
+needs two native packages. An `npm install -g` already has them; with the
+one-line installer, fetch them once with `turbobase ext extras install`
+(`turbobase ext extras status` reports what you have).
 
-On an interactive terminal the CLI renders colour, a spinner for long-running
-calls, a live stage + percent bar for `--follow` jobs, aligned tables (`auth status`,
-`apps list`, `ext binding`), and boxed result cards. When a command needs an
-instance and several are stored with no active default, it arrow-picks one
-instead of erroring.
+## Output
 
-Colour + animation are **chrome on stderr**; command results — ids, tables, JSON,
-`--reporter` output, streamed job logs — stay on **stdout**, so pipes and
-captured output are never disturbed. Colour is off automatically when stdout
-isn't a TTY, and can be forced off with `--no-color` (before the command) or
-`NO_COLOR=1`. `--json` / `--reporter` output is always plain.
+Colour, spinners, and progress bars are **chrome, written to stderr**. Command
+results — ids, tables, JSON, `--reporter` output, streamed logs — go to
+**stdout**, so pipes and captured output are never disturbed. Colour turns
+itself off when stdout isn't a terminal, and can be forced off with `--no-color`
+or `NO_COLOR=1`.
 
-## Offline commands (no instance required)
+## Versioning
 
-`ext lint`, `ext test`, `ext replay --fixture`, `ext new`, `project init` and
-`project ci` run fully offline.
-The rest resolve an instance + PAT from your credential store and fail with a
-clear message when you're not signed in.
+This package's version is the TurboBase release it shipped with, so
+`turbobase --version` tells you which platform release the CLI was built and
+tested against. A version reaches the `latest` tag only after that release is
+live in production.
 
-`turbobase mcp` (the local authoring server that `turbobase project init` wires
-into `.mcp.json`) runs from a published install — no source checkout needed.
+→ [Releases and adopt notes](https://docs.turbobase.io/releases/)
 
-## Version
+## Documentation
 
-This CLI is versioned independently of the instance runtime. It targets the
-instance HTTP API and is forward/backward tolerant across platform releases.
+- [Getting started](https://docs.turbobase.io/getting-started/what-is-turbobase/) — what TurboBase is, and the path to a live instance
+- [CLI overview](https://docs.turbobase.io/cli/overview/) — installing, signing in, and the shape of the tool
+- [CLI reference](https://docs.turbobase.io/cli/reference/) — every command, its flags, and an example
+- [Build apps on TurboBase](https://docs.turbobase.io/build-apps/) — building against your instance
+- [Extending TurboBase](https://docs.turbobase.io/extending/writing-hooks/) — hooks, conduits, sandboxes, promotion
 
-Node 22 or newer. `turbobase ext test` and `turbobase ext replay` load a native
-`isolated-vm` binary, and prebuilt binaries exist only for current Node
-releases — on older ones every install would fall back to compiling it.
+Questions the docs don't answer: [support@turbobase.io](mailto:support@turbobase.io).
 
 ## Licence
 
-Proprietary — see `LICENSE`. You may install and run it to author, test, and
-deploy extensions to instances you are authorised to access, including on your
-own CI runners. Redistribution and reverse engineering are not permitted.
+Proprietary — see `LICENSE`. You may install and run it to build, test, and
+deploy against instances you are authorised to access, including on your own CI
+runners. Redistribution and reverse engineering are not permitted.