@motherbase/cli 0.2.4 → 0.2.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Motherbase contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,7 +2,7 @@
 
 A Supabase-CLI-like operator CLI for **Motherbase**. It drives both the
 **Platform Console** (account + multi-project lifecycle) and a **linked project's
-admin API** through the Console proxy — or a single project API directly.
+admin API** through the Console proxy, or a single project API directly.
 
 Zero runtime dependencies. Node ≥ 18 (uses built-in `fetch`, `readline`, `fs`,
 `child_process` only).
@@ -18,17 +18,17 @@ motherbase functions deploy --name hello --route hello --file ./hello.js
 
 ## Connection model
 
-1. **Console / account** — `motherbase login [--url <consoleUrl>]` performs a real
+1. **Console / account**, `motherbase login [--url <consoleUrl>]` performs a real
    Console login (`POST /api/platform/login`) and stores the session token.
-2. **Linked project** — `motherbase link [project]` records which project this
+2. **Linked project**, `motherbase link [project]` records which project this
    directory targets. All resource commands then route through the Console proxy
    (`/api/projects/:id/admin/*`).
-3. **Direct mode (CI / single stack)** — set `MOTHERBASE_URL` +
+3. **Direct mode (CI / single stack)**. Set `MOTHERBASE_URL` +
    `MOTHERBASE_ADMIN_TOKEN` to talk straight to one project's `/api/admin/*`.
 
 ### Configuration files
 
-**Global credentials** — `~/.motherbase/config.json` (contains tokens, written `0o600`):
+**Global credentials**: `~/.motherbase/config.json` (contains tokens, written `0o600`):
 
 ```json
 {
@@ -39,7 +39,7 @@ motherbase functions deploy --name hello --route hello --file ./hello.js
 }
 ```
 
-**Project link** — `./.motherbase/config.json` (versionable, non-secret):
+**Project link**: `./.motherbase/config.json` (versionable, non-secret):
 
 ```json
 { "consoleUrl": "https://console.example.com", "projectId": "my-app", "projectName": "my-app" }
@@ -54,7 +54,7 @@ motherbase functions deploy --name hello --route hello --file ./hello.js
 | console URL | `--url/-u`        | `MOTHERBASE_CONSOLE_URL`  | link / global `current` |
 | token       | `--token`         | `MOTHERBASE_TOKEN`        | global console entry |
 | project     | `--project/-p`    | `MOTHERBASE_PROJECT`      | link |
-| direct API  | —                 | `MOTHERBASE_URL` + `MOTHERBASE_ADMIN_TOKEN` | — |
+| direct API  | (| `MOTHERBASE_URL` + `MOTHERBASE_ADMIN_TOKEN` |) |
 
 ### Auth headers
 
@@ -65,29 +65,80 @@ request. Console requests hit `/api/platform/*`; admin requests hit the proxy at
 
 ## Commands
 
-Global flags: `--json`, `--yes/-y`, `--project/-p <id>`, `--url/-u <consoleUrl>`,
-`--token <t>`, `-h/--help`, `-v/--version`.
+Global flags: `-o/--output pretty|json|yaml|env` (`--json` is `-o json`),
+`--yes/-y`, `--project/-p/--project-ref <id>`, `--url/-u <consoleUrl>`,
+`--token <t>`, `--workdir <dir>`, `--debug` (one stderr line per HTTP request),
+`-h/--help`, `-v/--version`.
+
+Commands follow the Supabase CLI's names. Where Motherbase already had its own
+name, both work: `projects api-keys` / `keys list`, `backups list|restore` /
+`db backups|restore`, `functions download` / `functions pull`, `db lint` /
+`rls lint`, `gen types --lang <l>` / `gen types <l>`.
 
 - **Connection**: `login`, `logout`, `whoami`, `link`, `unlink`, `status`
-- **Projects (Console)**: `projects list|create|start|stop|restart|update|rebuild|delete|logs|info|limits`
+- **Orgs & projects (Console)**: `orgs list|create`, `projects list|create|start|stop|restart|update|rebuild|delete|logs|info|limits|api-keys`
+- **Branches (Console)**: `branches create <name> [--with-data] [--git-branch <ref>]`, `branches list|get|update|delete|pause|unpause|reset|merge|rebase|switch <name>`
+- **Domains (Console)**: `domains create --custom-hostname <host>`, `domains get|reverify|activate|delete`, `vanity-subdomains get|check-availability|activate --desired-subdomain <name>|delete`
+- **Database access**: `network-restrictions get|update --db-allow-cidr <cidr> ...`, `ssl-enforcement get|update --enable-db-ssl-enforcement|--disable-db-ssl-enforcement`
 - **Local self-host** (docker compose): `init`, `start`, `stop`, `deploy`, `logs`
-- **Database**: `db tables|sql|dump|restore|backups`
-- **Migrations**: `migrations list|diff|get|create|apply|rollback`, `migration new`
+- **Database**: `db push|pull|diff|reset|dump|seed`, `db tables|sql|backup|restore|backups|lint`, `backups list|restore`, `test db`
+- **Database objects**: `db indexes list|create|drop`, `db types list|create|add-value|rename-value|drop`, `db roles list|create|alter|drop`, `db column-privileges list|grant|revoke`, `db publications list|create|alter|drop`
+- **Postgres config**: `postgres-config get [--all]`, `postgres-config update --config k=v [--scope database|role|system] [--replace-existing-overrides]`, `postgres-config delete --config k1,k2`
+- **Migrations**: `migration new|list|up|down|repair|squash|fetch|diff|get|create|apply|rollback` (`migrations` is an alias)
 - **Import**: `import --from-supabase <conn> [--preview] [--no-data] [--no-auth]`
 - **RLS**: `rls list|enable|disable`, `rls policy create|delete`
-- **Users**: `users list|get|create|update|delete|reset-password|promote|demote|revoke-sessions`
-- **Storage**: `storage buckets list|create|delete`, `storage ls|cp|rm`
-- **Functions**: `functions list|get|new|deploy|delete|invoke|logs`
-- **Secrets**: `secrets list|set|unset`
+- **Users**: `users list|get|create|update|delete|reset-password|promote|demote|revoke-sessions|audit`
+- **Storage**: `storage buckets list|create|delete`, `storage ls|cp|mv|rm [-r]` on `ss:///bucket/key` paths
+- **Functions**: `functions list|get|new|deploy|pull|download|serve|delete|invoke|logs`
+- **Secrets**: `secrets list|unset`, `secrets set NAME=VALUE ... [--env-file .env]`
 - **Realtime**: `realtime config|channels`
 - **Webhooks**: `webhooks list|create|delete|test`
 - **Cron**: `cron list|create|delete|toggle`
+- **Queues**: `queues list|enable|expose|create|drop|send|read|archive|purge`
+- **Vault**: `vault list|enable|create|update|reveal|delete`
+- **Wrappers**: `wrappers list|enable|create-server|drop-server|credentials|import|create-table|drop-table`
 - **Config**: `config list|get|set`
-- **Inspect**: `inspect logs|stats|performance|requests|advisor|shield`
-- **Codegen**: `gen types typescript [--schema public] [--local] [--output <file>] [--check]`
+- **Inspect**: `inspect db <query>`, `inspect report`, `inspect logs|stats|performance|index-advisor|requests|advisor|shield`
+- **Codegen**: `gen types [--lang typescript|zod] [--schema public] [--local] [--output <file>] [--check]`
+- **AI agents**: `mcp [--write]`
+- **Keys**: `gen signing-key [--algorithm ES256|RS256|EdDSA] [--append]`, `gen bearer-jwt --sub <user> [--role] [--valid-for 1h]`, `gen keys [-o env]`
+- **Shell**: `completion bash|zsh|fish` (e.g. `source <(motherbase completion bash)`)
 
 Run `motherbase <group> -h` for per-group usage.
 
+## Migrations and seeds
+
+Local files, laid out like a Supabase project's `supabase/` directory:
+
+```
+motherbase/
+  migrations/<version>_<name>.sql   `migration new <name>` stamps the version (UTC)
+  seed.sql                          or db.seed.sql_paths in motherbase/config.json
+  tests/*.sql                       pgTAP, for `motherbase test db`
+```
+
+A migration file may end with a `-- @down` line followed by the SQL that undoes
+it; `migration down` needs one. The linked project keeps the history, keyed on
+`version`, and the Studio Migrations page shows the same rows (origin `cli`,
+`studio` or `git`).
+
+```bash
+motherbase migration list                 # LOCAL | REMOTE side by side
+motherbase db push --dry-run              # then without, add --include-seed for the seeds
+motherbase db pull                        # remote changes -> a new file, recorded as applied
+motherbase db diff -f add_index           # the same diff, written as a new migration
+motherbase migration repair 20260101120000 --status reverted
+motherbase db reset --confirm             # backup, empty app schemas, replay migrations + seed
+motherbase db dump -f schema.sql --schema-only
+```
+
+Each pushed file runs in its own transaction; a push stops at the first file
+that fails, and nothing of that file is recorded. `db diff` replays the local
+migrations into a throwaway database on the same server and compares tables,
+columns and indexes: review what it writes. With no local migration yet, `db
+pull` writes the remote schema itself, from `pg_dump`. `db dump` used to take a
+server-side backup; that is `db backup` now.
+
 ## Type generation
 
 Generate TypeScript definitions for the live schema, in the shape supabase-js
@@ -111,6 +162,68 @@ when the committed file differs from a fresh generation:
 motherbase gen types typescript --check --output database.types.ts
 ```
 
+## Storage paths
+
+Objects are addressed as the Supabase CLI does, `ss:///<bucket>/<key>`, and
+`-r` applies a command to everything under a prefix:
+
+```bash
+motherbase storage ls                                   # buckets
+motherbase storage ls ss:///media/img                   # one level; -r for every key
+motherbase storage cp ./logo.png ss:///media/img/       # upload (overwrites)
+motherbase storage cp -r ./site ss:///web/v2            # upload a directory tree
+motherbase storage cp -r ss:///web/v2 ./site-backup     # download a prefix
+motherbase storage mv -r ss:///web/v2 ss:///web/live    # move within a bucket
+motherbase storage rm -r ss:///web/old
+```
+
+Bulk commands send one request per object and stop at the first failure,
+saying how many had already gone through. `mv` and in-bucket `cp` work within
+one bucket. The older forms still work: `cp ./a.png bucket:` uploads with a
+generated key, `cp <fileId> ./a.png` downloads and `rm <fileId>` deletes by id.
+
+## Database inspection
+
+`inspect db` runs the Supabase CLI's diagnostic queries against the linked
+project, on its read-only SQL endpoint:
+
+```bash
+motherbase inspect db outliers        # slowest queries by total time
+motherbase inspect db table-stats -o json
+motherbase inspect report --output-dir reports   # one CSV per query in reports/<YYYY-MM-DD>/
+```
+
+The queries are `bloat`, `blocking`, `calls`, `db-stats`, `index-stats`,
+`locks`, `long-running-queries`, `outliers`, `replication-slots`, `role-stats`,
+`table-stats`, `traffic-profile` and `vacuum-stats`. The names Supabase has
+deprecated (`cache-hit`, `index-usage`, `table-sizes`, `unused-indexes`, …)
+still work and run the query that replaced them. `calls` and `outliers` read
+`pg_stat_statements`: it is preloaded by the Motherbase Postgres image but has
+to be created once per database (Studio > Database > Extensions, or
+`motherbase db sql -e "create extension pg_stat_statements"`); `inspect report`
+skips those two files until it is.
+
+## MCP server
+
+`motherbase mcp` serves this project to an AI agent over stdio:
+
+```json
+{ "mcpServers": { "motherbase": { "command": "npx", "args": ["@motherbase/cli", "mcp"] } } }
+```
+
+It exposes what the session can reach. With a linked project (or direct mode):
+`list_tables`, `describe_table`, `list_policies`, `simulate_rls`,
+`get_advisors`, `get_logs`, `generate_types`, `execute_sql` (read-only),
+`get_project_url`, `get_publishable_keys`, `list_extensions`,
+`list_migrations`, `list_edge_functions`, `get_edge_function`,
+`list_storage_buckets` and `get_storage_config`. With a console login:
+`list_organizations`, `get_organization`, `list_projects` and `get_project`.
+
+Everything that changes something needs `--write`: `apply_migration`,
+`execute_sql_write`, `deploy_edge_function`, `create_project`,
+`pause_project` and `restore_project`. The names and arguments follow
+Supabase's MCP server.
+
 ## Supabase migration
 
 Preview a Supabase import without writing to Motherbase:

package/bin/motherbase.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-'use strict';
-
-const { main } = require('../src/main');
-
-main(process.argv.slice(2))
-  .then(code => { process.exitCode = code || 0; })
-  .catch(err => {
-    process.stderr.write((err && err.message ? err.message : String(err)) + '\n');
-    process.exitCode = 1;
-  });
+'use strict';
+
+const { main } = require('../src/main');
+
+main(process.argv.slice(2))
+  .then(code => { process.exitCode = code || 0; })
+  .catch(err => {
+    process.stderr.write((err && err.message ? err.message : String(err)) + '\n');
+    process.exitCode = 1;
+  });

package/package.json

@@ -1,26 +1,35 @@
-{
-  "name": "@motherbase/cli",
-  "version": "0.2.4",
-  "description": "Motherbase operator CLI — drives the Platform Console and linked projects.",
-  "type": "commonjs",
-  "bin": {
-    "motherbase": "./bin/motherbase.js"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "test": "node --test",
-    "lint": "eslint ."
-  },
-  "files": [
-    "bin",
-    "src",
-    "README.md"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "license": "MIT",
-  "dependencies": {}
-}
+{
+  "name": "@motherbase/cli",
+  "version": "0.2.6",
+  "description": "Motherbase operator CLI: drives the Platform Console and linked projects.",
+  "type": "commonjs",
+  "bin": {
+    "motherbase": "./bin/motherbase.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test",
+    "docs:cli": "node scripts/generate-cli-docs.js",
+    "lint": "eslint ."
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JulienGuinot/Boilerplate-backend.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/JulienGuinot/Boilerplate-backend#readme",
+  "bugs": {
+    "url": "https://github.com/JulienGuinot/Boilerplate-backend/issues"
+  }
+}