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.
- package/README.md +186 -45
- package/dist/cli.js +310 -46
- package/dist/cli.js.map +1 -1
- package/dist/commands/agent-init.js +112 -0
- package/dist/commands/agent-init.js.map +1 -0
- package/dist/commands/cloud-branch.js +97 -0
- package/dist/commands/cloud-branch.js.map +1 -0
- package/dist/commands/cloud-write.js +133 -0
- package/dist/commands/cloud-write.js.map +1 -0
- package/dist/commands/connection-string.js +17 -16
- package/dist/commands/connection-string.js.map +1 -1
- package/dist/commands/import.js +96 -0
- package/dist/commands/import.js.map +1 -0
- package/dist/commands/interactive.js +2 -0
- package/dist/commands/interactive.js.map +1 -1
- package/dist/commands/key-login.js +48 -0
- package/dist/commands/key-login.js.map +1 -0
- package/dist/commands/ls.js +17 -5
- package/dist/commands/ls.js.map +1 -1
- package/dist/commands/migrate.js +331 -0
- package/dist/commands/migrate.js.map +1 -0
- package/dist/commands/whoami-run.js +87 -0
- package/dist/commands/whoami-run.js.map +1 -0
- package/dist/commands/whoami.js +1 -1
- package/dist/commands/whoami.js.map +1 -1
- package/dist/lib/cli-output.js +28 -0
- package/dist/lib/cli-output.js.map +1 -0
- package/dist/lib/cloud-api.js +338 -20
- package/dist/lib/cloud-api.js.map +1 -1
- package/dist/lib/commands.js +90 -18
- package/dist/lib/commands.js.map +1 -1
- package/dist/lib/config.js +18 -0
- package/dist/lib/config.js.map +1 -1
- package/dist/lib/confirm.js +17 -0
- package/dist/lib/confirm.js.map +1 -0
- package/dist/lib/duration.js +33 -0
- package/dist/lib/duration.js.map +1 -0
- package/dist/lib/migration-catalog.js +209 -0
- package/dist/lib/migration-catalog.js.map +1 -0
- package/dist/lib/redact.js +23 -0
- package/dist/lib/redact.js.map +1 -0
- package/dist/lib/select.js +48 -0
- package/dist/lib/select.js.map +1 -0
- package/dist/lib/version.js +26 -0
- package/dist/lib/version.js.map +1 -0
- package/dist/ui/app.js +1 -1
- package/dist/ui/app.js.map +1 -1
- package/package.json +6 -3
- package/skills/layerbase/SKILL.md +222 -0
package/README.md
CHANGED
|
@@ -3,13 +3,16 @@
|
|
|
3
3
|
[](https://www.npmjs.com/package/layerbase)
|
|
4
4
|
[](https://www.npmjs.com/package/layerbase)
|
|
5
5
|
|
|
6
|
-
The Layerbase
|
|
7
|
-
|
|
8
|
-
|
|
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
|
-
|
|
11
|
-
|
|
12
|
-
`
|
|
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
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
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
|
-
##
|
|
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
|
-
| `
|
|
41
|
-
| `
|
|
42
|
-
| `
|
|
43
|
-
| `
|
|
44
|
-
| `
|
|
45
|
-
| `
|
|
46
|
-
| `
|
|
47
|
-
| `
|
|
48
|
-
| `
|
|
49
|
-
| `
|
|
50
|
-
| `
|
|
51
|
-
| `
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
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
|
-
|
|
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
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
| `
|
|
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
|
|
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
|
|