@motherbase/cli 0.2.1

package/README.md

@@ -0,0 +1,110 @@
+# Motherbase CLI
+
+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.
+
+Zero runtime dependencies. Node ≥ 18 (uses built-in `fetch`, `readline`, `fs`,
+`child_process` only).
+
+```bash
+node bin/motherbase.js --help          # auto-generated help
+npm link                               # or: npm i -g @motherbase/cli
+motherbase login --url https://console.example.com
+motherbase link                        # pick a project → writes ./.motherbase/config.json
+motherbase db tables
+motherbase functions deploy --name hello --route hello --file ./hello.js
+```
+
+## Connection model
+
+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
+   directory targets. All resource commands then route through the Console proxy
+   (`/api/projects/:id/admin/*`).
+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`):
+
+```json
+{
+  "consoles": {
+    "https://console.example.com": { "token": "…", "email": "you@example.com" }
+  },
+  "current": "https://console.example.com"
+}
+```
+
+**Project link** — `./.motherbase/config.json` (versionable, non-secret):
+
+```json
+{ "consoleUrl": "https://console.example.com", "projectId": "my-app", "projectName": "my-app" }
+```
+
+### Resolution precedence
+
+`flags > env > config`, per value:
+
+| Value       | Flag              | Env                       | Config |
+| ----------- | ----------------- | ------------------------- | ------ |
+| 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` | — |
+
+### Auth headers
+
+The console session token is sent as `Authorization: Bearer <token>` on every
+request. Console requests hit `/api/platform/*`; admin requests hit the proxy at
+`/api/projects/:id/admin/*` (which validates the session, then injects its own
+`X-Platform-Token` to the project). In direct mode the admin token is the Bearer.
+
+## Commands
+
+Global flags: `--json`, `--yes/-y`, `--project/-p <id>`, `--url/-u <consoleUrl>`,
+`--token <t>`, `-h/--help`, `-v/--version`.
+
+- **Connection**: `login`, `logout`, `whoami`, `link`, `unlink`, `status`
+- **Projects (Console)**: `projects list|create|start|stop|restart|update|rebuild|delete|logs|info|limits`
+- **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`
+- **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`
+- **Realtime**: `realtime config|channels`
+- **Webhooks**: `webhooks list|create|delete|test`
+- **Cron**: `cron list|create|delete|toggle`
+- **Config**: `config list|get|set`
+- **Inspect**: `inspect logs|stats|performance|requests|advisor|shield`
+
+Run `motherbase <group> -h` for per-group usage.
+
+## Supabase migration
+
+Preview a Supabase import without writing to Motherbase:
+
+```bash
+motherbase import --from-supabase "$SUPABASE_DB_URL" --preview --json
+```
+
+Run the import:
+
+```bash
+motherbase import --from-supabase "$SUPABASE_DB_URL" --yes
+```
+
+The importer moves the portable parts of a Supabase project: `public` schema, table data, RLS policies, and email/password users from `auth.users`. Storage objects are not copied. Use `--no-data` or `--no-auth` for partial imports.
+
+## Tests
+
+```bash
+npm test        # node --test, mocked fetch, no network/DB
+```

package/bin/motherbase.js

@@ -0,0 +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;
+  });

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@motherbase/cli",
+  "version": "0.2.1",
+  "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"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/src/api.js

@@ -0,0 +1,200 @@
+'use strict';
+
+// The one and only HTTP layer. Every command routes through here so auth headers,
+// URL construction and error mapping live in a single place.
+//
+// URL shapes:
+//   console request      -> ${consoleUrl}/api/platform${path}
+//   admin (console mode) -> ${consoleUrl}/api/projects/${projectId}/admin${path}
+//   admin (direct mode)  -> ${directUrl}/api/admin${path}
+//   edge invoke (console)-> ${consoleUrl}/api/projects/${projectId}/edge/${route}
+//   edge invoke (direct) -> ${directUrl}/api/edge/${route}
+//
+// Auth: the console session token is sent as `Authorization: Bearer <token>`.
+// Success envelopes differ across surfaces; both wrap payload under `data`, so we
+// unwrap `body.data` when present. Non-2xx becomes a thrown CliError with the
+// status and a short message/body snippet.
+
+const fs = require('fs');
+const path = require('path');
+const { Readable } = require('stream');
+const { CliError } = require('./context');
+
+function buildQuery(query) {
+  if (!query) return '';
+  const params = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) {
+    if (v === undefined || v === null) continue;
+    params.append(k, String(v));
+  }
+  const s = params.toString();
+  return s ? `?${s}` : '';
+}
+
+function unwrap(body) {
+  if (body && typeof body === 'object' && 'data' in body) return body.data;
+  return body;
+}
+
+function errorMessage(status, body, text) {
+  const snippet = (body && (body.message || body.error)) || (text ? text.slice(0, 300) : '');
+  if (status === 401) {
+    return `Unauthorized (401)${snippet ? `: ${snippet}` : ''}. Run \`motherbase login\` (or check --token).`;
+  }
+  if (status === 403) {
+    return `Forbidden (403)${snippet ? `: ${snippet}` : ''}.`;
+  }
+  if (status === 404) {
+    return `Not found (404)${snippet ? `: ${snippet}` : ''}.`;
+  }
+  return `Request failed (${status})${snippet ? `: ${snippet}` : ''}`;
+}
+
+async function parseResponse(res) {
+  const text = await res.text();
+  let body;
+  if (text) {
+    try { body = JSON.parse(text); } catch { body = undefined; }
+  }
+  if (!res.ok) {
+    throw new CliError(errorMessage(res.status, body, text));
+  }
+  return body === undefined ? text : unwrap(body);
+}
+
+async function doFetch(url, { method = 'GET', token, body, headers = {} } = {}) {
+  const finalHeaders = { ...headers };
+  if (token) finalHeaders['authorization'] = `Bearer ${token}`;
+  let payload;
+  if (body !== undefined && body !== null) {
+    finalHeaders['content-type'] = 'application/json';
+    payload = JSON.stringify(body);
+  }
+  let res;
+  try {
+    res = await fetch(url, { method, headers: finalHeaders, body: payload });
+  } catch (err) {
+    throw new CliError(`Cannot reach ${url}: ${err.message}`);
+  }
+  return parseResponse(res);
+}
+
+// ── Console (account / multi-project) ────────────────────────────────────────
+
+function consoleRequest(ctx, method, apiPath, { body, query } = {}) {
+  const { consoleUrl, token } = ctx.requireConsole();
+  const url = `${consoleUrl}/api/platform${apiPath}${buildQuery(query)}`;
+  return doFetch(url, { method, token, body });
+}
+
+// Login is special: no token yet. Uses Better Auth's native sign-in endpoint;
+// the session token comes back in the body and/or the `set-auth-token` header
+// (bearer plugin). Returns `{ token, user }` so the caller can persist it.
+async function loginRequest(consoleUrl, email, password) {
+  const url = `${consoleUrl}/api/auth/sign-in/email`;
+  let res;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ email, password }),
+    });
+  } catch (err) {
+    throw new CliError(`Cannot reach ${url}: ${err.message}`);
+  }
+  const text = await res.text();
+  let body;
+  if (text) { try { body = JSON.parse(text); } catch { body = undefined; } }
+  if (!res.ok) {
+    throw new CliError(errorMessage(res.status, body, text));
+  }
+  const token = (body && body.token) || res.headers.get('set-auth-token') || undefined;
+  return { token, user: body && body.user };
+}
+
+// ── Admin / resource (via proxy or direct) ───────────────────────────────────
+
+function adminBase(target) {
+  if (target.mode === 'direct') {
+    return { base: `${target.baseUrl}/api/admin`, token: target.token };
+  }
+  return { base: `${target.consoleUrl}/api/projects/${target.projectId}/admin`, token: target.token };
+}
+
+function adminRequest(ctx, method, apiPath, { body, query } = {}) {
+  const target = ctx.requireProject();
+  const { base, token } = adminBase(target);
+  const url = `${base}${apiPath}${buildQuery(query)}`;
+  return doFetch(url, { method, token, body });
+}
+
+// Edge invoke goes through the un-authenticated edge route, not /admin.
+function edgeInvokeRequest(ctx, route, body) {
+  const target = ctx.requireProject();
+  const url = target.mode === 'direct'
+    ? `${target.baseUrl}/api/edge/${encodeURIComponent(route)}`
+    : `${target.consoleUrl}/api/projects/${target.projectId}/edge/${encodeURIComponent(route)}`;
+  return doFetch(url, { method: 'POST', token: target.token, body: body || {} });
+}
+
+// ── Multipart upload (native FormData/Blob; zero-dep on Node >=18) ────────────
+
+async function uploadFile(ctx, apiPath, filePath, fields = {}) {
+  const target = ctx.requireProject();
+  const { base, token } = adminBase(target);
+  const url = `${base}${apiPath}`;
+  const buf = fs.readFileSync(filePath);
+  const form = new FormData();
+  form.append('file', new Blob([buf]), path.basename(filePath));
+  for (const [k, v] of Object.entries(fields)) {
+    if (v !== undefined && v !== null) form.append(k, String(v));
+  }
+  let res;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: token ? { authorization: `Bearer ${token}` } : {},
+      body: form,
+    });
+  } catch (err) {
+    throw new CliError(`Cannot reach ${url}: ${err.message}`);
+  }
+  return parseResponse(res);
+}
+
+// ── Streamed download to a local file ────────────────────────────────────────
+
+async function downloadFile(ctx, apiPath, destPath, { query } = {}) {
+  const target = ctx.requireProject();
+  const { base, token } = adminBase(target);
+  const url = `${base}${apiPath}${buildQuery(query)}`;
+  let res;
+  try {
+    res = await fetch(url, { headers: token ? { authorization: `Bearer ${token}` } : {} });
+  } catch (err) {
+    throw new CliError(`Cannot reach ${url}: ${err.message}`);
+  }
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    let body; try { body = JSON.parse(text); } catch { /* noop */ }
+    throw new CliError(errorMessage(res.status, body, text));
+  }
+  await new Promise((resolve, reject) => {
+    const out = fs.createWriteStream(destPath);
+    out.on('error', reject);
+    out.on('finish', resolve);
+    Readable.fromWeb(res.body).pipe(out);
+  });
+  return { path: destPath, contentType: res.headers.get('content-type') || undefined };
+}
+
+module.exports = {
+  consoleRequest,
+  loginRequest,
+  adminRequest,
+  edgeInvokeRequest,
+  uploadFile,
+  downloadFile,
+  buildQuery,
+  unwrap,
+};

package/src/commands/_util.js

@@ -0,0 +1,50 @@
+'use strict';
+
+// Small shared helpers for command modules.
+
+const { CliError } = require('../context');
+
+// Parse `key=value` tokens into an object. Values that look like numbers/bools are
+// coerced unless `raw` is set. Supports dotted keys via `--json`-style callers.
+function parseKeyValues(tokens, { coerce = true } = {}) {
+  const out = {};
+  for (const tok of tokens) {
+    const idx = tok.indexOf('=');
+    if (idx <= 0) throw new CliError(`expected key=value, got "${tok}"`);
+    const key = tok.slice(0, idx).trim();
+    let value = tok.slice(idx + 1);
+    if (coerce) {
+      if (value === 'true') value = true;
+      else if (value === 'false') value = false;
+      else if (value !== '' && !Number.isNaN(Number(value)) && /^-?\d+(\.\d+)?$/.test(value)) value = Number(value);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+// Emit either raw JSON (when --json) or run the human renderer.
+function output(ctx, data, humanFn) {
+  const ui = require('../ui');
+  if (ctx.flags.json) {
+    ui.json(data);
+    return;
+  }
+  humanFn(data, ui);
+}
+
+function requireArg(value, name) {
+  if (value === undefined || value === null || value === '') {
+    throw new CliError(`missing required argument: <${name}>`);
+  }
+  return value;
+}
+
+// Split "bucket:path" into { bucket, rest }.
+function splitRef(ref) {
+  const idx = ref.indexOf(':');
+  if (idx < 0) return { bucket: undefined, rest: ref };
+  return { bucket: ref.slice(0, idx), rest: ref.slice(idx + 1) };
+}
+
+module.exports = { parseKeyValues, output, requireArg, splitRef };

package/src/commands/config.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const api = require('../api');
+const { output, requireArg, parseKeyValues } = require('./_util');
+
+const subcommands = {
+  list: {
+    summary: 'List setting groups',
+    usage: 'motherbase config list',
+    async run(ctx) {
+      const data = await api.adminRequest(ctx, 'GET', '/settings');
+      const groups = (data && data.groups) || [];
+      output(ctx, data, (_d, ui) =>
+        ui.table(groups, [
+          { key: 'key', label: 'GROUP' },
+          { key: 'label', label: 'LABEL' },
+          { key: 'source', label: 'SOURCE' },
+        ]),
+      );
+    },
+  },
+  get: {
+    summary: 'Get a settings group',
+    usage: 'motherbase config get <group>',
+    async run(ctx, args) {
+      const group = requireArg(args[0], 'group');
+      const data = await api.adminRequest(ctx, 'GET', `/settings/${group}`);
+      output(ctx, data, (d, ui) => ui.keyValue(d || {}));
+    },
+  },
+  set: {
+    summary: 'Set values in a settings group',
+    usage: 'motherbase config set <group> key=value [key2=value2 ...]',
+    async run(ctx, args) {
+      const group = requireArg(args[0], 'group');
+      const body = parseKeyValues(args.slice(1));
+      const data = await api.adminRequest(ctx, 'PUT', `/settings/${group}`, { body });
+      output(ctx, data, (d, ui) => ui.success(`Saved settings for ${group}`));
+    },
+  },
+};
+
+module.exports = {
+  summary: 'Project settings groups',
+  usage: 'motherbase config <list|get|set> ...',
+  subcommands,
+};

package/src/commands/cron.js

@@ -0,0 +1,65 @@
+'use strict';
+
+const api = require('../api');
+const { output, requireArg } = require('./_util');
+const { CliError } = require('../context');
+
+const subcommands = {
+  list: {
+    summary: 'List pg_cron jobs (and app jobs with --app)',
+    usage: 'motherbase cron list [--app]',
+    async run(ctx, args, flags) {
+      if (flags.app) {
+        const data = await api.adminRequest(ctx, 'GET', '/cron/app/jobs');
+        const jobs = (data && data.jobs) || [];
+        output(ctx, data, (_d, ui) => ui.table(jobs, [{ key: 'name', label: 'NAME' }, { key: 'schedule', label: 'SCHEDULE' }]));
+        return;
+      }
+      const data = await api.adminRequest(ctx, 'GET', '/cron/pg/jobs');
+      const jobs = Array.isArray(data) ? data : (data && data.jobs) || [];
+      output(ctx, data, (_d, ui) =>
+        ui.table(jobs, [
+          { key: 'jobid', label: 'ID' },
+          { key: 'jobname', label: 'NAME' },
+          { key: 'schedule', label: 'SCHEDULE' },
+          { key: 'active', label: 'ACTIVE' },
+        ]),
+      );
+    },
+  },
+  create: {
+    summary: 'Create a pg_cron job',
+    usage: 'motherbase cron create --name <n> --schedule "<cron>" --command "<sql>"',
+    async run(ctx, args, flags) {
+      if (!flags.name || !flags.schedule || !flags.command) throw new CliError('--name, --schedule and --command are required');
+      const body = { name: flags.name, schedule: flags.schedule, command: flags.command };
+      const data = await api.adminRequest(ctx, 'POST', '/cron/pg/jobs', { body });
+      output(ctx, data, (d, ui) => ui.success(`Created cron job ${flags.name}`));
+    },
+  },
+  delete: {
+    summary: 'Delete a pg_cron job by numeric id',
+    usage: 'motherbase cron delete <id>',
+    async run(ctx, args) {
+      const id = requireArg(args[0], 'id');
+      const data = await api.adminRequest(ctx, 'DELETE', `/cron/pg/jobs/${id}`);
+      output(ctx, data, (d, ui) => ui.success(`Deleted cron job ${id}`));
+    },
+  },
+  toggle: {
+    summary: 'Enable/disable a pg_cron job',
+    usage: 'motherbase cron toggle <id> --active <true|false>',
+    async run(ctx, args, flags) {
+      const id = requireArg(args[0], 'id');
+      const active = flags.active === undefined ? true : flags.active === 'true' || flags.active === true;
+      const data = await api.adminRequest(ctx, 'PATCH', `/cron/pg/jobs/${id}`, { body: { active } });
+      output(ctx, data, (d, ui) => ui.success(`Cron job ${id} active=${active}`));
+    },
+  },
+};
+
+module.exports = {
+  summary: 'Scheduled jobs (pg_cron)',
+  usage: 'motherbase cron <list|create|delete|toggle> ...',
+  subcommands,
+};

package/src/commands/db.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const api = require('../api');
+const prompt = require('../prompt');
+const { output, parseKeyValues } = require('./_util');
+const { CliError } = require('../context');
+
+const subcommands = {
+  tables: {
+    summary: 'List database tables',
+    usage: 'motherbase db tables',
+    async run(ctx) {
+      const data = await api.adminRequest(ctx, 'GET', '/schema/tables');
+      const tables = (data && data.tables) || data || [];
+      output(ctx, data, (_d, ui) =>
+        ui.table(Array.isArray(tables) ? tables : [], [
+          { key: 'name', label: 'TABLE' },
+          { key: 'schema', label: 'SCHEMA' },
+        ]),
+      );
+    },
+  },
+  sql: {
+    summary: 'Run SQL from -e "..." or a file',
+    usage: 'motherbase db sql -e "select 1" | motherbase db sql <file.sql>',
+    async run(ctx, args, flags) {
+      let sql = flags.e || flags.execute;
+      if (!sql && args[0]) sql = fs.readFileSync(path.resolve(ctx.cwd, args[0]), 'utf8');
+      if (!sql) throw new CliError('Provide SQL via -e "..." or a file path.');
+      const data = await api.adminRequest(ctx, 'POST', '/sql', { body: { sql } });
+      output(ctx, data, (d, ui) => {
+        if (d && Array.isArray(d.rows)) ui.table(d.rows);
+        else if (Array.isArray(d)) ui.table(d);
+        else ui.json(d);
+      });
+    },
+  },
+  dump: {
+    summary: 'Create a database backup on the server',
+    usage: 'motherbase db dump [file]',
+    async run(ctx, args) {
+      const body = args[0] ? { file: args[0] } : {};
+      const data = await api.adminRequest(ctx, 'POST', '/backups', { body });
+      output(ctx, data, (d, ui) => ui.success(`Backup created${d && d.file ? `: ${d.file}` : ''}`));
+    },
+  },
+  restore: {
+    summary: 'Restore the database from a server dump or offsite key',
+    usage: 'motherbase db restore <file> | --key <remoteKey>  --confirm',
+    async run(ctx, args, flags) {
+      const file = args[0];
+      const key = flags.key;
+      if (!file && !key) throw new CliError('Provide a <file> or --key <remoteKey>.');
+      if (!flags.confirm && !flags.yes) {
+        const ok = await prompt.confirm('This will overwrite the database. Continue?');
+        if (!ok) throw new CliError('Aborted.');
+      }
+      const body = key ? { key, confirm: 'RESTORE' } : { file, confirm: 'RESTORE' };
+      const data = await api.adminRequest(ctx, 'POST', '/backups/restore', { body });
+      output(ctx, data, (d, ui) => ui.success('Restore complete'));
+    },
+  },
+  backups: {
+    summary: 'List backups, or manage backup config (`db backups config`)',
+    usage: 'motherbase db backups [list] | motherbase db backups config [--set key=value ...]',
+    async run(ctx, args, flags) {
+      const sub = args[0];
+      if (sub === 'config') {
+        const sets = [].concat(flags.set || []).filter(Boolean);
+        if (sets.length) {
+          const body = parseKeyValues(sets);
+          const data = await api.adminRequest(ctx, 'PUT', '/backups/config', { body });
+          output(ctx, data, (d, ui) => ui.success('Backup config saved'));
+        } else {
+          const data = await api.adminRequest(ctx, 'GET', '/backups/config');
+          output(ctx, data, (d, ui) => ui.keyValue(d || {}));
+        }
+        return;
+      }
+      const data = await api.adminRequest(ctx, 'GET', '/backups/list');
+      output(ctx, data, (d, ui) => ui.json(d));
+    },
+  },
+};
+
+module.exports = {
+  summary: 'Database: tables, SQL, dumps and restores',
+  usage: 'motherbase db <tables|sql|dump|restore|backups> ...',
+  subcommands,
+};