@nestcorehq/cli 0.8.0 → 0.10.0

package/README.md

@@ -1,214 +1,256 @@
-# @nestcorehq/cli
-
-The command-line interface for the [NestCore](https://nestcore.io) platform.
-
-`nestcore` brings the day-to-day backend workflow into your terminal and your
-repo: sign in once, link a directory to a project, run versioned SQL
-migrations, and generate TypeScript types straight from your live schema — the
-same ergonomics you expect from a modern backend toolchain.
-
-```bash
-npm install -g @nestcorehq/cli
-# or run without installing:
-npx @nestcorehq/cli --help
-```
-
-> Requires Node.js 22+.
-
----
-
-## Quick start
-
-```bash
-# 1. Sign in (credentials are stored in ~/.nestcore/credentials.json, mode 0600)
-nestcore login
-
-# 2. Link the current directory to one of your projects
-nestcore link my-project        # by slug, name, or id
-#   → writes .nestcore/config.json (safe to commit)
-
-# 3. Scaffold and apply a migration
-nestcore migration new "create posts table"
-#   → edits migrations/001_create_posts_table.sql
-nestcore db push
-
-# 4. Generate types from the live schema
-nestcore gen types              # → nestcore.types.ts
-```
-
----
-
-## Commands
-
-### Auth
-
-| Command | Description |
-| --- | --- |
-| `nestcore login` | Sign in. Reads `--email` / `--password`, then `NESTCORE_EMAIL` / `NESTCORE_PASSWORD`, then prompts interactively (password input is masked). |
-| `nestcore logout` | Revoke the refresh token and clear the local session. |
-| `nestcore whoami` | Show the current session, API URL, and token expiry. |
-
-### Projects
-
-| Command | Description |
-| --- | --- |
-| `nestcore projects` | List your projects (name, slug, id). |
-| `nestcore link [id\|slug\|name]` | Link the current directory to a project. With no argument and a single project, links it automatically; otherwise lists choices. Writes `.nestcore/config.json`. |
-
-### Database & migrations
-
-| Command | Description |
-| --- | --- |
-| `nestcore migration new <name>` | Scaffold `migrations/NNN_<name>.sql` with `up` / `-- migrate:down` sections. |
-| `nestcore db push` | Apply every pending migration in order, inside a transaction each. |
-| `nestcore db status` | Show which migrations are applied, pending, failed, or modified-after-apply. |
-| `nestcore db rollback [id]` | Roll back the latest applied migration (or a specific `id`) using its `-- migrate:down` section. |
-| `nestcore db reset --yes` | **Destructive.** Drop every table in the project (internal `auth_*` tables are spared) and re-apply all migrations from scratch. Requires `--yes`. First dry-runs the drop + every migration in a rolled-back transaction; if that fails, nothing is dropped. |
-| `nestcore db sql "<SQL>"` | Run ad-hoc SQL against the linked project. `--file <path>` runs a file. |
-| `nestcore db connect` | Print the direct Postgres connection string (when the deployment has direct connections enabled). |
-| `nestcore gen types` | Introspect the schema and emit TypeScript interfaces + a `Database` map (`bigint`/`numeric` and enums are typed `string`, `json`/`jsonb` `unknown` — matching what the API returns). `--out <file>` (default `nestcore.types.ts`) or `--stdout`. |
-
-### Integrations
-
-| Command | Description |
-| --- | --- |
-| `nestcore webhooks list` | List the project's webhooks. |
-| `nestcore webhooks create --url <u> [--events INSERT,UPDATE,DELETE] [--table <t>] [--name <n>]` | Create a webhook (prints the signing secret once). |
-| `nestcore webhooks delete <id>` / `test <id>` | Remove a webhook / send it a test event. |
-| `nestcore sms get` | Show the project's Twilio/SMS config. |
-| `nestcore sms set [--sid <s>] [--token <t>] [--from <n>] [--enable\|--disable]` | Configure Twilio (auth token stored encrypted). |
-| `nestcore sms test <phone>` | Send a test SMS. |
-
-### AI
-
-| Command | Description |
-| --- | --- |
-| `nestcore ai overview` | Counts of memories, memory subjects, collections, documents, threads, messages, traces (last 24 h) and embedded columns. Shows zeros until the project uses an AI feature. |
-| `nestcore ai embeddings list` | Embedded columns with progress: rows, embedded, pending, failed and the last error. |
-| `nestcore ai embeddings enable --table <t> --columns <a,b> [--target <col>] [--model <m>] [--provider <p>]` | Keep a `vector(768)` column (default `<first column>_embedding`) up to date from the source columns, and backfill existing rows. Admin role. |
-| `nestcore ai embeddings reembed <table> <column> [--model <m>] [--provider <p>]` | Re-embed every row, optionally switching model. Admin role. |
-| `nestcore ai embeddings disable <table> <column> [--drop-columns]` | Stop embedding a column; `--drop-columns` also drops the vector columns. Admin role. |
-| `nestcore ai collections list` | Vector collections with their model, document counts and chunking. |
-| `nestcore ai traces [--limit n] [--status ok\|error]` | Recent AI calls (default 20, max 500): kind, caller, model, tokens, cost, latency and status. |
-
-### Options
-
-| Option | Applies to | Description |
-| --- | --- | --- |
-| `-p, --project <id\|slug>` | db / gen / webhooks / sms / auth-security / ai | Target a specific project, overriding the linked one. |
-| `-d, --dir <path>` | migration / db | Migrations directory (default `migrations`). |
-| `-o, --out <file>` | gen types | Output file. |
-| `--stdout` | gen types | Print to stdout instead of a file. |
-| `-f, --file <path>` | db sql | Read SQL from a file. |
-| `--url <url>` | login | API base URL (default `https://api.nestcore.io`). |
-| `-h, --help` | — | Show help. |
-| `-v, --version` | — | Show version. |
-
----
-
-## Migrations
-
-A migration is a plain `.sql` file named `NNN_description.sql`. The numeric
-prefix defines apply order. An optional `-- migrate:down` line splits the file
-into a forward (`up`) section and a rollback (`down`) section:
-
-```sql
--- Migration 001: create posts table
--- Forward (up) SQL — applied by `nestcore db push`.
-CREATE TABLE posts (
-  id   uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-  title text NOT NULL,
-  created_at timestamptz DEFAULT now()
-);
-
--- migrate:down
--- Rollback SQL — applied by `nestcore db rollback`.
-DROP TABLE posts;
-```
-
-How it works:
-
-- A `migrations` registry table tracks `migration_id`, `name`, `checksum`,
-  `executed_at`, and `status`.
-- Each migration runs wrapped in `BEGIN; … COMMIT;` — a failure rolls the whole
-  file back and is recorded as `failed`.
-- Already-applied migrations are skipped. If an applied file's checksum no
-  longer matches, `db push` refuses to continue (add a new migration instead of
-  editing history).
-
----
-
-## Type generation
-
-`nestcore gen types` reads `information_schema.columns` for your `public`
-schema (skipping internal `auth_*`, `pg_*`, and `_*` tables) and emits a
-strongly-typed module:
-
-```ts
-// Generated by @nestcorehq/cli — do not edit by hand.
-export interface Posts {
-  id: string;
-  title: string;
-  created_at?: string | null;
-}
-
-export interface Database {
-  "posts": Posts;
-}
-```
-
-Re-run it after every schema change and commit the output, or wire it into a
-`predev` / `prebuild` script.
-
----
-
-## Permissions
-
-Raw SQL (`db sql`, `db push`/`status`/`rollback`/`reset`, `gen types`, `db diff`) runs only for the user who **created** the project; other workspace members get a 403 explaining this.
-
-## Configuration & files
-
-| Path | Scope | Contents |
-| --- | --- | --- |
-| `~/.nestcore/credentials.json` | global, `0600` | Access/refresh tokens, API URL, user. Shared with the NestCore MCP server; token refreshes are serialised through `~/.nestcore/credentials.lock`. |
-| `./.nestcore/config.json` | per-directory | Linked `projectId`, `projectSlug`, `name`, `apiUrl` (same file the MCP server reads; older files with `slug` still work). Safe to commit. |
-
-Environment variables (override stored values):
-
-- `NESTCORE_API_URL` — API base URL.
-- `NESTCORE_EMAIL`, `NESTCORE_PASSWORD` — non-interactive login.
-- `NESTCORE_MFA_CODE` — two-factor code for non-interactive login.
-- `NO_COLOR` — disable ANSI colors.
-
-### Upgrading from `@orbitneststudio/cli`
-
-The CLI was renamed from OrbitNest to NestCore. Existing setups keep working:
-
-- `orbitnest` is installed as a second command name for `nestcore`.
-- `~/.orbitnest/credentials.json` is read when `~/.nestcore/credentials.json`
-  doesn't exist yet; new sessions are written to `~/.nestcore` (and mirrored to
-  the old file while it exists, so older tools sharing it stay signed in).
-- `./.orbitnest/config.json` and `./.orbitnest/schema.snapshot.json` are read
-  when the `.nestcore` equivalents are absent; `link` and `db diff --save` write
-  the new paths.
-- The old `ORBITNEST_*` environment variables are used when the `NESTCORE_*`
-  ones are unset.
-
----
-
-## Development
-
-```bash
-npm install
-npm run build      # bundle to dist/ with tsup (CJS + shebang)
-npm run dev        # watch mode
-npm run typecheck  # tsc --noEmit
-
-node dist/index.js --help
-```
-
----
-
-## License
-
-MIT © NestCore
+# @nestcorehq/cli
+
+The command-line interface for the [NestCore](https://nestcore.io) platform.
+
+`nestcore` brings the day-to-day backend workflow into your terminal and your
+repo: sign in once, link a directory to a project, run versioned SQL
+migrations, and generate TypeScript types straight from your live schema — the
+same ergonomics you expect from a modern backend toolchain.
+
+```bash
+npm install -g @nestcorehq/cli
+# or run without installing:
+npx @nestcorehq/cli --help
+```
+
+> Requires Node.js 22+.
+
+---
+
+## Quick start
+
+```bash
+# 1. Sign in (credentials are stored in ~/.nestcore/credentials.json, mode 0600)
+nestcore login
+
+# 2. Link the current directory to one of your projects
+nestcore link my-project        # by slug, name, or id
+#   → writes .nestcore/config.json (safe to commit)
+
+# 3. Scaffold and apply a migration
+nestcore migration new "create posts table"
+#   → edits migrations/001_create_posts_table.sql
+nestcore db push
+
+# 4. Generate types from the live schema
+nestcore gen types              # → nestcore.types.ts
+```
+
+---
+
+## Commands
+
+### Auth
+
+| Command | Description |
+| --- | --- |
+| `nestcore login` | Sign in. Reads `--email` / `--password`, then `NESTCORE_EMAIL` / `NESTCORE_PASSWORD`, then prompts interactively (password input is masked). |
+| `nestcore logout` | Revoke the refresh token and clear the local session. |
+| `nestcore whoami` | Show the current session, API URL, and token expiry. |
+
+### Projects
+
+| Command | Description |
+| --- | --- |
+| `nestcore projects` | List your projects (name, slug, id). |
+| `nestcore link [id\|slug\|name]` | Link the current directory to a project. With no argument and a single project, links it automatically; otherwise lists choices. Writes `.nestcore/config.json`. Add `--branch development` to make Development the default for this directory. |
+
+### Branches
+
+Every App project has a **Production** branch (the live project) and a **Development** branch: a copy of Production's schema and config (tables, RLS, functions, buckets, auth settings) with its own data, end users, URL and keys. Schema changes you make on Development are recorded and can be promoted to Production.
+
+| Command | Description |
+| --- | --- |
+| `nestcore branches` | Production and Development: status, database and file sizes, changes waiting to be promoted. |
+| `nestcore branches create` | Create the Development branch (schema + config, no data). |
+| `nestcore branches reset --yes` | Rebuild Development from Production. Deletes its rows, end users and files; keeps its URL, keys, env vars and functions. |
+| `nestcore branches changes` | Schema changes recorded on Development and not promoted yet (`!` = can lose data). |
+| `nestcore branches discard <id…>` | Drop recorded changes so they are never promoted. |
+| `nestcore branches promote` | Preview what would be promoted. |
+| `nestcore branches promote --yes` | Promote (workspace admins). Schema changes run in one transaction on Production; then functions, new buckets and new jobs (created off). Add `--env` for missing env vars, `--auth-settings` to copy auth settings, `--confirm-destructive` for DROP / RENAME / type changes, `--acknowledge-drift` if Production changed meanwhile. |
+| `nestcore branches delete --yes` | Delete the Development branch (workspace admins). |
+
+Target a branch on any command with `--branch production` or `--branch development` (`-b`, also `prod` / `dev`), or link the directory with `--branch`. A typical flow:
+
+```bash
+nestcore link my-app --branch development
+nestcore db push                 # migrations go to Development
+nestcore gen types
+nestcore branches promote        # review
+nestcore branches promote --yes  # apply to Production
+```
+
+### Database & migrations
+
+| Command | Description |
+| --- | --- |
+| `nestcore migration new <name>` | Scaffold `migrations/NNN_<name>.sql` with `up` / `-- migrate:down` sections. |
+| `nestcore db push` | Apply every pending migration in order, inside a transaction each. |
+| `nestcore db status` | Show which migrations are applied, pending, failed, or modified-after-apply. |
+| `nestcore db rollback [id]` | Roll back the latest applied migration (or a specific `id`) using its `-- migrate:down` section. |
+| `nestcore db reset --yes` | **Destructive.** Drop every table in the project (internal `auth_*` tables are spared) and re-apply all migrations from scratch. Requires `--yes`. First dry-runs the drop + every migration in a rolled-back transaction; if that fails, nothing is dropped. |
+| `nestcore db sql "<SQL>"` | Run ad-hoc SQL against the linked project. `--file <path>` runs a file. |
+| `nestcore db connect` | Print the direct Postgres connection string (when the deployment has direct connections enabled). |
+| `nestcore gen types` | Introspect the schema and emit TypeScript interfaces + a `Database` map (`bigint`/`numeric` and enums are typed `string`, `json`/`jsonb` `unknown` — matching what the API returns). `--out <file>` (default `nestcore.types.ts`) or `--stdout`. |
+
+### Integrations
+
+| Command | Description |
+| --- | --- |
+| `nestcore webhooks list` | List the project's webhooks. |
+| `nestcore webhooks create --url <u> [--events INSERT,UPDATE,DELETE] [--table <t>] [--name <n>]` | Create a webhook (prints the signing secret once). |
+| `nestcore webhooks delete <id>` / `test <id>` | Remove a webhook / send it a test event. |
+| `nestcore sms get` | Show the project's Twilio/SMS config. |
+| `nestcore sms set [--sid <s>] [--token <t>] [--from <n>] [--enable\|--disable]` | Configure Twilio (auth token stored encrypted). |
+| `nestcore sms test <phone>` | Send a test SMS. |
+
+### AI
+
+| Command | Description |
+| --- | --- |
+| `nestcore ai overview` | Counts of memories, memory subjects, collections, documents, threads, messages, traces (last 24 h) and embedded columns. Shows zeros until the project uses an AI feature. |
+| `nestcore ai embeddings list` | Embedded columns with progress: rows, embedded, pending, failed and the last error. |
+| `nestcore ai embeddings enable --table <t> --columns <a,b> [--target <col>] [--model <m>] [--provider <p>]` | Keep a `vector(768)` column (default `<first column>_embedding`) up to date from the source columns, and backfill existing rows. Admin role. |
+| `nestcore ai embeddings reembed <table> <column> [--model <m>] [--provider <p>]` | Re-embed every row, optionally switching model. Admin role. |
+| `nestcore ai embeddings disable <table> <column> [--drop-columns]` | Stop embedding a column; `--drop-columns` also drops the vector columns. Admin role. |
+| `nestcore ai collections list` | Vector collections with their model, document counts and chunking. |
+| `nestcore ai traces [--limit n] [--status ok\|error]` | Recent AI calls (default 20, max 500): kind, caller, model, tokens, cost, latency and status. |
+
+### AI credit
+
+Prepaid AI credit belongs to the workspace and is shared by all its projects. It pays for AI calls of projects
+without their own provider key (a project's own key always wins), at the platform's key plus the margin. A
+workspace that never bought credit is never charged.
+
+| Command | Description |
+| --- | --- |
+| `nestcore credits` | Balance, monthly cap, this month's spend, whether credit can pay for a call now, the credit packs and the recent ledger. |
+| `nestcore credits buy <pack> [--open]` | Print a Stripe Checkout link for a pack (e.g. `credits_10`) to open and pay in the browser; `--open` opens it. Nothing is charged until you pay, and the credit appears once Stripe confirms. Admin role. |
+| `nestcore credits cap <usd\|off>` | Set the monthly cap on credit spend (e.g. `20` or `12.50`), or remove it with `off`. Admin role. |
+
+An AI call paid from credit fails with `CREDITS_EXHAUSTED` when the balance is gone or the cap is reached; the CLI
+prints which one, the next step and the buy link.
+
+### Options
+
+| Option | Applies to | Description |
+| --- | --- | --- |
+| `-p, --project <id\|slug>` | db / gen / webhooks / sms / auth-security / ai / branches | Target a specific project, overriding the linked one. |
+| `-b, --branch <name>` | db / gen / webhooks / sms / auth-security / ai | `production` or `development` (`prod` / `dev`), overriding the linked branch. |
+| `-d, --dir <path>` | migration / db | Migrations directory (default `migrations`). |
+| `-o, --out <file>` | gen types | Output file. |
+| `--stdout` | gen types | Print to stdout instead of a file. |
+| `-f, --file <path>` | db sql | Read SQL from a file. |
+| `--url <url>` | login | API base URL (default `https://api.nestcore.io`). |
+| `-h, --help` | — | Show help. |
+| `-v, --version` | — | Show version. |
+
+---
+
+## Migrations
+
+A migration is a plain `.sql` file named `NNN_description.sql`. The numeric
+prefix defines apply order. An optional `-- migrate:down` line splits the file
+into a forward (`up`) section and a rollback (`down`) section:
+
+```sql
+-- Migration 001: create posts table
+-- Forward (up) SQL — applied by `nestcore db push`.
+CREATE TABLE posts (
+  id   uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  title text NOT NULL,
+  created_at timestamptz DEFAULT now()
+);
+
+-- migrate:down
+-- Rollback SQL — applied by `nestcore db rollback`.
+DROP TABLE posts;
+```
+
+How it works:
+
+- A `migrations` registry table tracks `migration_id`, `name`, `checksum`,
+  `executed_at`, and `status`.
+- Each migration runs wrapped in `BEGIN; … COMMIT;` — a failure rolls the whole
+  file back and is recorded as `failed`.
+- Already-applied migrations are skipped. If an applied file's checksum no
+  longer matches, `db push` refuses to continue (add a new migration instead of
+  editing history).
+
+---
+
+## Type generation
+
+`nestcore gen types` reads `information_schema.columns` for your `public`
+schema (skipping internal `auth_*`, `pg_*`, and `_*` tables) and emits a
+strongly-typed module:
+
+```ts
+// Generated by @nestcorehq/cli — do not edit by hand.
+export interface Posts {
+  id: string;
+  title: string;
+  created_at?: string | null;
+}
+
+export interface Database {
+  "posts": Posts;
+}
+```
+
+Re-run it after every schema change and commit the output, or wire it into a
+`predev` / `prebuild` script.
+
+---
+
+## Permissions
+
+Raw SQL (`db sql`, `db push`/`status`/`rollback`/`reset`, `gen types`, `db diff`) runs only for the user who **created** the project; other workspace members get a 403 explaining this.
+
+## Configuration & files
+
+| Path | Scope | Contents |
+| --- | --- | --- |
+| `~/.nestcore/credentials.json` | global, `0600` | Access/refresh tokens, API URL, user. Shared with the NestCore MCP server; token refreshes are serialised through `~/.nestcore/credentials.lock`. |
+| `./.nestcore/config.json` | per-directory | Linked `projectId`, `projectSlug`, `name`, `apiUrl` and optional `branch` (same file the MCP server reads; older files with `slug` still work). Safe to commit. |
+
+Environment variables (override stored values):
+
+- `NESTCORE_API_URL` — API base URL.
+- `NESTCORE_EMAIL`, `NESTCORE_PASSWORD` — non-interactive login.
+- `NESTCORE_MFA_CODE` — two-factor code for non-interactive login.
+- `NO_COLOR` — disable ANSI colors.
+
+### Upgrading from `@orbitneststudio/cli`
+
+The CLI was renamed from OrbitNest to NestCore. Existing setups keep working:
+
+- `orbitnest` is installed as a second command name for `nestcore`.
+- `~/.orbitnest/credentials.json` is read when `~/.nestcore/credentials.json`
+  doesn't exist yet; new sessions are written to `~/.nestcore` (and mirrored to
+  the old file while it exists, so older tools sharing it stay signed in).
+- `./.orbitnest/config.json` and `./.orbitnest/schema.snapshot.json` are read
+  when the `.nestcore` equivalents are absent; `link` and `db diff --save` write
+  the new paths.
+- The old `ORBITNEST_*` environment variables are used when the `NESTCORE_*`
+  ones are unset.
+
+---
+
+## Development
+
+```bash
+npm install
+npm run build      # bundle to dist/ with tsup (CJS + shebang)
+npm run dev        # watch mode
+npm run typecheck  # tsc --noEmit
+npm test           # build, then run test/*.mjs against a local fake API
+
+node dist/index.js --help
+```
+
+---
+
+## License
+
+MIT © NestCore

package/dist/index.js

@@ -24,6 +24,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/index.ts
+var import_child_process = require("child_process");
 var import_fs4 = require("fs");
 var readline = __toESM(require("readline"));
 
@@ -83,6 +84,13 @@ var CRED_LOCK = (0, import_path.join)(CRED_DIR, "credentials.lock");
 var LINK_DIR = (0, import_path.resolve)(".nestcore");
 var LINK_FILE = (0, import_path.join)(LINK_DIR, "config.json");
 var LEGACY_LINK_FILE = (0, import_path.resolve)(".orbitnest", "config.json");
+function parseBranch(value) {
+  if (value === void 0) return void 0;
+  const v = value.toLowerCase();
+  if (v === "production" || v === "prod" || v === "main") return "production";
+  if (v === "development" || v === "dev") return "development";
+  fail(`Unknown branch "${value}". Use production or development.`);
+}
 function loadCredentials() {
   for (const file of [CRED_FILE, LEGACY_CRED_FILE]) {
     if (!(0, import_fs.existsSync)(file)) continue;
@@ -154,7 +162,7 @@ function loadLink() {
     const file = (0, import_fs.existsSync)(LINK_FILE) || !(0, import_fs.existsSync)(LEGACY_LINK_FILE) ? LINK_FILE : LEGACY_LINK_FILE;
     const raw = JSON.parse((0, import_fs.readFileSync)(file, "utf8"));
     if (!raw?.projectId) return null;
-    return { projectId: raw.projectId, projectSlug: raw.projectSlug ?? raw.slug, name: raw.name, apiUrl: raw.apiUrl };
+    return { projectId: raw.projectId, projectSlug: raw.projectSlug ?? raw.slug, name: raw.name, apiUrl: raw.apiUrl, branch: raw.branch };
   } catch {
     return null;
   }
@@ -183,11 +191,21 @@ function jwtExpiry(token) {
   }
 }
 var ApiError = class extends Error {
-  constructor(message, status2) {
+  /**
+   * `code` is the platform's own error code when it sent one (QUOTA_EXCEEDED,
+   * CREDITS_EXHAUSTED, AGENT_PROJECT_RESTRICTED, NOT_AN_AGENT_PROJECT, PROJECT_PAUSED, …);
+   * `body` keeps structured fields such as QUOTA_EXCEEDED's upgradeUrl or
+   * CREDITS_EXHAUSTED's reason and buyUrl.
+   */
+  constructor(message, status2, code, body) {
     super(message);
     this.status = status2;
+    this.code = code;
+    this.body = body;
   }
   status;
+  code;
+  body;
 };
 var Api = class {
   constructor(base, token, refresher) {
@@ -243,7 +261,20 @@ var Api = class {
       if (res.status === 403 && /restricted to the project owner/i.test(String(msg))) {
         msg += ". Raw SQL (incl. migrations, db reset, gen types, db diff), dropping tables, RLS toggles and policy changes are limited to the user who created the project. Ask the project owner to run this.";
       }
-      throw new ApiError(msg, res.status);
+      const code = typeof json?.code === "string" ? json.code : void 0;
+      if (code === "QUOTA_EXCEEDED" && json?.upgradeUrl) msg += `
+  Upgrade: ${json.upgradeUrl}`;
+      if (code === "PROJECT_PAUSED") msg += "\n  Resume it with `nestcore projects resume <id|slug>` or upgrade your plan.";
+      if (code === "DESTRUCTIVE_CHANGES") msg += "\n  Re-run with --confirm-destructive, or drop those changes with `nestcore branches discard <id>`.";
+      if (code === "PRODUCTION_DRIFT") msg += "\n  Review `nestcore branches promote`, then re-run with --acknowledge-drift.";
+      if (code === "PROMOTE_FAILED" && json?.failed_change?.statement) msg += `
+  Failed statement: ${json.failed_change.statement}`;
+      if (code === "CREDITS_EXHAUSTED") {
+        msg += json?.reason === "spend_cap" ? "\n  The workspace's monthly AI credit cap is reached. Raise or remove it with `nestcore credits cap <usd|off>`, add the project's own provider key, or wait for next month." : "\n  The workspace has no AI credit left. Buy a pack with `nestcore credits buy <pack>` or add the project's own provider key.";
+        if (json?.buyUrl) msg += `
+  Buy credit: ${json.buyUrl}`;
+      }
+      throw new ApiError(msg, res.status, code, json ?? void 0);
     }
     return json;
   }
@@ -297,17 +328,37 @@ function matchProject(projects, ref) {
   if (!byName[0]) fail(`No project matching "${ref}". Run \`nestcore projects\` to see them.`);
   return byName[0];
 }
-async function resolveProjectId(api, flagProject) {
+async function resolveProjectId(api, flagProject, flagBranch) {
+  const link = loadLink();
+  const branch = parseBranch(flagBranch) ?? (flagProject ? void 0 : link?.branch) ?? "production";
+  let base;
   if (flagProject) {
-    if (UUID_RE.test(flagProject)) return { id: flagProject };
-    const res = await api.get("/projects");
-    const projects = Array.isArray(res) ? res : res?.data ?? res?.projects ?? [];
-    const match = matchProject(projects, flagProject);
-    return { id: match.id, slug: match.slug };
+    if (UUID_RE.test(flagProject)) base = { id: flagProject };
+    else {
+      const res = await api.get("/projects");
+      const projects = Array.isArray(res) ? res : res?.data ?? res?.projects ?? [];
+      const match = matchProject(projects, flagProject);
+      base = { id: match.id, slug: match.slug };
+    }
+  } else if (link) {
+    base = { id: link.projectId, slug: link.projectSlug };
+  } else {
+    fail("No project selected. Run `nestcore link <project>` or pass `--project <id|slug>`.");
   }
-  const link = loadLink();
-  if (link) return { id: link.projectId, slug: link.projectSlug };
-  fail("No project selected. Run `nestcore link <project>` or pass `--project <id|slug>`.");
+  return { ...await resolveBranch(api, base.id, branch, base.slug), branch };
+}
+async function resolveBranch(api, projectId, branch, slug) {
+  const res = await api.get(`/projects/${projectId}/branches`).catch(() => null);
+  const list = res?.data ?? res;
+  const rows = list?.branches ?? [];
+  if (!rows.length) {
+    if (branch === "development") fail("Branches are not available for this project (Agent project or older API).");
+    return { id: projectId, slug };
+  }
+  const row = rows.find((b) => b.branch === branch);
+  if (!row) fail("This project has no Development branch yet. Run `nestcore branches create`.");
+  if (row.provisioning_status !== "ready") fail(`The ${branch} branch is ${row.provisioning_status}. Try again in a moment.`);
+  return { id: row.id, slug: row.slug };
 }
 
 // src/migrate.ts
@@ -653,7 +704,7 @@ function describeColumn(c) {
 // package.json
 var package_default = {
   name: "@nestcorehq/cli",
-  version: "0.8.0",
+  version: "0.10.0",
   description: "Command-line interface for the NestCore platform \u2014 auth, projects, migrations, type generation, and SQL.",
   bin: {
     nestcore: "dist/index.js",
@@ -673,6 +724,7 @@ var package_default = {
     build: "tsup",
     dev: "tsup --watch",
     typecheck: "tsc --noEmit",
+    test: "npm run build && node test/credits.mjs",
     start: "node dist/index.js"
   },
   keywords: [
@@ -702,7 +754,8 @@ var ALIAS = {
   d: "dir",
   h: "help",
   v: "version",
-  e: "email"
+  e: "email",
+  b: "branch"
 };
 function parseArgs(argv) {
   const positionals = [];
@@ -854,22 +907,51 @@ async function cmdWhoami() {
     warn(`Session check failed (${e.message}). Try \`nestcore login\`.`);
   }
 }
-async function cmdProjects() {
-  const projects = listFrom(await authed().get("/projects"));
+var PROJECT_KINDS = ["app", "agent"];
+async function cmdProjects(rest, flags) {
+  const sub = rest[0];
+  if (sub === "eligibility") {
+    const kind2 = rest[1] || str(flags, "kind") || "app";
+    if (!PROJECT_KINDS.includes(kind2)) fail("Usage: nestcore projects eligibility [app|agent]");
+    const e = await authed().get("/projects/eligibility", { kind: kind2 });
+    if (e.allowed) success(`You can create ${kind2 === "agent" ? "an agent" : "an app"} project (${e.plan} plan, ${e.used}/${e.limit ?? "\u221E"}).`);
+    else warn(`No room for ${kind2 === "agent" ? "an agent" : "an app"} project on the ${e.plan} plan (${e.used}/${e.limit}). Upgrade: ${e.upgradeUrl}`);
+    return;
+  }
+  if (sub === "pause" || sub === "resume") {
+    const ref = rest[1];
+    if (!ref) fail(`Usage: nestcore projects ${sub} <id|slug>`);
+    const match = matchProject(listFrom(await authed().get("/projects")), ref);
+    await authed().post(`/projects/${encodeURIComponent(match.id)}/status`, { status: sub === "pause" ? "paused" : "active" });
+    success(`${sub === "pause" ? "Paused" : "Resumed"} ${color.bold(match.name)}.`);
+    return;
+  }
+  if (sub && sub !== "list") fail("Usage: nestcore projects [list|eligibility|pause|resume] [--kind app|agent]");
+  const kind = str(flags, "kind") || void 0;
+  if (kind && !PROJECT_KINDS.includes(kind)) fail("--kind must be app or agent");
+  const projects = listFrom(await authed().get("/projects", { kind }));
   heading(`Projects (${projects.length})`);
   table(
-    projects.map((p) => ({ name: String(p.name ?? ""), slug: String(p.slug ?? ""), id: String(p.id ?? "") })),
-    ["name", "slug", "id"]
+    projects.map((p) => ({
+      name: String(p.name ?? ""),
+      slug: String(p.slug ?? ""),
+      kind: String(p.kind ?? "app"),
+      status: String(p.status ?? "active"),
+      id: String(p.id ?? "")
+    })),
+    ["name", "slug", "kind", "status", "id"]
   );
 }
-async function cmdLink(positionals) {
+async function cmdLink(positionals, flags) {
   const ref = positionals[0];
+  const branch = parseBranch(str(flags, "branch"));
   const projects = listFrom(await authed().get("/projects"));
+  const branchNote = branch === "development" ? ` on the ${color.bold("development")} branch` : "";
   if (!ref) {
     if (projects.length === 1) {
       const p = projects[0];
-      saveLink({ projectId: p.id, projectSlug: p.slug, name: p.name, apiUrl: apiUrl() });
-      success(`Linked to ${color.bold(p.name)} (${p.slug}).`);
+      saveLink({ projectId: p.id, projectSlug: p.slug, name: p.name, apiUrl: apiUrl(), ...branch ? { branch } : {} });
+      success(`Linked to ${color.bold(p.name)} (${p.slug})${branchNote}.`);
       return;
     }
     heading("Specify a project to link: `nestcore link <id|slug>`");
@@ -877,8 +959,9 @@ async function cmdLink(positionals) {
     return;
   }
   const match = matchProject(projects, ref);
-  saveLink({ projectId: match.id, projectSlug: match.slug, name: match.name, apiUrl: apiUrl() });
-  success(`Linked this directory to ${color.bold(match.name)} (${match.slug}).`);
+  saveLink({ projectId: match.id, projectSlug: match.slug, name: match.name, apiUrl: apiUrl(), ...branch ? { branch } : {} });
+  success(`Linked this directory to ${color.bold(match.name)} (${match.slug})${branchNote}.`);
+  if (branch === "development") log(color.dim("  Commands now target Development; pass --branch production to reach the live project."));
   log(color.dim("  Wrote .nestcore/config.json"));
 }
 function cmdMigrationNew(positionals, flags) {
@@ -890,7 +973,7 @@ function cmdMigrationNew(positionals, flags) {
 }
 async function cmdDbPush(flags) {
   const api = authed();
-  const { id } = await resolveProjectId(api, str(flags, "project"));
+  const { id } = await resolveProjectId(api, str(flags, "project"), str(flags, "branch"));
   const dir = str(flags, "dir") || "migrations";
   const sql = sqlRunner(api, id);
   const res = await push(sql, dir);
@@ -899,7 +982,7 @@ async function cmdDbPush(flags) {
 }
 async function cmdDbStatus(flags) {
   const api = authed();
-  const { id } = await resolveProjectId(api, str(flags, "project"));
+  const { id } = await resolveProjectId(api, str(flags, "project"), str(flags, "branch"));
   const dir = str(flags, "dir") || "migrations";
   const entries = await status(sqlRunner(api, id), dir);
   heading(`Migrations (${entries.filter((e) => e.applied).length}/${entries.length} applied)`);
@@ -914,14 +997,14 @@ async function cmdDbStatus(flags) {
 }
 async function cmdDbRollback(positionals, flags) {
   const api = authed();
-  const { id } = await resolveProjectId(api, str(flags, "project"));
+  const { id } = await resolveProjectId(api, str(flags, "project"), str(flags, "branch"));
   const dir = str(flags, "dir") || "migrations";
   const rolled = await rollback(sqlRunner(api, id), dir, positionals[0]);
   success(`Rolled back migration ${color.bold(rolled)}.`);
 }
 async function cmdDbReset(flags) {
   const api = authed();
-  const { id } = await resolveProjectId(api, str(flags, "project"));
+  const { id } = await resolveProjectId(api, str(flags, "project"), str(flags, "branch"));
   const dir = str(flags, "dir") || "migrations";
   if (!flags.yes && !flags.force) {
     fail("`db reset` DROPS every table in your project and re-runs all migrations. Re-run with --yes to confirm.");
@@ -935,7 +1018,7 @@ async function cmdDbReset(flags) {
 }
 async function cmdDbSql(positionals, flags) {
   const api = authed();
-  const { id } = await resolveProjectId(api, str(flags, "project"));
+  const { id } = await resolveProjectId(api, str(flags, "project"), str(flags, "branch"));
   const file = str(flags, "file");
   const sqlText = file ? (0, import_fs4.readFileSync)(file, "utf8") : positionals.join(" ");
   if (!sqlText.trim()) fail('Usage: nestcore db sql "<SQL>"  (or --file <path>)');
@@ -946,7 +1029,7 @@ ${rows.length} row(s)`));
 }
 async function cmdGenTypes(flags) {
   const api = authed();
-  const { id } = await resolveProjectId(api, str(flags, "project"));
+  const { id } = await resolveProjectId(api, str(flags, "project"), str(flags, "branch"));
   const ts = await generateTypes(sqlRunner(api, id));
   if (flags.stdout) {
     process.stdout.write(ts);
@@ -958,7 +1041,7 @@ async function cmdGenTypes(flags) {
 }
 async function cmdDbDiff(flags) {
   const api = authed();
-  const { id } = await resolveProjectId(api, str(flags, "project"));
+  const { id } = await resolveProjectId(api, str(flags, "project"), str(flags, "branch"));
   const current = await introspectSchema(sqlRunner(api, id));
   if (flags.save) {
     const path = saveSnapshot(current);
@@ -992,7 +1075,7 @@ async function cmdDbDiff(flags) {
 }
 async function cmdDbConnect(flags) {
   const api = authed();
-  const { id } = await resolveProjectId(api, str(flags, "project"));
+  const { id } = await resolveProjectId(api, str(flags, "project"), str(flags, "branch"));
   let res;
   try {
     res = await api.get(`/admin/projects/${encodeURIComponent(id)}/connection`);
@@ -1024,7 +1107,7 @@ async function cmdDbConnect(flags) {
 }
 async function cmdWebhooks(rest, flags) {
   const api = authed();
-  const { id } = await resolveProjectId(api, str(flags, "project"));
+  const { id } = await resolveProjectId(api, str(flags, "project"), str(flags, "branch"));
   const base = `/admin/projects/${encodeURIComponent(id)}/webhooks`;
   const sub = rest[0] ?? "list";
   if (sub === "list") {
@@ -1072,7 +1155,7 @@ var AUTH_SECURITY_FLAGS = [
 ];
 async function cmdAuthSecurity(rest, flags) {
   const api = authed();
-  const { id } = await resolveProjectId(api, str(flags, "project"));
+  const { id } = await resolveProjectId(api, str(flags, "project"), str(flags, "branch"));
   const base = `/projects/${encodeURIComponent(id)}/auth-settings`;
   const sub = rest[0] ?? "get";
   const show = (limits) => {
@@ -1100,7 +1183,7 @@ async function cmdAuthSecurity(rest, flags) {
 }
 async function cmdSms(rest, flags) {
   const api = authed();
-  const { id } = await resolveProjectId(api, str(flags, "project"));
+  const { id } = await resolveProjectId(api, str(flags, "project"), str(flags, "branch"));
   const base = `/admin/projects/${encodeURIComponent(id)}/sms-config`;
   const sub = rest[0] ?? "get";
   if (sub === "get") {
@@ -1156,7 +1239,7 @@ function showEmbeddings(cols) {
 }
 async function cmdAi(rest, flags) {
   const api = authed();
-  const { id } = await resolveProjectId(api, str(flags, "project"));
+  const { id } = await resolveProjectId(api, str(flags, "project"), str(flags, "branch"));
   const pid = encodeURIComponent(id);
   const area = rest[0] ?? "overview";
   if (area === "overview") {
@@ -1259,6 +1342,103 @@ Traces are kept ${d.retentionDays} day(s) on this plan. Prompts and replies are
   }
   fail(AI_USAGE);
 }
+var CREDITS_USAGE = "Usage: nestcore credits [show] | credits buy <pack> [--open] | credits cap <usd|off>";
+var money = (n) => {
+  if (n === null || n === void 0) return "\u2014";
+  const v = Number(n);
+  const abs = Math.abs(v);
+  const s = abs === 0 || abs >= 0.01 ? `$${abs.toFixed(2)}` : usd(abs);
+  return v < 0 ? `-${s}` : s;
+};
+function openInBrowser(url) {
+  if (!/^https:\/\//i.test(url)) return false;
+  const [cmd, args] = process.platform === "win32" ? ["rundll32", ["url.dll,FileProtocolHandler", url]] : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+  try {
+    const child = (0, import_child_process.spawn)(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+function showCreditSummary(c) {
+  heading("AI credit (workspace)");
+  table(
+    [
+      { item: "balance", value: money(c.balanceUsd) },
+      { item: "monthly cap", value: c.monthlyCapUsd === null || c.monthlyCapUsd === void 0 ? "none" : money(c.monthlyCapUsd) },
+      { item: "spent this month", value: money(c.spentThisMonthUsd) },
+      { item: "available now", value: c.available ? color.green("yes") : color.yellow("no") },
+      { item: "margin", value: `${c.marginPct ?? 0}%` }
+    ],
+    ["item", "value"]
+  );
+  if (!c.active) {
+    info("This workspace never bought credit, so it is never charged. Projects without their own provider key can't use the AI gateway until it does.");
+  } else if (!c.available) {
+    warn(c.balanceUsd <= 0 ? "No credit left: buy a pack with `nestcore credits buy <pack>`." : "The monthly cap is reached: raise or remove it with `nestcore credits cap <usd|off>`.");
+  }
+}
+async function cmdCredits(rest, flags) {
+  const api = authed();
+  const sub = rest[0] ?? "show";
+  if (sub === "show") {
+    const c = await api.get("/billing/credits");
+    showCreditSummary(c);
+    heading("Packs");
+    table(
+      (c.packs ?? []).map((p) => ({ pack: String(p.id), price: money(p.priceUsd), credit: money(p.creditsUsd) })),
+      ["pack", "price", "credit"]
+    );
+    const ledger = Array.isArray(c.ledger) ? c.ledger : [];
+    heading(`Recent activity (${ledger.length})`);
+    table(
+      ledger.map((l) => ({
+        time: shortTime(l.created_at),
+        kind: String(l.kind ?? ""),
+        amount: money(l.amount_usd),
+        description: String(l.description ?? "")
+      })),
+      ["time", "kind", "amount", "description"]
+    );
+    log(color.dim("\nCredit pays for AI calls of projects without their own provider key; a project's own key always wins."));
+    return;
+  }
+  if (sub === "buy") {
+    const pack = rest[1];
+    if (!pack) {
+      const c = await api.get("/billing/credits");
+      fail(`${CREDITS_USAGE}
+  Packs: ${(c.packs ?? []).map((p) => `${p.id} (${money(p.priceUsd)} \u2192 ${money(p.creditsUsd)} credit)`).join(", ")}`);
+    }
+    if (!/^[a-z0-9_-]{1,40}$/.test(pack)) fail(`"${pack}" is not a pack id. Run \`nestcore credits\` to see the packs.`);
+    const res = await api.post("/billing/credits/checkout", { pack, ref: "cli" });
+    if (!res?.url) fail("The API returned no checkout URL.");
+    info(`Checkout for ${color.bold(pack)}${res.pack?.priceUsd ? ` (${money(res.pack.priceUsd)})` : ""}. Open this link to pay with Stripe:`);
+    log(`  ${res.url}`);
+    if (flags.open === true && openInBrowser(res.url)) info("Opened it in your browser.");
+    log(color.dim("Nothing is charged until you pay. The credit shows up in `nestcore credits` once Stripe confirms the payment."));
+    return;
+  }
+  if (sub === "cap") {
+    const v = rest[1];
+    if (!v) fail(CREDITS_USAGE);
+    let cap;
+    if (["off", "none", "null"].includes(v.toLowerCase())) cap = null;
+    else {
+      if (!/^\d+(\.\d{1,2})?$/.test(v)) fail('The cap is a USD amount like 20 or 12.50, or "off" to remove it.');
+      cap = Number(v);
+      if (cap > 1e5) fail("The cap can be at most 100000 USD.");
+    }
+    const c = await api.put("/billing/credits/cap", { monthlyCapUsd: cap });
+    success(cap === null ? "Monthly AI credit cap removed." : `Monthly AI credit cap set to ${money(cap)}.`);
+    showCreditSummary(c);
+    return;
+  }
+  fail(CREDITS_USAGE);
+}
 function printHelp() {
   log(`${color.bold("nestcore")} ${color.dim("v" + VERSION)} \u2014 NestCore platform CLI
 
@@ -1271,8 +1451,25 @@ ${color.bold("Auth")}
   whoami                Show the current session
 
 ${color.bold("Projects")}
-  projects              List your projects
+  projects              List your projects with kind and status (--kind app|agent)
+  projects eligibility [app|agent]
+                        Can you create one more project of a kind? (shows the upgrade link)
+  projects pause|resume <id|slug>
+                        Pause a project (nothing is deleted) or resume it
   link <id|slug>        Link the current directory to a project (.nestcore/config.json)
+                        --branch development: work on the Development branch by default
+
+${color.bold("Branches (Production + Development)")}
+  branches              Production and Development: status, sizes, changes to promote
+  branches create       Create the Development branch (schema + config, no data)
+  branches reset --yes  Rebuild Development from Production (deletes its data, users, files)
+  branches changes      Schema changes recorded on Development, not yet promoted
+  branches discard <id\u2026> Drop recorded changes so they are never promoted
+  branches promote      Preview what would be promoted to Production
+  branches promote --yes [--confirm-destructive] [--acknowledge-drift] [--env] [--auth-settings]
+                        Apply it (admin): schema in one transaction, then functions,
+                        buckets, new jobs (off); --env adds missing env vars
+  branches delete --yes Delete the Development branch (admin)
 
 ${color.bold("Database & migrations")}
   migration new <name>  Scaffold a new migration file (NNN_name.sql)
@@ -1308,8 +1505,14 @@ ${color.bold("AI")}
   ai traces [--limit n] [--status ok|error]
                                         Recent model calls: tokens, cost, latency
 
+${color.bold("AI credit (workspace)")}
+  credits                               Balance, monthly cap, this month's spend, packs, recent activity
+  credits buy <pack> [--open]           Stripe Checkout link for a credit pack (--open: open it in the browser)
+  credits cap <usd|off>                 Set or remove the monthly cap on credit spend
+
 ${color.bold("Options")}
   -p, --project <id>    Target project (overrides the linked one)
+  -b, --branch <name>   production | development (overrides the linked branch)
   -d, --dir <path>      Migrations directory (default: migrations)
   -o, --out <file>      Output file for gen types
       --url <url>       API base URL for login (default: https://api.nestcore.io)
@@ -1320,6 +1523,115 @@ ${color.bold("Options")}
 ${color.dim("Migrations run DDL via the admin SQL endpoint. Files may include a")}
 ${color.dim("`-- migrate:down` section for rollback.")}`);
 }
+var human = (n) => {
+  const v = Number(n);
+  if (n == null || !Number.isFinite(v)) return "\u2014";
+  if (v < 1024 * 1024) return `${Math.round(v / 1024)} KB`;
+  return `${(v / 1024 / 1024).toFixed(1)} MB`;
+};
+async function cmdBranches(rest, flags) {
+  const api = authed();
+  const { id } = await resolveProjectId(api, str(flags, "project"), "production");
+  const base = `/projects/${id}/branches`;
+  const data = (r) => r?.data ?? r;
+  const sub = rest[0] ?? "list";
+  if (sub === "list" || sub === "ls") {
+    const list = data(await api.get(base));
+    if (!list?.branches?.length) fail("Branches are not available for this project.");
+    table(
+      list.branches.map((b) => ({
+        branch: b.branch === "development" ? color.yellow("development") : color.green("production"),
+        slug: String(b.slug),
+        status: String(b.provisioning_status),
+        database: human(b.database_bytes),
+        files: human(b.storage_bytes),
+        "to promote": b.branch === "development" ? String(b.pending_changes) : "",
+        id: String(b.id)
+      })),
+      ["branch", "slug", "status", "database", "files", "to promote", "id"]
+    );
+    if (!list.branches.some((b) => b.branch === "development")) info("No Development branch yet: `nestcore branches create`.");
+    return;
+  }
+  if (sub === "create") {
+    info("Creating the Development branch (copies schema and config, not data)\u2026");
+    const b = data(await api.post(`${base}/development`, {}));
+    success(`Development branch ready: ${color.bold(b.slug)}`);
+    log(color.dim(`  URL: ${b.project_url}`));
+    log(color.dim("  Use it: `nestcore link <project> --branch development`, or pass --branch development."));
+    return;
+  }
+  if (sub === "reset") {
+    if (!flags.yes) fail("Reset deletes every row, end user and file on Development and rebuilds it from Production. Re-run with --yes.");
+    info("Rebuilding Development from Production\u2026");
+    const b = data(await api.post(`${base}/development/reset`, { confirm: true }));
+    success(`Development reset (${b.slug}).`);
+    return;
+  }
+  if (sub === "delete") {
+    if (!flags.yes) fail("Deleting removes the Development database, users, files and keys. Re-run with --yes.");
+    await api.del(`${base}/development`);
+    success("Development branch deleted.");
+    return;
+  }
+  if (sub === "changes") {
+    const changes = data(await api.get(`${base}/development/changes`));
+    if (!changes.length) {
+      info("No schema changes waiting to be promoted.");
+      return;
+    }
+    for (const c of changes) {
+      log(`${color.dim(String(c.seq).padStart(3))} ${c.destructive ? color.red("!") : " "} ${c.statement}`);
+      log(color.dim(`      ${c.source} \xB7 ${c.id}`));
+    }
+    return;
+  }
+  if (sub === "discard") {
+    const ids = rest.slice(1);
+    if (!ids.length) fail("Usage: nestcore branches discard <change-id\u2026>");
+    const r = data(await api.post(`${base}/development/changes/discard`, { ids }));
+    success(`Discarded ${r.discarded} change(s).`);
+    return;
+  }
+  if (sub === "promote") {
+    const p = data(await api.get(`${base}/development/promote`));
+    heading(`Promote Development \u2192 Production (${p.production_name})`);
+    if (p.drift?.changed) warn("Production's schema changed since Development was created, reset or last promoted.");
+    if (p.changes.length) {
+      log(color.bold("Schema changes (one transaction):"));
+      for (const c of p.changes) log(`  ${c.destructive ? color.red("! ") : "  "}${c.statement}`);
+    }
+    const cfg = p.config;
+    if (cfg.functions.length) log(`${color.bold("Functions:")} ${cfg.functions.map((f) => `${f.name} (${f.status})`).join(", ")}`);
+    if (cfg.buckets.length) log(`${color.bold("Buckets:")} ${cfg.buckets.map((b) => b.name).join(", ")}`);
+    const newJobs = cfg.jobs.filter((j) => j.status === "new");
+    if (cfg.jobs.length) log(`${color.bold("Jobs:")} ${cfg.jobs.map((j) => `${j.name} (${j.status === "new" ? "new, created off" : "changed, update by hand"})`).join(", ")}`);
+    if (cfg.env_vars.length) log(`${color.bold("Env vars missing on Production:")} ${cfg.env_vars.map((e) => e.name).join(", ")} ${flags.env ? "" : color.dim("(not included; add --env)")}`);
+    if (cfg.auth_settings.changed) log(`${color.bold("Auth settings differ")} ${flags["auth-settings"] ? "" : color.dim("(not included; add --auth-settings)")}`);
+    const empty = !p.changes.length && !cfg.functions.length && !cfg.buckets.length && !newJobs.length && !(flags.env && cfg.env_vars.length) && !(flags["auth-settings"] && cfg.auth_settings.changed);
+    if (empty) {
+      info("Nothing to promote.");
+      return;
+    }
+    if (!flags.yes) {
+      info("Preview only. Re-run with --yes to apply.");
+      return;
+    }
+    const res = data(await api.post(`${base}/development/promote`, {
+      change_ids: p.changes.map((c) => c.id),
+      functions: cfg.functions.map((f) => f.name),
+      buckets: cfg.buckets.map((b) => b.name),
+      jobs: newJobs.map((j) => j.name),
+      env_vars: flags.env ? cfg.env_vars.map((e) => e.name) : [],
+      auth_settings: !!flags["auth-settings"],
+      confirm_destructive: !!flags["confirm-destructive"],
+      acknowledge_drift: !!flags["acknowledge-drift"]
+    }));
+    success(`Promoted to Production: ${JSON.stringify(res.summary)}`);
+    return;
+  }
+  fail("Usage: nestcore branches [list|create|reset|changes|discard|promote|delete]");
+}
 async function main() {
   const { positionals, flags } = parseArgs(process.argv.slice(2));
   if (flags.version) {
@@ -1340,9 +1652,12 @@ async function main() {
     case "whoami":
       return cmdWhoami();
     case "projects":
-      return cmdProjects();
+      return cmdProjects(rest, flags);
     case "link":
-      return cmdLink(rest);
+      return cmdLink(rest, flags);
+    case "branches":
+    case "branch":
+      return cmdBranches(rest, flags);
     case "migration":
       if (rest[0] === "new") return cmdMigrationNew(rest.slice(1), flags);
       return fail("Usage: nestcore migration new <name>");
@@ -1373,6 +1688,8 @@ async function main() {
       return cmdAuthSecurity(rest, flags);
     case "ai":
       return cmdAi(rest, flags);
+    case "credits":
+      return cmdCredits(rest, flags);
     case "gen":
       if (rest[0] === "types") return cmdGenTypes(flags);
       return fail("Usage: nestcore gen types");

package/package.json

@@ -1,41 +1,42 @@
-{
-  "name": "@nestcorehq/cli",
-  "version": "0.8.0",
-  "description": "Command-line interface for the NestCore platform — auth, projects, migrations, type generation, and SQL.",
-  "bin": {
-    "nestcore": "dist/index.js",
-    "orbitnest": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "engines": {
-    "node": ">=22.0.0"
-  },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "start": "node dist/index.js"
-  },
-  "keywords": [
-    "nestcore",
-    "cli",
-    "backend-as-a-service",
-    "migrations"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Orbitnest/nestcore_cli.git"
-  },
-  "license": "MIT",
-  "devDependencies": {
-    "@types/node": "^22.20.5",
-    "tsup": "^8.0.0",
-    "typescript": "^5.4.0"
-  }
-}
+{
+  "name": "@nestcorehq/cli",
+  "version": "0.10.0",
+  "description": "Command-line interface for the NestCore platform — auth, projects, migrations, type generation, and SQL.",
+  "bin": {
+    "nestcore": "dist/index.js",
+    "orbitnest": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node test/credits.mjs",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "nestcore",
+    "cli",
+    "backend-as-a-service",
+    "migrations"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Orbitnest/nestcore_cli.git"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  }
+}