layerbase 0.4.2 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +186 -45
  2. package/dist/cli.js +310 -46
  3. package/dist/cli.js.map +1 -1
  4. package/dist/commands/agent-init.js +112 -0
  5. package/dist/commands/agent-init.js.map +1 -0
  6. package/dist/commands/cloud-branch.js +97 -0
  7. package/dist/commands/cloud-branch.js.map +1 -0
  8. package/dist/commands/cloud-write.js +133 -0
  9. package/dist/commands/cloud-write.js.map +1 -0
  10. package/dist/commands/connection-string.js +17 -16
  11. package/dist/commands/connection-string.js.map +1 -1
  12. package/dist/commands/import.js +96 -0
  13. package/dist/commands/import.js.map +1 -0
  14. package/dist/commands/interactive.js +2 -0
  15. package/dist/commands/interactive.js.map +1 -1
  16. package/dist/commands/key-login.js +48 -0
  17. package/dist/commands/key-login.js.map +1 -0
  18. package/dist/commands/ls.js +17 -5
  19. package/dist/commands/ls.js.map +1 -1
  20. package/dist/commands/migrate.js +331 -0
  21. package/dist/commands/migrate.js.map +1 -0
  22. package/dist/commands/whoami-run.js +87 -0
  23. package/dist/commands/whoami-run.js.map +1 -0
  24. package/dist/commands/whoami.js +1 -1
  25. package/dist/commands/whoami.js.map +1 -1
  26. package/dist/lib/cli-output.js +28 -0
  27. package/dist/lib/cli-output.js.map +1 -0
  28. package/dist/lib/cloud-api.js +338 -20
  29. package/dist/lib/cloud-api.js.map +1 -1
  30. package/dist/lib/commands.js +90 -18
  31. package/dist/lib/commands.js.map +1 -1
  32. package/dist/lib/config.js +18 -0
  33. package/dist/lib/config.js.map +1 -1
  34. package/dist/lib/confirm.js +17 -0
  35. package/dist/lib/confirm.js.map +1 -0
  36. package/dist/lib/duration.js +33 -0
  37. package/dist/lib/duration.js.map +1 -0
  38. package/dist/lib/migration-catalog.js +209 -0
  39. package/dist/lib/migration-catalog.js.map +1 -0
  40. package/dist/lib/redact.js +23 -0
  41. package/dist/lib/redact.js.map +1 -0
  42. package/dist/lib/select.js +48 -0
  43. package/dist/lib/select.js.map +1 -0
  44. package/dist/lib/version.js +26 -0
  45. package/dist/lib/version.js.map +1 -0
  46. package/dist/ui/app.js +1 -1
  47. package/dist/ui/app.js.map +1 -1
  48. package/package.json +6 -3
  49. package/skills/layerbase/SKILL.md +222 -0
package/README.md CHANGED
@@ -3,13 +3,16 @@
3
3
  [![npm version](https://img.shields.io/npm/v/layerbase.svg)](https://www.npmjs.com/package/layerbase)
4
4
  [![license](https://img.shields.io/npm/l/layerbase.svg)](https://www.npmjs.com/package/layerbase)
5
5
 
6
- The Layerbase cloud CLI: connect to your managed cloud databases with their
7
- native clients, drop into local [spindb](https://github.com/robertjbass/spindb),
8
- and never paste a connection string into your shell history.
6
+ The Layerbase CLI is **local-first**: it is a drop-in for
7
+ [spindb](https://github.com/robertjbass/spindb) for local database work, plus a
8
+ `cloud` layer for your managed **Layerbase cloud** account. Connect with native
9
+ clients, drop into spindb, and never paste a connection string into your shell
10
+ history.
9
11
 
10
- `layerbase` is the bridge between **spindb** (the open-source local database
11
- manager) and your **Layerbase cloud** account. Think `flyctl` / `heroku` /
12
- `neonctl`, but it also wraps spindb for local work.
12
+ **The bare command namespace belongs to spindb.** Any command that is not one of
13
+ layerbase's own verbs forwards straight to your local spindb install, verbatim,
14
+ so `lbase create / ls / start / backup / branch ...` behave exactly like
15
+ `spindb <same>`. Cloud database commands live under `lbase cloud <verb>`.
13
16
 
14
17
  ## Install
15
18
 
@@ -27,53 +30,176 @@ This installs two commands, `layerbase` and a shorter `lbase`. For a two-letter
27
30
  ## Quick start
28
31
 
29
32
  ```bash
30
- layerbase # open the interactive menu
31
- layerbase login # sign in through your browser
32
- layerbase ls # list your cloud databases
33
- layerbase psql my-db # connect with the right client, no password typed
33
+ lbase # spindb's interactive menu (local databases)
34
+ lbase create my-db --engine postgres # any spindb command, verbatim
35
+ lbase login # sign in through your browser
36
+ lbase cloud ls # list your cloud databases
37
+ lbase psql my-cloud-db # connect with the right client, no password typed
34
38
  ```
35
39
 
36
- ## Commands
40
+ ## Local databases (drop-in for spindb)
41
+
42
+ Every spindb command works. Anything that is not a layerbase verb (see the
43
+ [cloud commands](#cloud-account) below) forwards straight to your local
44
+ [spindb](https://github.com/robertjbass/spindb) install, with every flag and the
45
+ exit code preserved:
46
+
47
+ ```bash
48
+ lbase create my-db --engine postgres # == spindb create my-db --engine postgres
49
+ lbase ls # == spindb list
50
+ lbase start my-db # == spindb start my-db
51
+ lbase backup my-db # == spindb backup my-db
52
+ lbase branch my-db feature-x # == spindb branch my-db feature-x
53
+ lbase <cmd> --help # == spindb <cmd> --help
54
+ ```
55
+
56
+ Bare `lbase` with no arguments opens spindb's own interactive menu. If spindb
57
+ does not recognize a command either, spindb's own error is shown and the exit
58
+ code is nonzero. `lbase spindb [args...]` is an explicit form of the same
59
+ passthrough.
60
+
61
+ ## Cloud account
62
+
63
+ These are the only verbs layerbase owns; everything else is spindb.
37
64
 
38
65
  | Command | Description |
39
66
  | --- | --- |
40
- | `layerbase` | Interactive menu: a hub to sign in, list, connect, and run spindb. |
41
- | `layerbase login` | Sign in via the browser; stores a token in `~/.layerbase-cli`. |
42
- | `layerbase logout` | Remove the stored credentials. |
43
- | `layerbase whoami` | Show the signed-in account and token expiry (`--json`). |
44
- | `layerbase ls` | List your cloud databases (`--json` for scripting). |
45
- | `layerbase connect <db>` | Connect with the engine's native client. |
46
- | `layerbase psql <db>` | Connect to a Postgres-family database. |
47
- | `layerbase redis-cli <db>` | Connect to a Redis / Valkey database. |
48
- | `layerbase mysql <db>` | Connect to a MySQL / MariaDB database. |
49
- | `layerbase connection-string <db>` | Print the connection string (reveals the password). |
50
- | `layerbase spindb [args...]` | Run the local spindb CLI (passes args through). |
51
- | `layerbase alias` | Set up the short `lb` command (only if it is free). |
52
-
53
- `<db>` accepts a cloud database id or its name. Add `--print` to `connect` to
54
- show the connection details instead of launching a client.
55
-
56
- ## Interactive menu
57
-
58
- Run `layerbase` with no command for an arrow-key menu. It is a small hub: each
59
- action runs, then the menu returns, so you can sign in, list databases, drop
60
- into spindb, and keep going.
67
+ | `lbase login` | Sign in via the browser; stores a token in `~/.layerbase-cli`. |
68
+ | `lbase login --api-key <key>` | Save a personal `sk_` API key for headless use (no browser). |
69
+ | `lbase logout` | Remove the stored credentials. |
70
+ | `lbase whoami` | Show the signed-in account (and API-key usage in key mode) (`--json`). |
71
+ | `lbase cloud ls` | List your cloud databases (`--json` for scripting). |
72
+ | `lbase cloud create <name> --engine <e> [--ttl 2h]` | Provision a database (`--ttl` makes it transient). |
73
+ | `lbase cloud delete <db> --yes` | Delete a database (`--yes`/`-y` to skip the prompt). |
74
+ | `lbase cloud start <db>` / `stop <db>` | Start or stop a database. |
75
+ | `lbase cloud branch <db> <name>` | Create or reuse a branch (idempotent). |
76
+ | `lbase cloud branch reset <db> <name>` | Re-fork a branch from its parent. |
77
+ | `lbase cloud branch delete <db> <name>` | Delete a branch. |
78
+ | `lbase cloud branch ls <db>` | List a database's branches (`--json`). |
79
+ | `lbase cloud connect <db>` | Connect with the engine's native client. |
80
+ | `lbase cloud clone <db> [name]` | Clone a cloud database into a local spindb container. |
81
+ | `lbase cloud connection-string <db>` | Print the connection string (reveals the password; alias: `url`; `--json`). |
82
+ | `lbase psql <db>` | Connect to a cloud Postgres-family database. |
83
+ | `lbase redis-cli <db>` | Connect to a cloud Redis / Valkey database. |
84
+ | `lbase mysql <db>` | Connect to a cloud MySQL / MariaDB database. |
85
+ | `lbase migrate --source <id> --target <db>` | Migrate an external database into a cloud database. |
86
+ | `lbase import <dumpfile> --target <db>` | Import a dump file into a cloud database. |
87
+ | `lbase agent init [--global]` | Install the Layerbase skill for AI coding agents. |
88
+ | `lbase alias` | Set up the short `lb` command (only if it is free). |
89
+ | `lbase chat` | Interactive console for your Layerbase account. |
90
+
91
+ `<db>` accepts a cloud database id or its name. Add `--print` to
92
+ `cloud connect` to show the connection details instead of launching a client.
93
+ `lbase cloud` with no subcommand prints the cloud help. Cloud mutation commands
94
+ (`create`, `delete`, `start`, `stop`, `branch`) run against the cloud API and
95
+ need an API key (see [Headless auth](#headless-auth-ci-and-agents)); every one
96
+ supports `--json` and returns a meaningful exit code.
97
+
98
+ ## Migrations and imports
99
+
100
+ `lbase migrate` imports an external database **into an existing cloud database**,
101
+ and `lbase import` restores a whole-database dump file. Both are headless (need
102
+ an API key), support `--json`, and never write credentials to stdout, stderr, or
103
+ JSON output. Run `lbase migrate --help` for the full per-source flag list.
104
+
105
+ ```bash
106
+ # Connection-string sources (paste one URL):
107
+ lbase migrate --source postgres --target my-db \
108
+ --connection-string "postgresql://user:pass@host:5432/db" --yes
61
109
 
110
+ # API-key sources (we discover the account, then you pick a database):
111
+ lbase migrate --source neon --target my-db --source-key napi_... --yes
112
+ lbase migrate --source algolia --target my-search --source-key <admin-key> --app-id <app-id> --yes
113
+ lbase migrate --source turso --target my-libsql --source-key <token> --url libsql://... --yes
114
+
115
+ # Whole-database dump import:
116
+ lbase import ./backup.dump --target my-db --yes
62
117
  ```
63
- ◆ Layerbase cloud + local databases
64
118
 
65
- Signed in as you@example.com
119
+ Sources: `neon`, `supabase`, `render`, `railway`, `postgres`, `mysql`,
120
+ `mariadb`, `planetscale`, `upstash`, `vercel-kv`, `redis`, `valkey`, `algolia`
121
+ (to Meilisearch), `turso` (to libSQL). Connection-string sources
122
+ (`postgres`/`mysql`/`mariadb`/`redis`/`valkey`/`vercel-kv`) take
123
+ `--connection-string` (alias `--url`). API-key sources take `--source-key` (alias
124
+ `--token`) plus, where needed, `--source-id` (aliases `--app-id`, `--email`,
125
+ `--token-id`, `--url` for a Turso database URL) and `--source-secret` (alias
126
+ `--db-password`, Supabase only). When multiple source databases are discovered,
127
+ pick one with `--source-db <label-or-number>` (or interactively on a TTY).
128
+
129
+ `--json` on `migrate` prints **one** final result object (no interim progress
130
+ lines): `{ ok, runId, status, databaseId, report }` on success or
131
+ `{ ok: false, runId, status, error }` on failure; without `--json`, status and
132
+ progress stream while the migration run polls. `--yes` (`-y`) confirms
133
+ non-interactively; a migration or import may overwrite the target's data, so a
134
+ non-TTY run without `--yes` refuses and exits `1`.
135
+
136
+ ## Headless auth (CI and agents)
137
+
138
+ For CI pipelines and coding agents, authenticate with a personal API key instead
139
+ of the browser flow. Create one in the dashboard at
140
+ `https://layerbase.com/cloud/settings`, then either export it or save it:
66
141
 
67
- ❯ List cloud databases
68
- Connect to a database
69
- Run spindb local databases
70
- Log out
71
- Quit
142
+ ```bash
143
+ export LAYERBASE_API_KEY=sk_... # env var: no login step needed at all
144
+ # or
145
+ lbase login --api-key sk_... # persists it to ~/.layerbase-cli (0600)
146
+ # or, per-invocation
147
+ lbase cloud ls --api-key sk_... --json
148
+ ```
72
149
 
73
- Up/Down to move · Enter to select · q to quit
150
+ Precedence is `--api-key` flag > `LAYERBASE_API_KEY` env > stored key. When a key
151
+ is in play, cloud calls go **directly** to the cloud API (the browser-JWT proxy
152
+ is skipped). Note: a key is tied to one account and works against your primary
153
+ control plane.
154
+
155
+ A transient database auto-deletes at its TTL, so a crashed CI run cannot strand
156
+ a database against your quota. Where the engine supports branching, a
157
+ branch-per-run (branch from a seeded parent, `reset` between runs, `delete` on
158
+ teardown) is the cheaper CI primitive.
159
+
160
+ ```yaml
161
+ # .github/workflows/test.yml (excerpt)
162
+ env:
163
+ LAYERBASE_API_KEY: ${{ secrets.LAYERBASE_API_KEY }}
164
+ steps:
165
+ - run: npm i -g layerbase
166
+ - run: |
167
+ DB=$(lbase cloud create "ci-$GITHUB_RUN_ID" --engine postgresql --ttl 2h --json)
168
+ echo "DATABASE_URL=$(echo "$DB" | jq -r .connectionString)" >> "$GITHUB_ENV"
169
+ - run: npm test
170
+ - if: always()
171
+ run: lbase cloud delete "ci-$GITHUB_RUN_ID" --yes || true
74
172
  ```
75
173
 
76
- The menu is sugar over the commands above, so everything stays scriptable.
174
+ Exit codes for scripting: `0` success, `1` usage/generic, `3` auth (invalid or
175
+ revoked key), `4` account paused, `5` capacity, `6` quota or rate limit.
176
+
177
+ ## Agents
178
+
179
+ `lbase agent init` installs the Layerbase skill so a coding agent (Claude Code,
180
+ etc.) knows how to use Layerbase. It writes `./.claude/skills/layerbase/SKILL.md`
181
+ (or `~/.claude/skills/layerbase/SKILL.md` with `--global`), fetching the latest
182
+ skill from `https://layerbase.com/skill.md` and falling back to the bundled copy
183
+ offline. It then prints an `AGENTS.md` snippet for Codex and other agents.
184
+
185
+ **Rule of thumb: bare = spindb, cloud = `lbase cloud <verb>`.** So `lbase ls`
186
+ lists your **local** containers (spindb) and `lbase cloud ls` lists your
187
+ **cloud** databases; likewise `lbase url` / `lbase connect` are local while
188
+ `lbase cloud connection-string` / `lbase cloud connect` are cloud.
189
+
190
+ ### Help and version
191
+
192
+ `lbase --help` / `-h` and `lbase help` render this unified help. `lbase --version`
193
+ / `-v` print the layerbase version. Because everything else forwards to spindb,
194
+ `lbase version` (no dashes) forwards to **spindb's** `version` command, and
195
+ `lbase <cmd> --help` reaches spindb's help for that command.
196
+
197
+ ## The chat console
198
+
199
+ `lbase chat` opens an interactive console for your Layerbase account (a
200
+ Claude-Code-style prompt). Type `/help` to see commands, `/spindb` (or `/menu`)
201
+ to hand off to local spindb, `/quit` to exit. Inside the console, `/ls`,
202
+ `/connect`, and `/clone` mean the **cloud** commands (it is the cloud console).
77
203
 
78
204
  ## The spindb bridge
79
205
 
@@ -101,7 +227,7 @@ deleted on exit. The password is never an argv value.
101
227
  | Postgres family | `PGPASSFILE` (temp `0600` file), deleted on exit |
102
228
  | MySQL / MariaDB | `--defaults-extra-file` (temp `0600` file), deleted on exit |
103
229
  | Redis / Valkey | `REDISCLI_AUTH` environment variable |
104
- | Other engines | `layerbase connection-string` / `--print` |
230
+ | Other engines | `layerbase cloud connection-string` / `--print` |
105
231
 
106
232
  Connecting requires the engine's native client (`psql`, `mysql`, `redis-cli`)
107
233
  on your `PATH`.
@@ -115,6 +241,9 @@ delivered to a loopback address. It is stored at
115
241
  `~/.layerbase-cli/credentials.json` (mode `0600`). This mirrors how the
116
242
  Layerbase desktop app signs in. Run `layerbase logout` to remove it.
117
243
 
244
+ For non-interactive use (CI, agents), skip the browser entirely with an API key:
245
+ see [Headless auth](#headless-auth-ci-and-agents).
246
+
118
247
  ## The `lb` shortcut
119
248
 
120
249
  The CLI installs as `layerbase` and `lbase`. For a two-letter `lb`, run
@@ -127,13 +256,25 @@ alone and suggests a shell alias instead.
127
256
 
128
257
  | Variable | Purpose |
129
258
  | --- | --- |
130
- | `LAYERBASE_API_URL` | Override the Layerbase API base (default `https://layerbase.com`). |
259
+ | `LAYERBASE_API_KEY` | Personal `sk_` API key for headless cloud access (see [Headless auth](#headless-auth-ci-and-agents)). |
260
+ | `LAYERBASE_API_URL` | Override the web API base used by the browser-login flow (default `https://layerbase.com`). |
261
+ | `LAYERBASE_CLOUD_API_URL` | Override the cloud API base used in key mode (default `https://cloud.layerbase.dev`). |
131
262
 
132
263
  ## Requirements
133
264
 
134
265
  - Node.js 20 or newer.
135
- - For `connect` / `psql` / `redis-cli` / `mysql`: the matching native client on
136
- your `PATH`.
266
+ - For `cloud connect` / `psql` / `redis-cli` / `mysql`: the matching native
267
+ client on your `PATH`.
268
+
269
+ ## For maintainers
270
+
271
+ The bare command namespace belongs to spindb. **New cloud functionality goes
272
+ under the `cloud` namespace (`lbase cloud <verb>`), or must be proven
273
+ collision-free against `spindb --help` INCLUDING aliases before it can claim a
274
+ bare verb.** The registered layerbase verbs are the single source of truth in
275
+ `src/lib/commands.ts`, and `scripts/check-spindb-collisions.ts` (part of
276
+ `pnpm check`) fails the build if any registered bare verb collides with a spindb
277
+ command. See `CLAUDE.md` for the full contract.
137
278
 
138
279
  ## License
139
280