neonctl 2.31.1 → 2.33.0

package/README.md

@@ -347,6 +347,34 @@ $ cat .neon
 
 After pinning the branch, `checkout` also runs [`env pull`](#env-pull) by default, so the branch's Neon env vars are written to your local `.env` and you can start building right away — the branch-first loop is just `link` + `checkout`. Pass `--no-env-pull` to skip it (for example when env is injected at runtime via `neon-env run` / `neon dev`, or to keep secrets out of the working tree). A pull failure never undoes the checkout: the branch stays pinned and the failure is surfaced as a warning pointing you at `neon env pull` (or `neon deploy` if a `neon.ts`-declared service is missing).
 
+### diff
+
+`diff [compare-branch]` prints a **git-style** schema diff between the branch you're on and another branch — the top-level companion to `checkout`. It reads the branch pinned in `.neon` as the side under review (the `+++` side) and compares it against the branch you name (the `---`, reference side), so `+` lines are what your current branch adds on top of the reference:
+
+```bash
+# On feature/add-comments (pinned in .neon), see how it differs from main:
+$ neon diff main
+→ Comparing schema main → feature/add-comments
+diff --neon database neondb
+--- main (br-crimson-snow-12345678)
++++ feature/add-comments (br-dry-salad-87654321)
+@@ -63,7 +64,8 @@
+ CREATE TABLE public.users (
+     id integer NOT NULL,
+     email text NOT NULL,
+-    created_at timestamp with time zone DEFAULT now()
++    created_at timestamp with time zone DEFAULT now(),
++    display_name text
+ );
+```
+
+- **`compare-branch`** is optional. Omit it to compare the current branch against its **parent** (`neon diff` answers "what did I change since branching?"). It accepts a branch **name** or `br-…` **id**.
+- **`--branch, -b <name|id>`** overrides the side under review instead of reading `.neon` — e.g. `neon diff main --branch feature/checkout` diffs an explicit branch against `main`.
+- **`--database, --db <name>`** limits the diff to one database; by default every database on the current branch is compared (each rendered as its own `diff --neon database <name>` block). A database missing on the reference side shows as fully added.
+- **`--output json|yaml`** emits a structured result per database (`{ database, base_branch, compare_branch, has_changes, diff }`) for scripting; the default renders the colorized git-style diff (respecting `--no-color` and non-TTY pipes).
+
+The human-readable summary line goes to stderr and the diff body to stdout, so `neon diff main > changes.patch` captures just the diff. When the schemas match, `diff` prints `No schema differences …` and writes nothing to stdout. For history-aware comparisons (a branch against its own past state at a timestamp or LSN), use [`branches schema-diff`](https://neon.com/docs/reference/cli-branches#schema-diff).
+
 ### env pull
 
 `env pull` writes the linked branch's Neon environment variables into a local dotenv file: an existing `.env` if you have one, otherwise `.env.local` (override with `--file <path>`). Only Neon-managed keys (`DATABASE_URL`, `DATABASE_URL_UNPOOLED`, and the Neon Auth / Data API URLs when those services are enabled) are written; any other lines in the file are preserved. The branch comes from the closest `.neon` file, so no `--branch` is needed (pass `--branch <id|name>` to target another branch).
@@ -420,7 +448,7 @@ The branch is chosen with `--branch <id|name>`; without it the project's default
 - `--update-existing` — auto-confirm overriding existing remote settings on the branch. Without it, drift on settings already present remotely (compute, TTL, `protected`) is reported as a **conflict** and `apply` makes no changes until you resolve it or pass this flag.
 - `--allow-protected` — auto-confirm applying to a branch Neon marks as protected. Without it, `apply` refuses to touch a protected branch.
 
-**Output**: `status` prints the project, branch, and reverse-engineered config; `plan` / `apply` print the planned/applied changes and any conflicts as tables. Pass `--output json` (or `--output yaml`) to emit the full machine-readable result (`PushResult`) for piping into other tools or CI.
+**Output**: `status` prints the project, branch, and reverse-engineered config. `plan` / `apply` render a **`git diff`-style report** (matching [`neon diff`](#diff)): service changes (Neon Auth, Data API, buckets, functions) list as green `+` additions, while **branch setting changes** (TTL, `protected`, compute) show grouped under a `~ <branch>` header, one sorted `field → value` line each. A bare `apply` that hits drift on settings already present remotely prints those as a sorted **before→after** diff (`current → desired`, old in red / new in green) and exits non-zero until you pass `--update-existing`. Pass `--output json` (or `--output yaml`) to emit the full machine-readable result (`PushResult`) instead, for piping into other tools or CI.
 
 **`config status --current-branch`** (alias `neon status --current-branch`) prints _only_ the branch pinned in the local `.neon` file — no network, no auth, no analytics — and exits non-zero when none is pinned. This behavior lets it safely drive a shell prompt. Example [starship](https://starship.rs) segment:
 
@@ -495,6 +523,7 @@ The target directory must be empty unless you pass `--force` (a lone `.git` is i
 | set-context                                                                |                                                                                                              | Deprecated; use `link`             |
 | env                                                                        | `pull`                                                                                                       | Manage a branch's env vars         |
 | checkout                                                                   |                                                                                                              | Pin a branch in `.neon`            |
+| diff                                                                       |                                                                                                              | Git-style schema diff vs a branch  |
 | [link](https://neon.com/docs/reference/cli-link)                           |                                                                                                              | Link a directory to a project      |
 | config                                                                     | `status`, `plan`, `apply`                                                                                    | Drive a branch from `neon.ts`      |
 | deploy                                                                     |                                                                                                              | Alias for `config apply`           |

package/dist/commands/config.js

@@ -1,14 +1,17 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { resolveConfig } from "@neon/config";
-import { apply, createBranch as createBranchFromPolicy, inspect, loadConfigFromFile, plan, } from "@neon/config-runtime";
+import { apply, createBranch as createBranchFromPolicy, inspect, loadConfigFromFile, PushConflictError, plan, } from "@neon/config-runtime";
 import chalk from "chalk";
+import { getApiClient } from "../api.js";
 import { toNeonConfigView } from "../config_format.js";
 import { contextBranch, readContextFile } from "../context.js";
 import { isCi } from "../env.js";
 import { loadEnvFileIntoProcess } from "../env_file.js";
 import { log } from "../log.js";
+import { assertAiGatewayProvisionable, warnAiGateway, } from "../utils/ai_gateway_notice.js";
 import { announceTargetBranch } from "../utils/branch_notice.js";
+import { renderAppliedChanges, renderBranchSettingConflicts, } from "../utils/config_diff.js";
 import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
 import { bundleEntry } from "../utils/esbuild.js";
 import { addDependenciesArgs, resolvePackageManager, runCommand, } from "../utils/package_manager.js";
@@ -23,19 +26,6 @@ import { autoPullEnvAfterPin } from "./env.js";
  */
 const neonctlBundler = async (fn) => zipBundle(await bundleEntry(fn.source));
 const INSPECT_FIELDS = ["project", "branch", "config"];
-// Deliberately minimal: action/kind/identifier are short and fixed-ish, so the table can
-// never overflow. Per-change `details` (a function's long invocationUrl in particular) are
-// intentionally NOT a column — they used to be JSON-stringified into a cell and blew the
-// table past 190 cols. Function URLs are printed below as a plain list (see reportPushResult),
-// and the full details are still available via `--output json`.
-const APPLIED_FIELDS = ["action", "kind", "identifier"];
-const CONFLICT_FIELDS = [
-    "identifier",
-    "field",
-    "current",
-    "desired",
-    "reason",
-];
 /**
  * Shared `--env` flag for `config plan|apply` and `deploy`. Loads a `.env` into
  * `process.env` before the policy is evaluated.
@@ -323,23 +313,56 @@ export const planCmd = async (props) => {
         ...(props.apiHost ? { apiHost: props.apiHost } : {}),
         ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
     });
-    reportPushResult(props, result, "plan", utilizedServices(config));
+    const services = utilizedServices(config);
+    reportPushResult(props, result, "plan", services);
+    // `plan` is a dry run and never pulls credentials, so it can only offer the plan-based
+    // (Free) AI Gateway notice — the reduced-model-set check needs a live gateway token,
+    // which `apply`/`checkout`/`env pull` get via the bundled env pull. Best-effort.
+    if (services.includes("AI Gateway")) {
+        await warnAiGateway({
+            apiClient: props.apiClient,
+            projectId: props.projectId,
+            branchId,
+        });
+    }
 };
 export const applyCmd = async (props) => {
     const config = await loadConfig(props);
     const branch = await resolveBranchRef(props);
     announceTargetBranch(props, branch, "Applying to branch");
     const branchId = branch.branchId;
-    const result = await apply(config, {
-        projectId: props.projectId,
-        branchId,
-        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
-        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
-        ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
-        ...(props.updateExisting ? { updateExisting: true } : {}),
-        ...(props.allowProtected ? { allowProtectedBranch: true } : {}),
-        bundleFunction: neonctlBundler,
-    });
+    // The AI Gateway can't serve on the Free plan, so refuse to provision it up front rather
+    // than write a credential that won't work. Only when the policy actually enables the
+    // gateway; best-effort on the plan lookup (a transient failure never blocks a paid user).
+    if (utilizedServices(config).includes("AI Gateway")) {
+        await assertAiGatewayProvisionable({
+            apiClient: props.apiClient,
+            projectId: props.projectId,
+        });
+    }
+    let result;
+    try {
+        result = await apply(config, {
+            projectId: props.projectId,
+            branchId,
+            ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+            ...(props.apiHost ? { apiHost: props.apiHost } : {}),
+            ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
+            ...(props.updateExisting ? { updateExisting: true } : {}),
+            ...(props.allowProtected ? { allowProtectedBranch: true } : {}),
+            bundleFunction: neonctlBundler,
+        });
+    }
+    catch (err) {
+        // Drift without `--update-existing` throws with the conflicting fields attached.
+        // Render them as the same git-style before→after diff, then fail with a concise
+        // message (the detailed diff above replaces the library's long multi-line text).
+        if (err instanceof PushConflictError) {
+            reportConflicts(props, err.conflicts);
+            throw new Error("Branch settings conflict with the policy. Re-run with --update-existing to apply the changes shown above.");
+        }
+        throw err;
+    }
     reportPushResult(props, result, "apply", utilizedServices(config));
     // After a successful apply/deploy, write the branch's Neon env vars to a local .env —
     // the same bundled convenience as `link` / `checkout`, so the branch is immediately
@@ -388,56 +411,44 @@ const utilizedServices = (config) => {
 /**
  * Render a {@link PushResult}. JSON/YAML output emits the raw result (plus a `services`
  * summary) verbatim so it can be piped; the human-readable path renders the actual changes
- * (dropping noops) and any blocking conflicts as tables, or a "nothing to do" line when both
- * are empty — and always closes with the list of services the policy utilizes so a service
- * that produces no plan step (Postgres, or the credential-gated AI Gateway) isn't mistaken
- * for being missing from the plan above.
+ * (dropping noops) and any blocking conflicts as a `git diff`-style report, or a "nothing to
+ * do" line when both are empty — and always closes with the list of services the policy
+ * utilizes so a service that produces no plan step (Postgres, or the credential-gated AI
+ * Gateway) isn't mistaken for being missing from the plan above.
+ *
+ * The diff is asymmetric on purpose (see the CLI's `neon diff`): **service** changes are
+ * additions with no "before", so they list as `+`/`~` lines; **branch setting** changes have
+ * a natural before→after, so conflicts render as a sorted `current → desired` diff. Planned
+ * branch updates (under `--update-existing`) carry only the new value, so they render
+ * desired-only for now (the previous value isn't threaded through the runtime yet).
  */
 const reportPushResult = (props, result, mode, services) => {
     if (props.output === "json" || props.output === "yaml") {
         writer(props).end({ ...result, services }, { fields: [] });
         return;
     }
-    const changes = result.applied
-        .filter((change) => change.action !== "noop")
-        .map((change) => ({
-        action: change.action,
-        kind: change.kind,
-        identifier: change.identifier,
-    }));
-    const conflicts = result.conflicts.map((conflict) => ({
-        identifier: conflict.identifier,
-        field: conflict.field,
-        current: stringify(conflict.current),
-        desired: stringify(conflict.desired),
-        reason: conflict.reason,
-    }));
+    const appliedChanges = result.applied.filter((change) => change.action !== "noop");
     // Deployed functions carry their invocation URL in the change details — collect them so
     // we can list where to call each function without digging through the raw details blob.
     // Keyed by slug so a function never shows twice.
     const functionUrlBySlug = new Map();
-    for (const change of result.applied) {
-        if (change.action === "noop")
-            continue;
+    for (const change of appliedChanges) {
         const slug = change.details?.slug;
         const invocationUrl = change.details?.invocationUrl;
         if (typeof slug === "string" && typeof invocationUrl === "string") {
             functionUrlBySlug.set(slug, invocationUrl);
         }
     }
+    // chalk self-detects TTY/NO_COLOR; `--no-color` (props.color === false) forces plain.
+    const color = props.color !== false;
     const out = writer(props);
-    const noChanges = changes.length === 0 && conflicts.length === 0;
-    if (changes.length > 0) {
-        out.write(changes, {
-            fields: APPLIED_FIELDS,
-            title: mode === "plan" ? "Planned changes" : "Applied changes",
-        });
-    }
-    if (conflicts.length > 0) {
-        out.write(conflicts, { fields: CONFLICT_FIELDS, title: "Conflicts" });
-    }
-    // Flush any tables, then append the lists/summary so they read directly below them.
-    out.end();
+    // Conflicts never reach here in the CLI: `plan` runs with updateExisting on, and a bare
+    // `apply` throws PushConflictError (rendered by reportConflicts). So an empty applied set
+    // is the whole story here.
+    const noChanges = appliedChanges.length === 0;
+    const appliedText = renderAppliedChanges(appliedChanges, mode === "plan" ? "Planned changes" : "Applied changes", { color });
+    if (appliedText)
+        out.text(`${appliedText}\n`);
     // Function URLs are a plain list rather than a table: an invocation URL can be 70+ chars,
     // which makes any bordered table overflow and wrap awkwardly in a normal terminal. A list
     // lets each URL reflow on its own line, and stays copy-pasteable.
@@ -452,15 +463,51 @@ const reportPushResult = (props, result, mode, services) => {
         log.info(`No changes — branch ${result.branchName} already matches the policy.`);
     }
     out.text(`\nUtilized services: ${services.join(", ")}\n`);
-    if (conflicts.length > 0) {
-        log.info("Resolve the conflicts above, or re-run with --update-existing to override the current remote settings.");
+};
+/**
+ * Render the branch-setting {@link ConflictReport}s a bare `apply` refused to override (drift
+ * without `--update-existing`) as the git-style before→after diff. JSON/YAML output emits the
+ * structured conflicts so it can be piped; the human path prints the sorted diff followed by
+ * any conflict whose fix is *not* `--update-existing` (e.g. an immutable "no endpoint" case),
+ * so nothing the library's error message carried is lost.
+ */
+const reportConflicts = (props, conflicts) => {
+    if (props.output === "json" || props.output === "yaml") {
+        writer(props).end({ conflicts }, { fields: [] });
+        return;
+    }
+    const out = writer(props);
+    const text = renderBranchSettingConflicts([...conflicts], {
+        color: props.color !== false,
+    });
+    if (text)
+        out.text(`${text}\n`);
+    for (const conflict of conflicts) {
+        if (!/updateExisting/i.test(conflict.reason)) {
+            out.text(`  ! ${conflict.field}: ${conflict.reason}\n`);
+        }
     }
 };
-const stringify = (value) => value === undefined
-    ? ""
-    : typeof value === "string"
-        ? value
-        : JSON.stringify(value);
+/**
+ * Block provisioning the AI Gateway on a Free plan from the `checkout` policy paths, which
+ * carry raw credentials (`apiKey`/`apiHost`) rather than the CLI's api client. Builds a client
+ * from them and defers to {@link assertAiGatewayProvisionable}. Skipped when a `runtimeApi` is
+ * injected (tests) or no `apiKey` is available; the interactive commands always have a key.
+ */
+const assertAiGatewayProvisionableFromCreds = async (props) => {
+    if (props.runtimeApi || !props.apiKey)
+        return;
+    if (!utilizedServices(props.config).includes("AI Gateway"))
+        return;
+    const apiClient = getApiClient({
+        apiKey: props.apiKey,
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
+    });
+    await assertAiGatewayProvisionable({
+        apiClient,
+        projectId: props.projectId,
+    });
+};
 /**
  * Apply a `neon.ts` policy to a **freshly created** branch (used by `neonctl checkout`
  * when it creates a branch). No-op when there is no `neon.ts` on the path from cwd up to
@@ -483,6 +530,13 @@ export const applyPolicyOnCreate = async (props) => {
             return;
         throw err;
     }
+    await assertAiGatewayProvisionableFromCreds({
+        projectId: props.projectId,
+        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
+        ...(props.runtimeApi ? { runtimeApi: props.runtimeApi } : {}),
+        config,
+    });
     log.info("Applying neon.ts policy to the new branch…");
     const result = await apply(config, {
         projectId: props.projectId,
@@ -530,6 +584,13 @@ export const createBranchFromPolicyOnCheckout = async (props) => {
             return null;
         throw err;
     }
+    await assertAiGatewayProvisionableFromCreds({
+        projectId: props.projectId,
+        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
+        ...(props.runtimeApi ? { runtimeApi: props.runtimeApi } : {}),
+        config,
+    });
     const { branchId, branchName, result } = await createBranchFromPolicy(config, {
         projectId: props.projectId,
         branchName: props.branchName,

package/dist/commands/diff.js

@@ -0,0 +1,222 @@
+import chalk from "chalk";
+import { isNeonApiError } from "../api.js";
+import { log } from "../log.js";
+import { fillSingleProject } from "../utils/enrichers.js";
+import { looksLikeBranchId } from "../utils/formats.js";
+import { renderDatabaseSchemaDiff, renderSchemaDiffReport, } from "../utils/git_diff.js";
+import { writer } from "../writer.js";
+// A top-level shortcut for `branches schema-diff`, framed like `git diff`: it
+// compares the branch you're on (pinned in `.neon`, or `--branch`) against the
+// branch you name, and prints a git-style unified schema diff. Because it has a
+// handler but no subcommands, `diff` is also listed in `NO_SUBCOMMANDS_VERBS`
+// (see index.ts) so a bare `neon diff main` isn't intercepted by the help
+// fallback.
+export const command = "diff [compare-branch]";
+export const describe = "Show a git-style schema diff between the current branch and another branch";
+export const builder = (argv) => argv
+    .usage("$0 diff [compare-branch] [options]")
+    .positional("compare-branch", {
+    describe: "Branch name or id to compare against (the reference / '---' side). " +
+        "Defaults to the current branch's parent.",
+    type: "string",
+})
+    .options({
+    "project-id": {
+        describe: "Project ID",
+        type: "string",
+    },
+    branch: {
+        alias: "b",
+        describe: "The branch to review (the '+++' side). Defaults to the branch " +
+            "pinned in the local context (.neon).",
+        type: "string",
+    },
+    database: {
+        alias: "db",
+        describe: "Limit the diff to a single database. Defaults to every database on the current branch.",
+        type: "string",
+    },
+})
+    .middleware(fillSingleProject)
+    .middleware((args) => {
+    // The positional arrives as `compare-branch`; surface it under the
+    // camelCase name the handler reads, and mirror it to `branchId` for
+    // analytics (same pattern as the `branches` command group).
+    const compareBranch = args["compare-branch"];
+    if (typeof compareBranch === "string") {
+        args.compareBranch = compareBranch;
+    }
+})
+    .example([
+    [
+        "$0 diff main",
+        "Diff the current branch's schema against the main branch",
+    ],
+    [
+        "$0 diff",
+        "Diff the current branch's schema against its parent branch",
+    ],
+    [
+        "$0 diff main --branch feature/checkout",
+        "Diff an explicit branch against main (ignoring the .neon context)",
+    ],
+    [
+        "$0 diff main --db neondb",
+        "Diff only the neondb database against main",
+    ],
+]);
+export const handler = async (props) => {
+    const branches = (await props.apiClient.listProjectBranches({
+        projectId: props.projectId,
+    })).data.branches;
+    const after = resolveAfterBranch(branches, props.branch);
+    const before = resolveBeforeBranch(branches, after, props.compareBranch);
+    if (before.branchId === after.branchId) {
+        throw new Error(`Nothing to compare: both sides resolve to branch ${after.branchName} (${after.branchId}).`);
+    }
+    const databases = await resolveDatabases(props, after);
+    const diffs = [];
+    for (const database of databases) {
+        const [beforeSql, afterSql] = await Promise.all([
+            fetchSchemaSql(props, before.branchId, database),
+            fetchSchemaSql(props, after.branchId, database),
+        ]);
+        diffs.push({
+            database,
+            before: { ...before, sql: beforeSql },
+            after: { ...after, sql: afterSql },
+        });
+    }
+    if (props.output === "json" || props.output === "yaml") {
+        writeStructured(props, diffs);
+        return;
+    }
+    log.info("%s Comparing schema %s → %s", chalk.dim("→"), chalk.red(`${before.branchName}`), chalk.green(`${after.branchName}`));
+    const { hasChanges, text } = renderSchemaDiffReport(diffs, {
+        color: props.color !== false,
+    });
+    if (!hasChanges) {
+        log.info("No schema differences between %s and %s.", before.branchName, after.branchName);
+        return;
+    }
+    writer(props).text(`${text}\n`);
+};
+/**
+ * Resolve the branch under review (`+++` side). Prefers the explicit
+ * `branch`/`--branch` value (name or `br-…` id), falling back to the project's
+ * default branch. An unknown `br-…` id is trusted as-is (it may be too new to
+ * appear in the listing); an unknown *name* is a hard error.
+ */
+const resolveAfterBranch = (branches, ref) => {
+    if (ref) {
+        return resolveRef(branches, ref);
+    }
+    const def = branches.find((b) => b.default);
+    if (!def) {
+        throw new Error("No branch specified and no default branch found. Pass --branch <name|id>.");
+    }
+    return { branchId: def.id, branchName: def.name ?? def.id };
+};
+/**
+ * Resolve the reference branch (`---` side). Uses the `compare-branch`
+ * positional when given, otherwise the parent of the branch under review — so a
+ * bare `neon diff` answers "what did I change since branching?".
+ */
+const resolveBeforeBranch = (branches, after, ref) => {
+    if (ref) {
+        return resolveRef(branches, ref);
+    }
+    const afterBranch = branches.find((b) => b.id === after.branchId);
+    const parentId = afterBranch?.parent_id;
+    if (!parentId) {
+        throw new Error(`Branch "${after.branchName}" has no parent to compare against. ` +
+            "Pass a branch to compare with, e.g. `neon diff main`.");
+    }
+    const parent = branches.find((b) => b.id === parentId);
+    return {
+        branchId: parentId,
+        branchName: parent?.name ?? parentId,
+    };
+};
+/** Resolve a branch reference (name or `br-…` id) against the fetched listing. */
+const resolveRef = (branches, ref) => {
+    const found = looksLikeBranchId(ref)
+        ? branches.find((b) => b.id === ref)
+        : branches.find((b) => b.name === ref);
+    if (found) {
+        return { branchId: found.id, branchName: found.name ?? found.id };
+    }
+    // A `br-…` id absent from the listing is still usable as an id; only an
+    // unresolved name is a genuine error (mirrors resolveBranchRef in enrichers).
+    if (looksLikeBranchId(ref)) {
+        return { branchId: ref, branchName: ref };
+    }
+    throw new Error(`Branch ${ref} not found.\nAvailable branches: ${branches
+        .map((b) => b.name)
+        .join(", ")}`);
+};
+/**
+ * The databases to diff: the one passed via `--database` (validated against the
+ * branch under review), or every database on that branch when none is given.
+ */
+const resolveDatabases = async (props, after) => {
+    const databases = (await props.apiClient.listProjectBranchDatabases(props.projectId, after.branchId)).data.databases;
+    if (props.database !== undefined) {
+        if (!databases.find((d) => d.name === props.database)) {
+            throw new Error(`Database "${props.database}" not found on branch ${after.branchName}. ` +
+                `Available: ${databases.map((d) => d.name).join(", ")}`);
+        }
+        return [props.database];
+    }
+    if (databases.length === 0) {
+        throw new Error(`No databases found on branch ${after.branchName} (${after.branchId}).`);
+    }
+    return databases.map((d) => d.name);
+};
+/**
+ * Fetch a branch database's `CREATE …` SQL. A database absent from the branch
+ * (404) yields an empty schema, so the diff shows it as fully added/removed
+ * rather than failing — the natural outcome when a database exists on only one
+ * side of the comparison.
+ */
+const fetchSchemaSql = async (props, branchId, database) => {
+    try {
+        const { data } = await props.apiClient.getProjectBranchSchema({
+            projectId: props.projectId,
+            branchId,
+            db_name: database,
+        });
+        return data.sql ?? "";
+    }
+    catch (err) {
+        if (isNeonApiError(err) && err.status === 404) {
+            log.debug("diff: database %s not found on branch %s; treating schema as empty", database, branchId);
+            return "";
+        }
+        throw err;
+    }
+};
+/** Machine-readable output for `--output json|yaml`: one entry per database. */
+const writeStructured = (props, diffs) => {
+    const report = diffs.map((diff) => {
+        const rendered = renderDatabaseSchemaDiff(diff, { color: false });
+        return {
+            database: diff.database,
+            base_branch: diff.before.branchName,
+            base_branch_id: diff.before.branchId,
+            compare_branch: diff.after.branchName,
+            compare_branch_id: diff.after.branchId,
+            has_changes: rendered.hasChanges,
+            diff: rendered.text,
+        };
+    });
+    writer(props).end(report, {
+        fields: [
+            "database",
+            "base_branch",
+            "compare_branch",
+            "has_changes",
+            "diff",
+        ],
+    });
+};

package/dist/commands/env.js

@@ -4,6 +4,7 @@ import chalk from "chalk";
 import { resolveNeonEnvVars } from "../dev/env.js";
 import { mergeEnvFile, readEnvFile, resolveEnvFilePath } from "../env_file.js";
 import { log } from "../log.js";
+import { warnAiGateway } from "../utils/ai_gateway_notice.js";
 import { announceTargetBranch } from "../utils/branch_notice.js";
 import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
 export const command = "env";
@@ -104,6 +105,20 @@ export const pull = async (props, opts = {}) => {
     if (removed.length > 0) {
         log.info("Removed %d stale Neon variable%s not enabled on this branch: %s", removed.length, removed.length === 1 ? "" : "s", removed.join(", "));
     }
+    // When the branch has the AI Gateway enabled, the pulled credentials always work, but
+    // serving is plan-gated and the model set can be reduced on the beta — surface that as a
+    // courtesy notice (best-effort; never fails the pull). The freshly pulled token lets us
+    // probe the branch's own /v1/models to detect a reduced catalog.
+    const gatewayBaseUrl = neonVars.NEON_AI_GATEWAY_BASE_URL;
+    const gatewayToken = neonVars.NEON_AI_GATEWAY_TOKEN;
+    if (gatewayBaseUrl && gatewayToken) {
+        await warnAiGateway({
+            apiClient: props.apiClient,
+            projectId: props.projectId,
+            branchId,
+            gateway: { baseUrl: gatewayBaseUrl, token: gatewayToken },
+        });
+    }
     return { status: "written", written, file: targetPath };
 };
 /**

package/dist/commands/index.js

@@ -10,6 +10,7 @@ import * as dataApi from "./data_api.js";
 import * as databases from "./databases.js";
 import * as deploy from "./deploy.js";
 import * as dev from "./dev.js";
+import * as diff from "./diff.js";
 import * as env from "./env.js";
 import * as functions from "./functions.js";
 import * as init from "./init.js";
@@ -47,6 +48,7 @@ export default [
     dataApi,
     functions,
     dev,
+    diff,
     config,
     status,
     deploy,

package/dist/index.js

@@ -31,6 +31,9 @@ const NO_SUBCOMMANDS_VERBS = [
     "init",
     "dev",
     "deploy",
+    // `diff <compare-branch>` has a handler but no subcommands (like `status`),
+    // so the help-fallback middleware must not intercept a bare `neon diff main`.
+    "diff",
     "bootstrap",
     // alias of `config status`
     "status",

package/dist/utils/ai_gateway_notice.js

@@ -0,0 +1,173 @@
+import { log } from "../log.js";
+/**
+ * Friendly guidance shown when a branch enables the AI Gateway (`preview.aiGateway`).
+ *
+ * The gateway is credential-gated, not provisioned: enabling it always mints a working
+ * branch credential, so `apply` / `checkout` / `env pull` succeed regardless of plan. The
+ * two things that *do* gate the gateway happen at serving time and are invisible in the
+ * provisioning result, so we surface them as a courtesy notice instead:
+ *
+ *  - **Free plan** — credentials provision, but the gateway does not *serve* model requests.
+ *    The account needs to upgrade to a paid plan.
+ *  - **Reduced model set** — on a paid plan, an account still ramping up on the beta gets a
+ *    trimmed model catalog (flagship models are missing from `/v1/models`). They can request
+ *    access to more models.
+ *
+ * This is deliberately phrased for the user: it never mentions account "verification" or any
+ * other internal gating mechanism.
+ */
+/**
+ * `BillingSubscriptionType` values that mean the account is on a Free plan (the gateway
+ * won't serve requests). Everything else — `launch`, `scale`, `business`, the `*_v3`
+ * variants, marketplace plans — is treated as paid.
+ */
+const FREE_SUBSCRIPTION_TYPES = new Set(["free_v2", "free_v3"]);
+/**
+ * The Neon Console billing page to upgrade a Free-plan account so the gateway can serve. It's
+ * org-scoped when the project belongs to an org; projects on a personal account (which is
+ * where Free plans usually live) have no org id, so we fall back to the account-level page.
+ */
+export const aiGatewayUpgradeUrl = (orgId) => orgId
+    ? `https://console.neon.tech/app/${orgId}/billing`
+    : "https://console.neon.tech/app/billing";
+/**
+ * The branch's AI Gateway page in the Neon Console — where a paid user with a reduced model
+ * set requests access to more models. It's branch-scoped, so it's built from the linked
+ * project and branch ids.
+ */
+export const aiGatewayModelsUrl = (projectId, branchId) => `https://console.neon.tech/app/projects/${projectId}/branches/${branchId}/ai-gateway`;
+export const isFreePlan = (subscriptionType) => subscriptionType !== undefined &&
+    FREE_SUBSCRIPTION_TYPES.has(subscriptionType);
+/**
+ * Whether a model catalog includes at least one flagship model. Flagship models (Anthropic
+ * Opus, OpenAI Codex / `*-pro`) are the first to be held back for an account still ramping
+ * up on the beta, so their total absence from a non-empty catalog is the signal that the
+ * account has a reduced model set. Matched by id substring so it survives model version
+ * bumps (e.g. `claude-opus-4-8`).
+ */
+export const hasFlagshipModels = (modelIds) => modelIds.some((id) => id.includes("opus") || id.includes("codex") || id.endsWith("-pro"));
+/**
+ * The message shown when a `neon.ts` that enables the AI Gateway is applied on a Free plan.
+ * Provisioning is refused up front (see {@link assertAiGatewayProvisionable}) because the
+ * gateway won't serve model requests until the account is on a paid plan. `upgradeUrl` is the
+ * org-scoped Console billing page (see {@link aiGatewayUpgradeUrl}).
+ */
+export const freePlanBlockMessage = (upgradeUrl) => "This neon.ts enables the AI Gateway, which isn't available on the Free plan — the " +
+    "gateway won't serve model requests. Upgrade to a paid plan and re-run, or remove " +
+    `\`preview.aiGateway\` from neon.ts. Upgrade here: ${upgradeUrl}`;
+/**
+ * Build the AI Gateway courtesy notice for an account's plan and (optionally) its live model
+ * catalog, or `null` when nothing needs saying.
+ *
+ * `modelIds` is `undefined` when the catalog wasn't probed (e.g. a dry-run `plan`, or a probe
+ * that failed); in that case only the plan-based (Free) notice can be produced — never a
+ * false "reduced models" warning. `upgradeUrl` is the org-scoped Console billing page
+ * (Free notice); `moreModelsUrl` is the branch's Console AI Gateway page
+ * (see {@link aiGatewayModelsUrl}), shown when the catalog is reduced.
+ */
+export const buildAiGatewayNotice = ({ subscriptionType, modelIds, upgradeUrl, moreModelsUrl, }) => {
+    if (isFreePlan(subscriptionType)) {
+        return {
+            level: "warning",
+            message: "AI Gateway is enabled, but the gateway does not serve model requests on the " +
+                `Free plan. Upgrade to a paid plan to start making requests: ${upgradeUrl}`,
+        };
+    }
+    if (modelIds !== undefined &&
+        modelIds.length > 0 &&
+        !hasFlagshipModels(modelIds)) {
+        return {
+            level: "warning",
+            message: "AI Gateway is in public beta and not every model is enabled for your account " +
+                "yet, so some models are missing from the catalog. Request access to more " +
+                `models here: ${moreModelsUrl}`,
+        };
+    }
+    return null;
+};
+const isRecord = (value) => typeof value === "object" && value !== null;
+/** Pull the string `id`s out of an OpenAI-compatible `{ object: "list", data: [...] }` body. */
+const extractModelIds = (body) => {
+    if (!isRecord(body) || !Array.isArray(body.data))
+        return null;
+    const ids = [];
+    for (const entry of body.data) {
+        if (isRecord(entry) && typeof entry.id === "string") {
+            ids.push(entry.id);
+        }
+    }
+    return ids;
+};
+/**
+ * `GET {baseUrl}/v1/models` → the served model ids, or `null` if the catalog can't be read
+ * (network / HTTP / parse failure). Returning `null` keeps the notice silent rather than
+ * risking a false "reduced models" warning. `/v1/models` is served only on the unified
+ * dialect (the `/openai/v1` Responses dialect returns 404).
+ */
+export const fetchGatewayModelIds = async (baseUrl, token) => {
+    try {
+        const res = await fetch(`${baseUrl.replace(/\/+$/, "")}/v1/models`, {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!res.ok)
+            return null;
+        return extractModelIds(await res.json());
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Refuse to provision the AI Gateway on a Free plan. Called before the `neon.ts` lifecycle
+ * commands provision a branch (`config apply` / `deploy`, `checkout`), so a Free-plan user
+ * gets a clear "upgrade first" error instead of a credential that can't serve requests.
+ *
+ * Best-effort on the plan lookup: if the plan can't be determined (network / API failure) we
+ * do NOT block, so a transient error never wrongly refuses a paid user's deploy. Only a
+ * positively-identified Free plan throws.
+ */
+export const assertAiGatewayProvisionable = async (params) => {
+    let subscriptionType;
+    let orgId;
+    try {
+        const { data } = await params.apiClient.getProject(params.projectId);
+        subscriptionType = data.project.owner?.subscription_type;
+        orgId = data.project.org_id ?? undefined;
+    }
+    catch {
+        return; // Can't determine the plan — don't block.
+    }
+    if (isFreePlan(subscriptionType)) {
+        throw new Error(freePlanBlockMessage(aiGatewayUpgradeUrl(orgId)));
+    }
+};
+/**
+ * Resolve the account's plan (and, when gateway credentials are on hand, its live model
+ * catalog) and print the AI Gateway courtesy notice — used by the `neon.ts` lifecycle and
+ * `env pull` whenever a branch has the gateway enabled.
+ *
+ * Pass `gateway` (base URL + token) to enable the reduced-model-set check; omit it (e.g. a
+ * dry-run `plan`) to get only the Free-plan notice. This is best-effort: any failure while
+ * fetching the plan or catalog is swallowed so it can never break the underlying command.
+ */
+export const warnAiGateway = async (params) => {
+    try {
+        const { data } = await params.apiClient.getProject(params.projectId);
+        const subscriptionType = data.project.owner?.subscription_type;
+        const orgId = data.project.org_id ?? undefined;
+        const modelIds = params.gateway
+            ? ((await fetchGatewayModelIds(params.gateway.baseUrl, params.gateway.token)) ?? undefined)
+            : undefined;
+        const notice = buildAiGatewayNotice({
+            subscriptionType,
+            modelIds,
+            upgradeUrl: aiGatewayUpgradeUrl(orgId),
+            moreModelsUrl: aiGatewayModelsUrl(params.projectId, params.branchId),
+        });
+        if (notice)
+            log.warning(notice.message);
+    }
+    catch {
+        // A courtesy notice must never break the command that triggered it.
+    }
+};

package/dist/utils/config_diff.js

@@ -0,0 +1,179 @@
+import chalk from "chalk";
+const UNSET = "(unset)";
+/**
+ * Shared palette for the config diff, matching `neon diff`'s `git diff` styling
+ * (bold headers, red "before", green "after", dim connective glyphs). When
+ * `color` is false every entry is the identity function, so the identical layout
+ * renders without ANSI codes for `--no-color`, non-TTY pipes, and test snapshots.
+ */
+const palette = (color) => {
+    const id = (s) => s;
+    if (!color) {
+        return { title: id, group: id, added: id, removed: id, arrow: id };
+    }
+    return {
+        title: (s) => chalk.bold(s),
+        group: (s) => chalk.bold(s),
+        added: (s) => chalk.green(s),
+        removed: (s) => chalk.red(s),
+        arrow: (s) => chalk.dim(s),
+    };
+};
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const stringifyValue = (value) => {
+    if (value === undefined || value === null || value === "")
+        return UNSET;
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "boolean" || typeof value === "number") {
+        return String(value);
+    }
+    return JSON.stringify(value);
+};
+/**
+ * Expand one policy field into flat {@link FieldChange}s. When either side is a
+ * plain object (compute settings, Data API settings) it splits into one
+ * `field.key` entry per key across both sides, so the diff reads as sorted
+ * scalar lines (`computeSettings.autoscalingLimitMaxCu  2 → 4`) rather than an
+ * opaque JSON blob. Scalars produce a single entry.
+ */
+const expandField = (field, current, desired) => {
+    if (isPlainObject(current) || isPlainObject(desired)) {
+        const cur = isPlainObject(current) ? current : {};
+        const des = isPlainObject(desired) ? desired : {};
+        const keys = Array.from(new Set([...Object.keys(cur), ...Object.keys(des)])).sort();
+        return keys.map((key) => ({
+            field: `${field}.${key}`,
+            ...(key in cur ? { current: stringifyValue(cur[key]) } : {}),
+            desired: stringifyValue(des[key]),
+        }));
+    }
+    return [
+        {
+            field,
+            ...(current !== undefined
+                ? { current: stringifyValue(current) }
+                : {}),
+            desired: stringifyValue(desired),
+        },
+    ];
+};
+/** Render the indented `field  current → desired` lines for one branch group. */
+const renderFieldLines = (fields, paint) => {
+    const width = fields.reduce((max, f) => Math.max(max, f.field.length), 0);
+    return fields.map((f) => {
+        const name = f.field.padEnd(width);
+        const arrow = paint.arrow("→");
+        return f.current !== undefined
+            ? `      ${name}  ${paint.removed(f.current)} ${arrow} ${paint.added(f.desired)}`
+            : `      ${name}  ${arrow} ${paint.added(f.desired)}`;
+    });
+};
+/** Group field changes by branch, each block sorted alphabetically by field. */
+const renderBranchGroups = (byBranch, paint) => {
+    const lines = [];
+    const groups = [...byBranch.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+    for (const [branch, fields] of groups) {
+        const sorted = [...fields].sort((a, b) => a.field.localeCompare(b.field));
+        lines.push(`  ${paint.group(`~ ${branch}`)}`);
+        lines.push(...renderFieldLines(sorted, paint));
+    }
+    return lines;
+};
+/** Friendly label for a service change identifier (`bucket:x` → `bucket x`). */
+const serviceLabel = (identifier) => {
+    if (identifier === "auth")
+        return "Neon Auth";
+    if (identifier === "dataApi")
+        return "Data API";
+    if (identifier.startsWith("bucket:")) {
+        return `bucket ${identifier.slice("bucket:".length)}`;
+    }
+    if (identifier.startsWith("function:")) {
+        return `function ${identifier.slice("function:".length)}`;
+    }
+    return identifier;
+};
+/**
+ * The desired-only field changes for an applied/planned **branch** update. The
+ * synthesized `AppliedChange.details` carry the new value keyed by `field`
+ * (`ttl`→`expiresAt`, `protected`→`protected`, `computeSettings`→`settings`);
+ * the previous value isn't threaded through in Phase 1, so these render as
+ * `field → desired` (no red "before"). Object settings expand into sub-fields.
+ */
+const appliedBranchFields = (change) => {
+    const details = change.details ?? {};
+    const field = typeof details.field === "string" ? details.field : "setting";
+    switch (field) {
+        case "ttl":
+            return expandField("ttl", undefined, details.expiresAt);
+        case "protected":
+            return expandField("protected", undefined, details.protected);
+        case "computeSettings":
+            return expandField("computeSettings", undefined, details.settings);
+        default:
+            return expandField(field, undefined, details.settings);
+    }
+};
+/**
+ * Render the applied (or planned) changes as a `git diff`-style list:
+ *
+ * - **Service changes** (auth / Data API / buckets / functions) are additions
+ *   with no meaningful "before", so they list as green `+ <label>` lines
+ *   (`~ <label>` for the lone Data API settings *update*).
+ * - **Branch setting changes** group per branch and render as sorted
+ *   `field → value` lines under a `~ <branch>` header.
+ *
+ * Returns "" when there is nothing to show. Pure — callers own the heading
+ * spacing and any surrounding summary.
+ */
+export const renderAppliedChanges = (changes, title, opts) => {
+    if (changes.length === 0)
+        return "";
+    const paint = palette(opts.color);
+    const lines = [paint.title(title)];
+    const services = changes
+        .filter((c) => c.kind === "service")
+        .sort((a, b) => a.identifier.localeCompare(b.identifier));
+    for (const service of services) {
+        const label = serviceLabel(service.identifier);
+        lines.push(service.action === "create"
+            ? `  ${paint.added(`+ ${label}`)}`
+            : `  ${paint.arrow(`~ ${label}`)}`);
+    }
+    const byBranch = new Map();
+    for (const change of changes.filter((c) => c.kind === "branch")) {
+        const existing = byBranch.get(change.identifier) ?? [];
+        byBranch.set(change.identifier, [
+            ...existing,
+            ...appliedBranchFields(change),
+        ]);
+    }
+    lines.push(...renderBranchGroups(byBranch, paint));
+    return lines.join("\n");
+};
+/**
+ * Render branch-setting **conflicts** (drift the policy wants to change but that
+ * needs `--update-existing`) as a `git diff`-style before→after report: grouped
+ * per branch, sorted by field, `current → desired` with the old value in red and
+ * the new in green. Conflicts already carry both sides, so this is the fullest
+ * form of the diff. Returns "" when there are no conflicts.
+ */
+export const renderBranchSettingConflicts = (conflicts, opts) => {
+    if (conflicts.length === 0)
+        return "";
+    const paint = palette(opts.color);
+    const byBranch = new Map();
+    for (const conflict of conflicts) {
+        const existing = byBranch.get(conflict.identifier) ?? [];
+        byBranch.set(conflict.identifier, [
+            ...existing,
+            ...expandField(conflict.field, conflict.current, conflict.desired),
+        ]);
+    }
+    const lines = [
+        paint.title("Branch settings differ (re-run with --update-existing to apply)"),
+        ...renderBranchGroups(byBranch, paint),
+    ];
+    return lines.join("\n");
+};

package/dist/utils/git_diff.js

@@ -0,0 +1,90 @@
+import chalk from "chalk";
+import { structuredPatch } from "diff";
+/**
+ * Color palette for the rendered diff. When `color` is false every entry is the
+ * identity function, so the exact same layout is emitted without ANSI codes
+ * (for `--no-color`, non-TTY pipes, and stable test snapshots).
+ */
+const palette = (color) => {
+    const id = (s) => s;
+    if (!color) {
+        return {
+            header: id,
+            removedFile: id,
+            addedFile: id,
+            hunk: id,
+            added: id,
+            removed: id,
+            noNewline: id,
+        };
+    }
+    return {
+        header: (s) => chalk.bold(s),
+        removedFile: (s) => chalk.bold.red(s),
+        addedFile: (s) => chalk.bold.green(s),
+        hunk: (s) => chalk.cyan(s),
+        added: (s) => chalk.green(s),
+        removed: (s) => chalk.red(s),
+        noNewline: (s) => chalk.dim(s),
+    };
+};
+const branchLabel = (schema) => `${schema.branchName} (${schema.branchId})`;
+/**
+ * Render a single database's schema comparison as a git-style unified diff.
+ *
+ * Pure: given the two schemas it computes hunks with `diff`'s `structuredPatch`
+ * and lays them out like `git diff` — a bold header, red `---` / green `+++`
+ * branch lines, cyan `@@` hunk headers, and green/red line bodies. Returns
+ * `hasChanges: false` with empty text when the two schemas are identical.
+ */
+export const renderDatabaseSchemaDiff = (diff, opts) => {
+    const patch = structuredPatch(diff.database, diff.database, diff.before.sql, diff.after.sql, "", "", { context: 3 });
+    if (patch.hunks.length === 0) {
+        return { database: diff.database, hasChanges: false, text: "" };
+    }
+    const paint = palette(opts.color);
+    const lines = [
+        paint.header(`diff --neon database ${diff.database}`),
+        paint.removedFile(`--- ${branchLabel(diff.before)}`),
+        paint.addedFile(`+++ ${branchLabel(diff.after)}`),
+    ];
+    for (const hunk of patch.hunks) {
+        lines.push(paint.hunk(`@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`));
+        for (const line of hunk.lines) {
+            // `structuredPatch` prefixes every line: '+' added, '-' removed,
+            // ' ' unchanged context, and '\' for the "No newline at end of file"
+            // marker. Color the first three; dim the marker; leave context plain.
+            if (line.startsWith("+")) {
+                lines.push(paint.added(line));
+            }
+            else if (line.startsWith("-")) {
+                lines.push(paint.removed(line));
+            }
+            else if (line.startsWith("\\")) {
+                lines.push(paint.noNewline(line));
+            }
+            else {
+                lines.push(line);
+            }
+        }
+    }
+    return {
+        database: diff.database,
+        hasChanges: true,
+        text: lines.join("\n"),
+    };
+};
+/**
+ * Render every database's diff into one report, keeping only databases whose
+ * schema actually changed. `hasChanges` is false when nothing changed across
+ * all databases, letting the caller print a single "no differences" note.
+ */
+export const renderSchemaDiffReport = (diffs, opts) => {
+    const rendered = diffs.map((diff) => renderDatabaseSchemaDiff(diff, opts));
+    const changed = rendered.filter((r) => r.hasChanges);
+    return {
+        hasChanges: changed.length > 0,
+        text: changed.map((r) => r.text).join("\n\n"),
+        changedDatabases: changed.map((r) => r.database),
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neonctl",
-  "version": "2.31.1",
+  "version": "2.33.0",
   "description": "CLI tool for Neon Serverless Postgres",
   "keywords": [
     "neon",
@@ -42,7 +42,7 @@
     "cliui": "8.0.1",
     "diff": "5.2.0",
     "fflate": "^0.8.3",
-    "neon-init": "0.20.0",
+    "neon-init": "0.20.1",
     "open": "^10.2.0",
     "openid-client": "6.8.1",
     "pg-protocol": "^1.14.0",
@@ -51,10 +51,10 @@
     "which": "3.0.1",
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
-    "@neon/sdk": "1.1.0",
-    "@neon/config": "0.9.2",
-    "@neon/config-runtime": "0.9.2",
-    "@neon/env": "0.11.1"
+    "@neon/sdk": "1.1.1",
+    "@neon/config": "0.9.3",
+    "@neon/config-runtime": "0.9.3",
+    "@neon/env": "0.11.2"
   },
   "optionalDependencies": {
     "esbuild": "0.28.1"