neon 2.46.0 → 2.47.0

package/README.md

@@ -417,9 +417,15 @@ The human-readable summary line goes to stderr and the diff body to stdout, so `
 
 ### 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).
+`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 are written (see the table below); 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).
 
-`link` and `checkout` invoke `env pull` automatically (see above), so you usually only run it by hand to refresh vars or to pull a different branch into a specific file:
+**What gets pulled**, in precedence order:
+
+1. **`--service`**, when you pass it — exactly those services, whatever else is on the branch and whatever a `neon.ts` says.
+2. **`neon.ts`**, when the working directory has one — the policy is the source of truth, same as `neon dev` and `neon deploy`.
+3. **Everything the branch has** otherwise — Postgres, Neon Auth, the Data API, and object storage read back from the branch, plus the AI Gateway. The gateway has no branch-level state to read back (it is credential-gated, not provisioned), so a bare `env pull` asks for it rather than detecting it, which mints a branch credential. To leave it out, name the services you do want with `--service`.
+
+If the gateway can't be resolved, it is dropped with a warning and the rest of the pull still lands. Gateway variables already in your file for *this* branch are left alone — a pull that couldn't reach the gateway is no evidence the branch has stopped having one — while ones left over from a different branch are pruned like any other stale value.
 
 ```bash
 # Refresh the linked branch's vars in place
@@ -427,10 +433,45 @@ neon env pull
 
 # Pull a specific branch into a specific file
 neon env pull --branch preview --file .env.preview
+
+# Only the AI Gateway
+neon env pull --service ai-gateway
+
+# Repeat the flag or comma-separate; -s, --service and --services are all accepted
+neon env pull -s postgres -s data-api
+neon env pull -s postgres,auth
+```
+
+Every services flag in the CLI takes those three spellings, the same value syntax, and the same service names — see [`config init --services`](#getting-a-neonts-config-init).
+
+| `--service` | Variables |
+| --- | --- |
+| `postgres` | `DATABASE_URL`, `DATABASE_URL_UNPOOLED` |
+| `auth` | `NEON_AUTH_BASE_URL`, `NEON_AUTH_JWKS_URL` |
+| `data-api` | `NEON_DATA_API_URL` |
+| `object-storage` | `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ENDPOINT_URL_S3`, `AWS_REGION` |
+| `ai-gateway` | `NEON_AI_GATEWAY_TOKEN`, `NEON_AI_GATEWAY_BASE_URL` |
+
+`NEON_BRANCH` is written by every pull — it is branch identity, not a service.
+
+**A scoped pull is scoped in both directions.** An unscoped `env pull` owns the Neon-named variables: pointing a directory at a branch without Neon Auth prunes the stale `NEON_AUTH_*` lines. `--service` narrows that to the services you named, so `env pull -s ai-gateway` never touches your `DATABASE_URL`. (`AWS_*` is never pruned by any pull: those names collide with credentials you may set yourself, so `env pull` only ever writes them.)
+
+**A scoped pull also never revokes a credential.** Where an unscoped pull revokes the credential it replaces, a scoped one leaves the old one live — it can't tell which other services still use it. It says so when it happens; revoke it in the Neon Console if nothing does.
+
+Naming a service the branch does not have is an error, not an empty pull:
+
+```
+--service auth: branch br-snowy-frost-12345 has no Neon Auth integration, so there are no
+auth env vars to pull. Provision it first (`neon deploy`, `neon config apply`, or the Neon
+Console), or drop auth from --service.
 ```
 
+`link`, `checkout`, and `config apply` invoke `env pull` automatically (see above). Those bundled pulls follow rules 2 and 3 above **without** the implied AI Gateway: minting a credential for a service you never named isn't something a side effect of another command should do. Run `neon env pull` to get it.
+
 If you'd rather not keep env vars on disk, inject them at runtime instead with `neon-env run -- <your dev command>` (from `@neon/env`) or `neon dev`, and pass `--no-env-pull` to `link` / `checkout`.
 
+**`neon dev` resolves the same set, by the same rules** — including the AI Gateway on a branch with no `neon.ts`. A function running locally gets what the deployed runtime would inject into it, which is the whole point of `dev`; a handler that reads `NEON_AI_GATEWAY_BASE_URL` should not work in production and fail on your machine. `dev` writes nothing, but it does *read* your `.env` / `.env.local` to reuse the branch credential behind the AI Gateway and object storage. Without a file to read from it issues one on every start and leaves the last one live — it has nowhere to keep it, and so cannot name it to revoke it. It says so when it happens; run `env pull` (or just `link` / `checkout`) once and restarts reuse the credential instead.
+
 **Where `.neon` lives**: `link` writes `.neon` into the **current working directory** by default. If an existing `.neon` is found in any parent directory, that file is reused — so commands run from a sub-directory of a linked project still pick up the project's context. To pin the location explicitly, pass `--context-file <path>`.
 
 **`.gitignore` scaffolding**: when `.neon` is **created** for the first time, the CLI also makes sure a `.gitignore` sits alongside it listing `.neon`. If `.gitignore` doesn't exist it's created with a single `.neon` line; if it does exist, `.neon` is appended only when missing (no duplicates, your other entries are left alone). On subsequent updates to an existing `.neon`, `.gitignore` is left untouched — so if you deliberately un-ignore `.neon` (e.g. to commit shared context), the entry is not re-added on every command.
@@ -479,7 +520,10 @@ Selecting nothing is a valid answer: you get the starter policy, which is also w
 neon config init
 
 # Declare services with no prompt
-neon config init --services auth,functions,storage,ai-gateway
+neon config init --services auth,functions,object-storage,ai-gateway
+
+# Repeat the flag instead, and shorten it — every services flag takes all three spellings
+neon config init -s auth -s functions
 
 # Explicitly ask for the bare starter policy
 neon config init --services none
@@ -488,6 +532,8 @@ neon config init --services none
 neon config init --no-install
 ```
 
+Object storage is spelled `object-storage` here, matching [`env pull --service`](#env-pull) and the rest of the CLI. The old `storage` still works and warns; it will be removed.
+
 Choosing **Functions** also writes the handler the policy points at, since `source` is only resolved when `apply` bundles it — a declared function with no file on disk fails at deploy:
 
 ```ts

package/dist/analytics.js

@@ -1,5 +1,5 @@
 import { Analytics } from "@segment/analytics-node";
-import { inspectCredentials } from "./_shared/credentials.js";
+import { inspectCredentials, OAUTH } from "./_shared/credentials.js";
 import { getApiClient, isNeonApiError } from "./api.js";
 import { getAuthContext } from "./auth_context.js";
 import { credentialsPath } from "./config.js";
@@ -14,6 +14,63 @@ const WRITE_KEY = "3SQXn5ejjXWLEJ8xU2PRYhAotLtTaeeV";
  * not be populated yet, so we also scan `process.argv` directly to be safe.
  */
 const hasCurrentBranchArgv = () => process.argv.includes("--current-branch");
+const ANONYMOUS = "anonymous";
+/**
+ * Who to attribute an event to, given whatever identified this invocation.
+ *
+ * Nothing is guaranteed to have identified it: a command can run with no credentials at all,
+ * leaving the id empty. Segment accepts an empty `userId` and forwards it as-is rather than
+ * rejecting it, so the substitution has to happen here. `""` is falsy but not nullish, which
+ * is why the fallback has to be `||`.
+ *
+ * Exported for tests.
+ */
+export const analyticsUserId = (userId) => userId || ANONYMOUS;
+/**
+ * The account an invocation that presented no API key may claim, which is nothing at all
+ * unless stored credentials named a user.
+ *
+ * Both fields are omitted together. An empty account reported under a named method describes
+ * an authentication that did not happen, which is worse than reporting neither.
+ *
+ * Exported for tests.
+ */
+export const storedCredentialAttribution = (storedUserId) => storedUserId ? { accountId: storedUserId, authMethod: OAUTH } : {};
+/**
+ * Which credential telemetry may describe this invocation with.
+ *
+ * `ensureAuth` records a context only when it selected a credential for this invocation, so a
+ * missing context means the global auth middleware selected nothing before this ran. A key
+ * sitting in `args.apiKey` is then not the credential the middleware chose — `neon profile list`
+ * never used it — and must not be queried on its behalf, which would attribute the run to an
+ * account it never authenticated as and add a telemetry-only API call. The local default is the
+ * guess.
+ *
+ * The boundary is deliberately the credential the middleware selected, not every key a handler
+ * may go on to use. Several `profile` subcommands authenticate inside their own handlers —
+ * `create --api-key` verifies the key it is about to store, `rotate-key` mints and revokes — and
+ * those runs are attributed to the local default rather than to the account the handler talked
+ * to. Attributing them to that key puts an `identify` for the signed-in user beside an
+ * `accountId` for a different account.
+ *
+ * A selected key records no file, because it authenticates as its own account rather than out
+ * of one. Reading `DEFAULT` for it would identify the run as whoever is signed in locally, and
+ * that borrowed id would suppress the API lookup that names the key's real owner.
+ *
+ * Exported for tests.
+ */
+export const telemetryCredential = (authContext, apiKey, defaultCredentialsPath) => {
+    if (authContext === null) {
+        return { credentialsPath: defaultCredentialsPath };
+    }
+    if (authContext.source === "api-key") {
+        return { apiKey };
+    }
+    return {
+        apiKey,
+        credentialsPath: authContext.credentialsPath ?? defaultCredentialsPath,
+    };
+};
 let client;
 let clientInitialized = false;
 let userId = "";
@@ -42,7 +99,7 @@ export const initAnalyticsClientMiddleware = (args) => {
     });
     log.debug("Initialized CLI analytics client");
     client.identify({
-        userId: "anonymous",
+        userId: ANONYMOUS,
     });
 };
 /**
@@ -56,28 +113,27 @@ export const analyticsMiddleware = async (args) => {
     if (isCurrentBranchProbe(args)) {
         return;
     }
-    // Read the credentials this invocation actually authenticated with, which `ensureAuth`
-    // recorded. Reading `DEFAULT`'s unconditionally attributed every `--profile`-selected
-    // command to whichever account happened to be the default one.
-    const authenticatedAs = getAuthContext()?.credentialsPath ?? credentialsPath(args.configDir);
-    // Telemetry must never turn a damaged or unreadable credentials file into a failed command.
-    try {
-        const read = inspectCredentials(authenticatedAs);
-        if (read.kind === "ok" &&
-            typeof read.credentials.user_id === "string") {
-            userId = read.credentials.user_id;
+    const { apiKey: keyToQuery, credentialsPath: fileToRead } = telemetryCredential(getAuthContext(), args.apiKey, credentialsPath(args.configDir));
+    if (fileToRead !== undefined) {
+        // Telemetry must never turn a damaged or unreadable credentials file into a failed command.
+        try {
+            const read = inspectCredentials(fileToRead);
+            if (read.kind === "ok" &&
+                typeof read.credentials.user_id === "string") {
+                userId = read.credentials.user_id;
+            }
+            else if (read.kind !== "ok") {
+                log.debug("No usable credentials at %s", fileToRead);
+            }
         }
-        else if (read.kind !== "ok") {
-            log.debug("No usable credentials at %s", authenticatedAs);
+        catch (err) {
+            log.debug("Could not read %s: %s", fileToRead, err);
         }
     }
-    catch (err) {
-        log.debug("Could not read %s: %s", authenticatedAs, err);
-    }
     try {
-        if (args.apiKey) {
+        if (keyToQuery) {
             const apiClient = getApiClient({
-                apiKey: args.apiKey,
+                apiKey: keyToQuery,
                 apiHost: args.apiHost,
             });
             // Populating api key details for analytics
@@ -93,18 +149,19 @@ export const analyticsMiddleware = async (args) => {
             }
         }
         else {
-            args.accountId = userId;
-            args.authMethod = "oauth";
+            const { accountId, authMethod } = storedCredentialAttribution(userId);
+            args.accountId = accountId;
+            args.authMethod = authMethod;
         }
     }
     catch (err) {
         log.debug("Failed to get user id from api", err);
     }
     client.identify({
-        userId: userId?.toString() ?? "anonymous",
+        userId: analyticsUserId(userId),
     });
     client.track({
-        userId: userId || "anonymous",
+        userId: analyticsUserId(userId),
         event: "CLI Started",
         properties: getAnalyticsEventProperties(args),
         context: {
@@ -145,7 +202,7 @@ export const sendError = (err, errCode) => {
     }
     client.track({
         event: "CLI Error",
-        userId: userId || "anonymous",
+        userId: analyticsUserId(userId),
         properties: getErrorAnalyticsEventProperties(err, errCode, errorEventContext),
     });
     log.debug("Sent CLI error event: %s", errCode);
@@ -156,7 +213,7 @@ export const trackEvent = (event, properties) => {
     }
     client.track({
         event,
-        userId: userId || "anonymous",
+        userId: analyticsUserId(userId),
         properties,
     });
     log.debug("Sent CLI event: %s", event);

package/dist/commands/config.js

@@ -5,11 +5,12 @@ import { apply, createBranch as createBranchFromPolicy, inspect, isPartialBranch
 import chalk from "chalk";
 import { getApiClient } from "../api.js";
 import { toNeonConfigView } from "../config_format.js";
-import { FUNCTION_FILENAME, FUNCTION_SLUG, FUNCTION_TEMPLATE, NEON_SERVICES, NO_SERVICES, parseServices, REQUIRED_PACKAGES, renderNeonConfig, renderNeonConfigFromView, } from "../config_template.js";
+import { CONFIG_INIT_NONE_MEANS, CONFIG_INIT_SERVICES, CONFIG_INIT_UNAVAILABLE, FUNCTION_FILENAME, FUNCTION_SLUG, FUNCTION_TEMPLATE, REQUIRED_PACKAGES, renderNeonConfig, renderNeonConfigFromView, } from "../config_template.js";
 import { contextBranch, readContextFile } from "../context.js";
 import { isCi } from "../env.js";
 import { loadEnvFileIntoProcess } from "../env_file.js";
 import { log } from "../log.js";
+import { deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOption, } from "../neon_services.js";
 import { assertAiGatewayProvisionable, warnAiGateway, } from "../utils/ai_gateway_notice.js";
 import { announceTargetBranch } from "../utils/branch_notice.js";
 import { getCliName } from "../utils/cli_name.js";
@@ -120,7 +121,13 @@ const missingDependencies = (cwd) => {
  */
 const resolveServices = async (props) => {
     if (props.services !== undefined) {
-        return parseServices(props.services);
+        return parseServices(props.services, {
+            allowed: CONFIG_INIT_SERVICES,
+            whyUnavailable: CONFIG_INIT_UNAVAILABLE,
+            flag: "--services",
+            noneMeans: CONFIG_INIT_NONE_MEANS,
+            onDeprecated: (used, canonical) => log.warning(deprecatedServiceMessage(used, canonical)),
+        });
     }
     if (props.pickServices) {
         return props.pickServices();
@@ -217,7 +224,7 @@ export const initCmd = async (props) => {
         log.info("%s are already installed.", REQUIRED_PACKAGES.join(" and "));
     }
     else {
-        const pm = resolvePackageManager();
+        const pm = resolvePackageManager(cwd);
         const args = addDependenciesArgs(pm, missing);
         if (props.install === false) {
             log.info("Install the Neon config packages to use neon.ts: %s %s", pm, args.join(" "));
@@ -285,12 +292,14 @@ export const builder = (argv) => argv
         type: "boolean",
         default: true,
     },
-    services: {
-        describe: `Services the scaffolded neon.ts declares, comma-separated: ${NEON_SERVICES.join(", ")}. ` +
-            `Pass "${NO_SERVICES}" for the bare starter policy. Omitted: pick interactively on a ` +
-            "terminal, starter policy in CI or without a TTY.",
-        type: "string",
-    },
+    services: servicesOption({
+        key: "services",
+        allowed: CONFIG_INIT_SERVICES,
+        noneMeans: CONFIG_INIT_NONE_MEANS,
+        describe: "Services the scaffolded neon.ts declares",
+        also: "Omitted: pick interactively on a terminal, starter policy in " +
+            "CI or without a TTY.",
+    }),
     "from-branch": {
         describe: "Seed neon.ts from a branch's live Neon state instead of asking. Uses the " +
             "branch pinned in .neon, or --branch <name|id>, or the project's default " +
@@ -300,7 +309,12 @@ export const builder = (argv) => argv
         // `default: false` makes `conflicts` reject every `--services` run.
         conflicts: "services",
     },
-}), (args) => initCmd(args));
+}), (args) => initCmd({
+    ...args,
+    // `args` is untyped here, and "flag omitted" has to stay distinct from
+    // "flag given" — it decides whether the picker runs at all.
+    services: servicesFlagValue(args.services),
+}));
 export const handler = (args) => {
     return args;
 };

package/dist/commands/dev.js

@@ -7,7 +7,9 @@ import chalk from "chalk";
 import { resolveDevEnv } from "../dev/env.js";
 import { resolveFunctionsFromConfig, } from "../dev/functions.js";
 import { resolveWatchInputs } from "../dev/inputs.js";
+import { readEnvFile, resolveEnvFilePath } from "../env_file.js";
 import { log } from "../log.js";
+import { getCliName } from "../utils/cli_name.js";
 import { branchIdResolve } from "../utils/enrichers.js";
 import { bundleEntry } from "../utils/esbuild.js";
 export const command = "dev";
@@ -30,7 +32,68 @@ export const builder = (argv) => argv
         type: "number",
     },
 })
+    .epilogue([
+    "",
+    "Functions run with the linked branch's Neon env injected, the same set the",
+    "deployed runtime gives them: DATABASE_URL, plus Neon Auth, the Data API,",
+    "object storage and the AI Gateway where the branch has them. A neon.ts in",
+    "this directory decides instead, exactly as it does for `env pull`.",
+    "",
+    "`dev` reads your .env / .env.local to reuse the branch credential behind the",
+    "AI Gateway and object storage, and never writes to them. With no such file it",
+    "issues a credential on every start, so run `env pull` once if you restart often.",
+].join("\n"))
     .strict();
+/**
+ * The resolver context for a `neon dev` run.
+ *
+ * Two things here are what make local dev match the deployed runtime, which injects a
+ * branch's whole env into a function:
+ *
+ * - **The AI Gateway is asked for**, like `env pull` does, because nothing can detect it.
+ *   Without this, a function that works deployed fails locally with no `NEON_AI_GATEWAY_*`,
+ *   which is exactly the difference `dev` exists to eliminate.
+ * - **The local dotenv file is layered in**, so the branch credential behind the gateway and
+ *   object storage is *reused* rather than re-minted. `dev` writes no file of its own, so
+ *   without a source of persisted secrets every start would mint a credential and leave the
+ *   last one live — one orphan per restart. `neon-env run` already reads the file for this
+ *   reason; `dev` was the one that didn't.
+ */
+export const devEnvContext = (props, branchId, cwd) => {
+    const envFile = resolveEnvFilePath(cwd);
+    return {
+        cwd,
+        implyAiGateway: true,
+        env: {
+            ...process.env,
+            ...(existsSync(envFile) ? readEnvFile(envFile) : {}),
+        },
+        ...(props.projectId ? { projectId: props.projectId } : {}),
+        ...(branchId ? { branchId } : {}),
+        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
+        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
+    };
+};
+/**
+ * Say when a run issued a branch credential.
+ *
+ * `dev` has nowhere to persist one — it writes no file — so on a branch with nothing to reuse
+ * it mints per start and cannot name the previous one to revoke it. Every other command that
+ * mints says so; this is the one that runs dozens of times a day, and the server banner listing
+ * `NEON_AI_GATEWAY_TOKEN` reads as "fetched", not "just created, and the last one is still
+ * live". The note names the one action that stops it, so it disappears once followed.
+ */
+export const reportDevCredential = (credential) => {
+    if (!credential?.issued)
+        return;
+    if (credential.revoked.length > 0) {
+        log.info("Issued a new branch credential — %s changed. Revoked the one it replaced (%s).", credential.keys.join(", "), credential.revoked.join(", "));
+        return;
+    }
+    log.warning("Issued a branch credential for this run (%s) and left any previous one live — a dev " +
+        `server has nowhere to keep it. Run \`${getCliName()} env pull\` once to write it to ` +
+        "your .env, and restarts will reuse it instead of issuing another.", credential.keys.join(", "));
+};
 export const handler = async (props) => {
     if (props.source !== undefined) {
         await runSingleSource(props);
@@ -51,13 +114,8 @@ const runSingleSource = async (props) => {
         throw new Error(`Source file not found: ${source}`);
     }
     const branchId = await resolveBranchId(props);
-    const { vars: neonEnv, skipped } = await resolveDevEnv({
-        cwd: process.cwd(),
-        ...(props.projectId ? { projectId: props.projectId } : {}),
-        ...(branchId ? { branchId } : {}),
-        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
-        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
-    });
+    const { vars: neonEnv, skipped, credential, } = await resolveDevEnv(devEnvContext(props, branchId, process.cwd()));
+    reportDevCredential(credential);
     const unit = {
         slug: null,
         source,
@@ -89,13 +147,8 @@ const runFromConfig = async (props) => {
         throw new Error("neon.ts has no functions to serve. Add at least one under " +
             "`preview.functions`, or pass --source <path>.");
     }
-    const { vars: neonEnv, skipped } = await resolveDevEnv({
-        cwd: process.cwd(),
-        ...(props.projectId ? { projectId: props.projectId } : {}),
-        ...(branchId ? { branchId } : {}),
-        ...(props.apiKey ? { apiKey: props.apiKey } : {}),
-        ...(props.apiHost ? { apiHost: props.apiHost } : {}),
-    });
+    const { vars: neonEnv, skipped, credential, } = await resolveDevEnv(devEnvContext(props, branchId, process.cwd()));
+    reportDevCredential(credential);
     const units = planFunctionsToUnits(functions, neonEnv, DEFAULT_PORT_BASE);
     // Re-derive the units from neon.ts on demand so the config watcher can hot-add/remove
     // functions without restarting the dev server. `searchBase` lets a freshly-added unit

package/dist/commands/env.js

@@ -4,7 +4,9 @@ import chalk from "chalk";
 import { ensureGitignored } from "../context.js";
 import { resolveNeonEnvVars } from "../dev/env.js";
 import { mergeEnvFile, readEnvFile, resolveEnvFilePath } from "../env_file.js";
+import { ENV_PULL_SERVICES, ENV_PULL_UNAVAILABLE, envServiceKeys, ownedEnvServiceKeys, } from "../env_services.js";
 import { log } from "../log.js";
+import { deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOption, } from "../neon_services.js";
 import { warnAiGateway } from "../utils/ai_gateway_notice.js";
 import { announceTargetBranch } from "../utils/branch_notice.js";
 import { getCliName } from "../utils/cli_name.js";
@@ -34,14 +36,51 @@ export const builder = (argv) => argv
             "lines are preserved.",
         type: "string",
     },
+    service: servicesOption({
+        key: "service",
+        allowed: ENV_PULL_SERVICES,
+        describe: "Pull only these services' variables",
+        also: "Overrides neon.ts, and prunes only within the services you name.",
+    }),
 })
+    .epilogue([
+    "",
+    "What gets pulled, in precedence order:",
+    "  1. --service, when given — exactly those, ignoring neon.ts.",
+    "  2. neon.ts, when this directory has one.",
+    "  3. Otherwise everything the branch has, plus the AI Gateway —",
+    "     which mints a branch credential for it.",
+    "",
+    "The pull bundled into link / checkout / config apply follows 2 and 3",
+    "without the AI Gateway, so it never mints a credential you did not ask",
+    "for. Run `env pull` to add it.",
+].join("\n"))
     .example("$0 env pull", "Write the linked branch's Neon vars into .env.local (or .env if present)")
-    .example("$0 env pull --branch preview --file .env.preview", "Pull a specific branch into a specific file"), async (args) => {
+    .example("$0 env pull --branch preview --file .env.preview", "Pull a specific branch into a specific file")
+    .example("$0 env pull -s ai-gateway -s postgres", "Pull only the AI Gateway and Postgres variables"), async (args) => {
+    const raw = servicesFlagValue(args.service);
     // Explicit `env pull` announces the branch it's reading from up front so the user
     // can catch "pulled env from the wrong branch" before it overwrites their .env. The
     // bundled auto-pull (link / checkout / apply) stays quiet — those already report the
     // branch they pinned/applied to.
-    await pull(args, { announce: true });
+    //
+    // It also implies the AI Gateway when there is no neon.ts, so a bare `env pull`
+    // really does write everything the branch can give you. The bundled auto-pull does
+    // not: minting a credential for a service the user never named is not something a
+    // side effect of `link` / `checkout` / `apply` should do.
+    await pull({
+        ...args,
+        ...(raw
+            ? {
+                services: parseServices(raw, {
+                    allowed: ENV_PULL_SERVICES,
+                    whyUnavailable: ENV_PULL_UNAVAILABLE,
+                    flag: "--service",
+                    onDeprecated: (used, canonical) => log.warning(deprecatedServiceMessage(used, canonical)),
+                }),
+            }
+            : {}),
+    }, { announce: true, implyAiGateway: raw === undefined });
 })
     .demandCommand(1);
 export const handler = (args) => args;
@@ -83,16 +122,18 @@ export const pull = async (props, opts = {}) => {
     // Reuse `neon dev`'s tiered resolver (neon.ts policy -> plan gate -> fetchEnv, else
     // pullConfig -> fetchEnv). Unlike dev, an unresolved context or failure is surfaced —
     // `env pull` is an explicit action, so it should error rather than write nothing.
-    const { vars, credential } = await resolveNeonEnvVars({
+    const { vars, credential, skipped } = await resolveNeonEnvVars({
         cwd,
         projectId: props.projectId,
         branchId,
         env: { ...process.env, ...existingEnv },
+        ...(props.services ? { services: props.services } : {}),
+        ...(opts.implyAiGateway ? { implyAiGateway: true } : {}),
         ...(props.apiKey ? { apiKey: props.apiKey } : {}),
         ...(props.apiHost ? { apiHost: props.apiHost } : {}),
         ...(props.runtimeApi ? { api: props.runtimeApi } : {}),
     });
-    const neonVars = pickNeonVars(vars);
+    const neonVars = pickServiceVars(pickNeonVars(vars), props.services);
     if (Object.keys(neonVars).length === 0) {
         log.info("No Neon env variables to pull for this branch (no DATABASE_URL or " +
             "enabled Auth / Data API).");
@@ -102,7 +143,7 @@ export const pull = async (props, opts = {}) => {
     // Neon-owned vars the branch no longer has (e.g. NEON_AUTH_* / NEON_DATA_API_* carried over
     // from a previous project/branch). Non-Neon lines are always preserved.
     const { written, removed } = mergeEnvFile(targetPath, neonVars, {
-        managedKeys: NEON_OWNED_ENV_KEYS,
+        managedKeys: managedKeysFor(props.services, unreachedButCurrent(skipped, existingEnv, branchId)),
     });
     log.info("Pulled %d Neon variable%s into %s: %s", written.length, written.length === 1 ? "" : "s", targetPath, written.join(", "));
     if (removed.length > 0) {
@@ -116,6 +157,17 @@ export const pull = async (props, opts = {}) => {
         if (credential.revoked.length > 0) {
             log.info("Revoked the credential it replaced (%s).", credential.revoked.join(", "));
         }
+        else if (credential.superseded.length > 0) {
+            // An unscoped pull revokes what it supersedes and says so above. A scoped one
+            // cannot — it may not be the only service on that credential — so it leaves the
+            // old one live. Say that too, rather than letting the identical-looking output
+            // imply the branch is not accumulating credentials. Driven by what the resolver
+            // actually declined to revoke, so a first pull (which supersedes nothing) does
+            // not send the user hunting for a credential that was never there.
+            log.info("Left the credential it replaced live (%s): a pull scoped with --service " +
+                "can't tell which other services still use it. Revoke it in the Neon " +
+                "Console if nothing does.", credential.superseded.join(", "));
+        }
     }
     // A dotenv file *we* create holds live branch credentials (DATABASE_URL, Auth keys, service
     // tokens), so ignore it the same way the `.neon` context file is — otherwise a fresh repo is
@@ -143,8 +195,75 @@ export const pull = async (props, opts = {}) => {
         written,
         file: targetPath,
         ...(credential && credential.keys.length > 0 ? { credential } : {}),
+        ...(skipped && skipped.length > 0 ? { skipped } : {}),
     };
 };
+/**
+ * The keys this pull is allowed to prune, i.e. the ones it is authoritative for.
+ *
+ * A `--service` selection narrows that to the services it named: `env pull -s ai-gateway`
+ * says nothing about `DATABASE_URL`, so it must not read that variable's absence from this
+ * pull as "the branch no longer has it". `unreached` is subtracted for the same reason — see
+ * {@link unreachedButCurrent}.
+ */
+const managedKeysFor = (services, unreached) => {
+    const owned = services
+        ? ownedEnvServiceKeys(services)
+        : [...NEON_OWNED_ENV_KEYS];
+    if (unreached.length === 0)
+        return owned;
+    const keep = new Set(ownedEnvServiceKeys(unreached));
+    return owned.filter((key) => !keep.has(key));
+};
+/**
+ * Of the services this pull could not reach, the ones whose variables already on disk belong
+ * to the branch being pulled — the only ones worth keeping.
+ *
+ * Failing to reach a service is not evidence that the branch stopped having it:
+ * `PLATFORM_FEATURE_UNAVAILABLE` covers a transient incident as well as a project that
+ * genuinely lacks the feature, and pruning would delete a token whose secret exists nowhere
+ * else and strand the live credential behind it. But that only argues for keeping *this
+ * branch's* values. Variables left over from another branch are stale by definition, and
+ * keeping those would leave an app pointed at the wrong branch's gateway — a worse failure
+ * than losing a token, because it is silent.
+ *
+ * The gateway is the only service that can be unreached (only it is implied rather than
+ * observed), and its base URL is branch-scoped, so the persisted URL is what tells the two
+ * cases apart. Anything that does not resolve to this branch's gateway host is pruned, which
+ * is the safe direction: a stale entry costs a re-pull, a wrongly-kept one silently misroutes
+ * traffic.
+ */
+const unreachedButCurrent = (skipped, existingEnv, branchId) => {
+    if (!skipped?.includes("ai-gateway"))
+        return [];
+    const baseUrl = existingEnv[NEON_ENV_VAR_KEYS.aiGateway.baseUrl];
+    return baseUrl !== undefined && isBranchGatewayUrl(baseUrl, branchId)
+        ? ["ai-gateway"]
+        : [];
+};
+/**
+ * Whether a persisted `NEON_AI_GATEWAY_BASE_URL` addresses `branchId`'s gateway.
+ *
+ * Checks the parsed **hostname** against the shape `@neon/env` builds
+ * (`<branchId>-api.ai.<host suffix>`), not the raw string: a prefix comparison is satisfied
+ * by a URL whose userinfo carries the branch id (`https://<branchId>-api.ai.@other-host/`)
+ * while the request actually goes elsewhere. An unparseable value is not this branch's
+ * gateway either, which is an answer rather than a swallowed failure.
+ */
+const isBranchGatewayUrl = (baseUrl, branchId) => URL.canParse(baseUrl) &&
+    new URL(baseUrl).hostname.startsWith(`${branchId}-api.ai.`);
+/**
+ * Narrow the resolved vars to the selected services (plus `NEON_BRANCH`, which every pull
+ * refreshes). Needed because the two `DATABASE_URL*` vars are always resolved — `fetchEnv`
+ * reads both connection URIs regardless, since the AI Gateway host is derived from the direct
+ * one — so `--service ai-gateway` has to drop them here rather than avoid fetching them.
+ */
+const pickServiceVars = (vars, services) => {
+    if (!services)
+        return vars;
+    const wanted = envServiceKeys(services);
+    return Object.fromEntries(Object.entries(vars).filter(([key]) => wanted.has(key)));
+};
 /**
  * Pull a freshly-pinned branch's Neon env vars into a local `.env`, bundled into `link` and
  * `checkout` so the branch-first loop is just *link + checkout* — `env pull` runs for you.
@@ -183,6 +302,8 @@ export const renderAgentPullNote = (result) => {
             const credential = result.credential?.issued
                 ? ` Issued a new branch credential, so ${result.credential.keys.join(", ")} changed.`
                 : "";
+            // No `skipped` note: only the implied AI Gateway can be skipped, and the auto-pull
+            // this renders never implies it.
             return ` Pulled ${result.written.length} Neon env var${result.written.length === 1 ? "" : "s"} into ${result.file}.${credential}`;
         }
         case "empty":

package/dist/config_template.js

@@ -1,3 +1,4 @@
+import { NEON_SERVICES } from "./neon_services.js";
 /**
  * The published npm packages a `neon.ts` project needs — the `@neon/*` org names.
  *
@@ -11,55 +12,32 @@ export const CONFIG_PACKAGE = "@neon/config";
 export const ENV_PACKAGE = "@neon/env";
 export const REQUIRED_PACKAGES = [CONFIG_PACKAGE, ENV_PACKAGE];
 /**
- * A Neon service `config init` can declare in the `neon.ts` it scaffolds, spelled the way a
- * user types it in `--services`. Kebab-case rather than the `neon.ts` field names (`aiGateway`,
- * `buckets`) so the flag reads like a flag; {@link renderNeonConfig} owns the mapping.
+ * The services `config init` can declare in the `neon.ts` it scaffolds — the subset of
+ * {@link NEON_SERVICES} a policy has a field for. {@link renderNeonConfig} owns the mapping
+ * from these names to the `neon.ts` fields (`aiGateway`, `buckets`).
  *
- * Postgres is absent because every branch has it, and `dataApi` is absent because enabling it
- * with the default `authProvider: "neon"` requires `auth` — a pairing the picker would have to
- * enforce rather than offer.
+ * Postgres is absent because every branch has it, so there is nothing to declare. `data-api`
+ * is absent because enabling it with the default `authProvider: "neon"` requires `auth` — a
+ * pairing the picker would have to enforce rather than offer.
  */
-export const NEON_SERVICES = [
-    "auth",
-    "functions",
-    "storage",
-    "ai-gateway",
-];
-/** `--services none`: declare nothing, i.e. scaffold the bare starter policy. */
-export const NO_SERVICES = "none";
+export const CONFIG_INIT_SERVICES = NEON_SERVICES.filter((service) => service !== "postgres" && service !== "data-api");
+/**
+ * What `config init --services none` produces. One constant because it is both the help text
+ * and what tells the parser `none` is a value here — passing the literal at each call site
+ * lets the two drift into documenting something the parser does not accept.
+ */
+export const CONFIG_INIT_NONE_MEANS = "the bare starter policy";
+/** Why the two a policy cannot declare are not selectable, for the refusal message. */
+export const CONFIG_INIT_UNAVAILABLE = {
+    postgres: "every branch has Postgres, so a policy has nothing to declare for it",
+    "data-api": "enabling it with the default provider requires auth, so declare auth here and turn the Data API on with `neon data-api create`",
+};
 /** Slug, display name, and source path of the function scaffolded for `functions`. */
 export const FUNCTION_SLUG = "hello";
 export const FUNCTION_NAME = "Hello World";
 export const FUNCTION_FILENAME = "hello.ts";
 /** Name of the bucket scaffolded for `storage`. */
 export const BUCKET_NAME = "assets";
-/**
- * Parse a `--services` value into a canonical service list: comma-separated
- * {@link NEON_SERVICES} names, or {@link NO_SERVICES} on its own for none.
- *
- * Unknown names are rejected here rather than silently dropped — a typo'd service would
- * otherwise scaffold a policy missing exactly the service the user asked for. The result is
- * deduplicated and ordered by {@link NEON_SERVICES} so the rendered file doesn't depend on the
- * order they were typed in.
- */
-export const parseServices = (raw) => {
-    const names = raw
-        .split(",")
-        .map((name) => name.trim())
-        .filter((name) => name !== "");
-    if (names.includes(NO_SERVICES)) {
-        if (names.length > 1) {
-            throw new Error(`--services ${NO_SERVICES} cannot be combined with other services.`);
-        }
-        return [];
-    }
-    const unknown = names.filter((name) => !NEON_SERVICES.includes(name));
-    if (unknown.length > 0) {
-        throw new Error(`Unknown service${unknown.length === 1 ? "" : "s"} ${unknown.join(", ")}. ` +
-            `Supported values: ${NEON_SERVICES.join(", ")}, ${NO_SERVICES}.`);
-    }
-    return NEON_SERVICES.filter((service) => names.includes(service));
-};
 /**
  * One indentation level in the emitted `neon.ts`. Two spaces, which is what every renderer
  * here produces and what `config_template.format.test.ts` holds them to.
@@ -88,7 +66,7 @@ const renderPreview = (services) => {
             ...at(3, `${FUNCTION_SLUG}: { name: "${FUNCTION_NAME}", source: "./${FUNCTION_FILENAME}" },`),
         ]));
     }
-    if (services.includes("storage")) {
+    if (services.includes("object-storage")) {
         lines.push(...block(2, "buckets", [
             ...at(3, `// "private" is the default; use "public_read" for anonymous reads`, `${BUCKET_NAME}: { access: "private" },`),
         ]));

package/dist/dev/env.js

@@ -1,5 +1,6 @@
-import { loadConfigFromFile } from "@neon/config";
+import { createNeonApiFromOptions, loadConfigFromFile, } from "@neon/config";
 import { plan, pullConfig } from "@neon/config-runtime";
+import { NEON_ENV_VAR_KEYS } from "@neon/env";
 import { fetchEnvReusingSecrets, } from "@neon/env/runtime";
 import { log } from "../log.js";
 import { getCliName } from "../utils/cli_name.js";
@@ -34,6 +35,18 @@ export class MissingBranchContextError extends Error {
         this.name = "MissingBranchContextError";
     }
 }
+/**
+ * Thrown when an explicit `--service` selection names a service the branch does not have.
+ * Unlike the policy path — where the same situation is a {@link DevEnvMismatchError} pointing
+ * at `deploy` — the user named the service on the command line, so the fix is to provision it
+ * or drop it from the selection.
+ */
+export class ServiceNotOnBranchError extends Error {
+    constructor() {
+        super(...arguments);
+        this.name = "ServiceNotOnBranchError";
+    }
+}
 /**
  * Resolve the branch's Neon env vars (pooled / direct `DATABASE_URL`, plus Auth /
  * Data API when enabled) into a `{ KEY: value }` map. Shared by `neon dev` (which
@@ -41,6 +54,8 @@ export class MissingBranchContextError extends Error {
  *
  * Tiered:
  *
+ *   0. {@link DevEnvContext.services} is set -> that selection *is* the policy, and any
+ *      `neon.ts` is ignored. See {@link resolveSelectedServices}.
  *   1. a `neon.ts` policy is found -> the policy is the source of truth. We first
  *      check it against the branch's live state (`plan`); if it declares a resource
  *      the branch is missing, we stop with a {@link DevEnvMismatchError} pointing at
@@ -49,12 +64,17 @@ export class MissingBranchContextError extends Error {
  *      branch's live state (Auth / Data API enablement plus any object-storage
  *      buckets) into a config, then `fetchEnv` resolves what is actually enabled —
  *      so a branch with a bucket gets its `AWS_*` storage vars pulled with no policy.
+ *      With {@link DevEnvContext.implyAiGateway}, the AI Gateway is added on top, since
+ *      `pullConfig` cannot read it back.
  *   3. otherwise -> throw {@link MissingBranchContextError}.
  *
  * Unlike {@link resolveDevEnv}, this never swallows errors — callers decide how to
  * handle them.
  */
 export const resolveNeonEnvVars = async (ctx) => {
+    if (ctx.services) {
+        return await resolveSelectedServices(ctx, ctx.services);
+    }
     const config = await loadNeonConfig(ctx.cwd);
     if (config) {
         if (!ctx.projectId || !ctx.branchId) {
@@ -85,11 +105,193 @@ export const resolveNeonEnvVars = async (ctx) => {
         // straight into fetchEnv — no wrapping needed. pullConfig excludes functions and
         // the AI Gateway (neither can be faithfully read back), so fetchEnv never probes
         // the functions API here and only mints a storage credential when a bucket exists.
-        return await fetchAndProject(pulled.config, ctx);
+        if (!ctx.implyAiGateway) {
+            return await fetchAndProject(pulled.config, ctx);
+        }
+        return await resolveWithImpliedGateway(pulled.config, ctx, {
+            projectId: ctx.projectId,
+            branchId: ctx.branchId,
+        });
     }
     throw new MissingBranchContextError(`No project/branch context found. Link a branch (\`${getCliName()} link\` / ` +
         `\`${getCliName()} checkout\`) or pass --project-id and --branch.`);
 };
+/** The same config with the AI Gateway enabled, leaving any other `preview` entries intact. */
+const withAiGateway = (config) => ({
+    ...config,
+    preview: { ...config.preview, aiGateway: true },
+});
+/**
+ * Tier-2 resolution with the AI Gateway added on top of the branch's read-back state.
+ *
+ * The gateway is not detectable — `pullConfig` reports no enabled flag for it — so it is
+ * implied rather than observed. Nobody named it, so it must never be the reason the whole
+ * resolve fails: a project outside the regions where branch credentials exist would otherwise
+ * lose its `DATABASE_URL` too, and `neon dev` would start with no env at all.
+ *
+ * So the gateway is only added once its credential endpoint has been shown to answer, by
+ * reading the branch's credentials first. A project that does not have them says so on a
+ * read, before anything is minted — which is the whole question, since the gateway's env is a
+ * credential and nothing else.
+ *
+ * Deciding this **before** resolving, rather than by catching and retrying, is what keeps it
+ * honest. A retry re-runs every call the first attempt made, so it would blame the gateway for
+ * a one-off failure in shared work, and — worse — a first attempt that minted a credential and
+ * then failed would be papered over by a second that succeeds without one, swallowing the
+ * error and stranding a secret nobody holds. Once the read succeeds, a later failure is a real
+ * failure and propagates: the same thing already happens on a branch with object storage,
+ * whose credential is minted whether or not the gateway is involved.
+ */
+const resolveWithImpliedGateway = async (config, ctx, 
+/** Resolved by the caller, which is the branch this env belongs to. */
+branch) => {
+    const unreachable = await credentialsUnreachable(ctx, branch);
+    if (unreachable === null) {
+        return await fetchAndProject(withAiGateway(config), ctx);
+    }
+    // Deliberately does not assert that the project lacks the gateway: a read can also fail
+    // for a reason that has nothing to do with the feature, and this is not the place to
+    // guess which. Name both, and the command that answers it.
+    log.warning("Could not reach the AI Gateway's credentials, so %s were not resolved. Everything " +
+        "else was. Either this project does not have the AI Gateway, or the call failed — " +
+        `\`${getCliName()} env pull -s ai-gateway\` will say which.\nDetails: %s`, [
+        NEON_ENV_VAR_KEYS.aiGateway.apiKey,
+        NEON_ENV_VAR_KEYS.aiGateway.baseUrl,
+    ].join(" and "), unreachable);
+    return {
+        ...(await fetchAndProject(config, ctx)),
+        skipped: ["ai-gateway"],
+    };
+};
+/**
+ * Why the branch's credentials could not be read, or `null` when they could. A plain read: it
+ * mints nothing, revokes nothing, and changes nothing, so asking is free of the side effects
+ * that make a failed resolve ambiguous.
+ */
+const credentialsUnreachable = async (ctx, branch) => {
+    try {
+        await apiFor(ctx).listCredentials(branch.projectId, branch.branchId);
+        return null;
+    }
+    catch (err) {
+        return err instanceof Error ? err.message : String(err);
+    }
+};
+/** The adapter for direct branch reads: the injected one in tests, else built from options. */
+const apiFor = (ctx) => ctx.api ??
+    createNeonApiFromOptions("neon env", {
+        ...(ctx.apiKey ? { apiKey: ctx.apiKey } : {}),
+        ...(ctx.apiHost ? { apiHost: ctx.apiHost } : {}),
+    });
+/**
+ * Tier-0: resolve exactly the services `--service` named, with `neon.ts` out of the picture.
+ *
+ * The selection is checked against the branch's live state so a service that is named but not
+ * provisioned fails by name, instead of quietly contributing no vars. `postgres` and the AI
+ * Gateway are not checked: every branch has Postgres, and the gateway has no branch-level
+ * state to check (an unavailable one surfaces when its credential is minted).
+ */
+const resolveSelectedServices = async (ctx, services) => {
+    const { projectId, branchId } = ctx;
+    if (!projectId || !branchId) {
+        throw new MissingBranchContextError("--service needs a project and branch to read from. " +
+            `Run \`${getCliName()} link\` and \`${getCliName()} checkout <branch>\`, or pass ` +
+            "--project-id / --branch.");
+    }
+    // Read only the services that were named, rather than going through `pullConfig`. That
+    // keeps a selection independent of everything else on the branch — `pullConfig` also
+    // enumerates functions and credentials, so a failure there would abort `-s auth` — and it
+    // keeps an "object storage isn't available for this project" error intact, which
+    // `pullConfig` degrades to an empty bucket list and would report as "no buckets".
+    const api = apiFor(ctx);
+    const has = (service) => services.includes(service);
+    const [auth, dataApiEnabled, buckets] = await Promise.all([
+        has("auth") ? api.getNeonAuth(projectId, branchId) : null,
+        has("data-api") ? readDataApiEnabled(api, projectId, branchId) : null,
+        has("object-storage")
+            ? api.listBranchBuckets(projectId, branchId)
+            : null,
+    ]);
+    const config = configForServices(services, branchId, {
+        authEnabled: auth !== null,
+        dataApiEnabled,
+        buckets: buckets ?? [],
+    });
+    // A selection resolves part of the branch, so it must not revoke: the credential its
+    // persisted secrets name may also back a service it is not resolving. See
+    // `fetchEnvReusingSecrets`'s `revokeSuperseded`.
+    return await fetchAndProject(config, ctx, { revokeSuperseded: false });
+};
+/**
+ * Whether the branch has a Data API integration — or `null` when that cannot be determined.
+ *
+ * It is enabled per branch *and database*, so this has to probe the database `fetchEnv` will
+ * resolve the URL from, or the two would disagree. That is Neon's default `neondb`, else the
+ * only database; several databases with no `neondb` is a case `fetchEnv` refuses to auto-pick
+ * at all. Reporting "no Data API integration" there would be a claim this read cannot support,
+ * so it answers `null` and lets `fetchEnv` raise its own ambiguity error, which names the
+ * databases and the fix.
+ */
+const readDataApiEnabled = async (api, projectId, branchId) => {
+    const databases = await api.listBranchDatabases(projectId, branchId);
+    const database = databases.find((db) => db.name === NEON_DEFAULT_DATABASE) ??
+        (databases.length === 1 ? databases[0] : undefined);
+    if (!database)
+        return databases.length === 0 ? false : null;
+    const dataApi = await api.getNeonDataApi(projectId, branchId, database.name);
+    return dataApi !== null;
+};
+/** Neon's default database, and the one `fetchEnv` prefers when a branch has several. */
+const NEON_DEFAULT_DATABASE = "neondb";
+/**
+ * Build the `Config` an explicit `--service` selection stands for, raising
+ * {@link ServiceNotOnBranchError} for anything the branch does not have. Naming a service
+ * that isn't there has to fail rather than contribute no vars, or a scoped pull would report
+ * "no Neon env variables to pull" — which reads as a statement about the branch rather than
+ * about the selection.
+ */
+const configForServices = (services, branchId, branch) => {
+    // The command that provisions each one, for a user who may well have no `neon.ts` — in
+    // which case `deploy` / `config apply` would be no help at all.
+    const provisionWith = {
+        auth: `${getCliName()} neon-auth enable`,
+        "data-api": `${getCliName()} data-api create`,
+        "object-storage": `${getCliName()} buckets create <name>`,
+    };
+    const notOnBranch = (service, what) => {
+        throw new ServiceNotOnBranchError(`--service ${service}: branch ${branchId} has no ${what}, so there are no ` +
+            `${service} env vars to pull. Provision it first (\`${provisionWith[service]}\`, ` +
+            `or in the Neon Console), or drop ${service} from --service.`);
+    };
+    const config = {};
+    if (services.includes("auth")) {
+        if (!branch.authEnabled)
+            notOnBranch("auth", "Neon Auth integration");
+        config.auth = true;
+    }
+    if (services.includes("data-api")) {
+        // Only a positive "not there" is an error; an undecidable read defers to `fetchEnv`.
+        if (branch.dataApiEnabled === false) {
+            notOnBranch("data-api", "Data API integration");
+        }
+        config.dataApi = true;
+    }
+    const preview = {};
+    if (services.includes("object-storage")) {
+        if (branch.buckets.length === 0) {
+            notOnBranch("object-storage", "object-storage buckets");
+        }
+        preview.buckets = Object.fromEntries(branch.buckets.map((bucket) => [
+            bucket.name,
+            { access: bucket.accessLevel },
+        ]));
+    }
+    if (services.includes("ai-gateway"))
+        preview.aiGateway = true;
+    if (Object.keys(preview).length > 0)
+        config.preview = preview;
+    return config;
+};
 /**
  * `neon dev`'s env resolver: {@link resolveNeonEnvVars} with graceful degradation.
  *
@@ -180,11 +382,12 @@ const assertPolicyMatchesBranch = async (config, ctx) => {
 const isMissingResource = (change) => change.kind === "service" &&
     change.action === "create" &&
     !change.identifier.startsWith("function:");
-const fetchAndProject = async (config, ctx) => fetchEnvReusingSecrets(config, {
+const fetchAndProject = async (config, ctx, opts = {}) => fetchEnvReusingSecrets(config, {
     projectId: ctx.projectId,
     branch: ctx.branchId,
     ...apiOptions(ctx),
     ...(ctx.env ? { env: ctx.env } : {}),
+    ...(opts.revokeSuperseded === false ? { revokeSuperseded: false } : {}),
 });
 /**
  * Load a `neon.ts` policy if one exists on the path from `cwd` up to the repo

package/dist/env_services.js

@@ -0,0 +1,51 @@
+import { NEON_ENV_VAR_KEYS } from "@neon/env";
+import { NEON_SERVICES } from "./neon_services.js";
+/**
+ * The services `env pull --service` can select: every Neon service that produces branch env
+ * vars. `functions` is the one left out — a function's env comes from the local `neon.ts`,
+ * never from the branch, so there is nothing to pull.
+ */
+export const ENV_PULL_SERVICES = NEON_SERVICES.filter((service) => service !== "functions");
+/** Why the services `env pull` leaves out are not selectable, for the refusal message. */
+export const ENV_PULL_UNAVAILABLE = {
+    functions: "a function's env comes from your neon.ts, not from the branch, so there is nothing to pull",
+};
+/** The OS-level env vars each service contributes to a pulled `.env`. */
+const SERVICE_ENV_KEYS = {
+    postgres: Object.values(NEON_ENV_VAR_KEYS.postgres),
+    auth: Object.values(NEON_ENV_VAR_KEYS.auth),
+    "data-api": Object.values(NEON_ENV_VAR_KEYS.dataApi),
+    "object-storage": Object.values(NEON_ENV_VAR_KEYS.storage),
+    "ai-gateway": Object.values(NEON_ENV_VAR_KEYS.aiGateway),
+    functions: [],
+};
+/**
+ * The subset of {@link SERVICE_ENV_KEYS} a pull *owns*, and so may prune from the target file
+ * when the branch no longer has it. Object storage is deliberately absent: it is emitted under
+ * the third-party `AWS_*` names, which collide with credentials a user may set by hand, so
+ * `env pull` only ever writes them.
+ */
+const SERVICE_OWNED_ENV_KEYS = {
+    ...SERVICE_ENV_KEYS,
+    "object-storage": [],
+};
+/**
+ * Branch identity. Not a service — every branch has a name — so a scoped pull refreshes it
+ * alongside whatever services were selected.
+ */
+export const BRANCH_ENV_KEY = NEON_ENV_VAR_KEYS.branch.name;
+/** Every env var the selected services contribute, plus branch identity. */
+export const envServiceKeys = (services) => {
+    const keys = new Set([BRANCH_ENV_KEY]);
+    for (const service of services) {
+        for (const key of SERVICE_ENV_KEYS[service])
+            keys.add(key);
+    }
+    return keys;
+};
+/**
+ * The env vars a pull scoped to `services` may prune. Narrower than the unscoped set on
+ * purpose: `env pull -s ai-gateway` says nothing about `DATABASE_URL`, so it must leave it
+ * alone rather than treat its absence from this pull as "the branch no longer has it".
+ */
+export const ownedEnvServiceKeys = (services) => services.flatMap((service) => SERVICE_OWNED_ENV_KEYS[service]);

package/dist/neon_services.js

@@ -0,0 +1,143 @@
+/**
+ * Every Neon service a `--service` flag can name, spelled the way a user types it — one
+ * vocabulary for the whole CLI.
+ *
+ * Kebab-case rather than the `neon.ts` field names (`aiGateway`, `buckets`) so a flag reads
+ * like a flag, and the full product name rather than a shortening (`object-storage`, not
+ * `storage`) so nothing is ambiguous when read on its own.
+ *
+ * Commands take a **subset** of this via {@link ParseServicesOptions.allowed} — `config init`
+ * can only declare what a `neon.ts` has a field for, `env pull` can only pull what produces
+ * env vars — but the spelling of a service never varies between them. The order here is the
+ * canonical one: parsing sorts into it, so a command's output never depends on the order the
+ * flags were typed in.
+ *
+ * Not to be confused with `NeonFeature` in `init/bootstrap.ts`, which is what a *template*
+ * requires. That list comes from remote manifests (`neondatabase/examples/bootstrap.yaml`),
+ * spells Postgres `database`, and is not ours to rename.
+ */
+export const NEON_SERVICES = [
+    "postgres",
+    "auth",
+    "data-api",
+    "functions",
+    "object-storage",
+    "ai-gateway",
+];
+/**
+ * Spellings that used to be canonical, and the service they now mean. Accepted so a scripted
+ * `--services storage` keeps working, warned about so it does not quietly become a second
+ * vocabulary, and absent from help text, errors, and docs so nobody learns it fresh.
+ */
+const DEPRECATED_SERVICE_ALIASES = {
+    // `config init --services storage` shipped before the vocabulary was unified.
+    storage: "object-storage",
+};
+/** An explicit empty selection, for commands where "declare nothing" is a real answer. */
+export const NO_SERVICES = "none";
+/**
+ * What to tell someone still using a retired spelling. A message rather than a log call, so
+ * the parser stays free of the CLI's writer and each command can surface it in its own voice.
+ */
+export const deprecatedServiceMessage = (used, canonical) => `"${used}" is the old name for "${canonical}" and still works, but it will be removed. ` +
+    `Use "${canonical}".`;
+/**
+ * Parse the raw values of a services flag into a canonical selection.
+ *
+ * Accepts the flag repeated (`-s auth -s postgres`) and comma-separated
+ * (`-s auth,postgres`), since both read naturally and users will try either. The result is
+ * deduplicated and sorted into {@link NEON_SERVICES} order, so what a command does never
+ * depends on typing order.
+ *
+ * An unrecognized name is rejected rather than dropped: a typo would otherwise act on
+ * everything *except* the service that was asked for, and report success. A name that is a
+ * real service but not one this command supports says so specifically — "functions has no env
+ * variables" is a different problem from a typo, and has a different fix.
+ */
+export const parseServices = (raw, options) => {
+    const { allowed, flag, noneMeans, whyUnavailable = {}, onDeprecated, } = options;
+    const supported = `Supported values: ${allowed.join(", ")}${noneMeans !== undefined ? `, ${NO_SERVICES}` : ""}.`;
+    const names = raw
+        .flatMap((value) => value.split(","))
+        .map((name) => name.trim())
+        .filter((name) => name !== "");
+    if (names.length === 0) {
+        throw new Error(`${flag} needs at least one service. ${supported}`);
+    }
+    if (noneMeans !== undefined && names.includes(NO_SERVICES)) {
+        // Deduplicate before deciding it was combined with something: a repeated value is
+        // a no-op everywhere else in this parser, so `-s none -s none` must be too.
+        if (new Set(names).size > 1) {
+            throw new Error(`${flag} ${NO_SERVICES} cannot be combined with other services.`);
+        }
+        return [];
+    }
+    // Canonicalize first and unconditionally, so a retired spelling is reported against the
+    // service it means rather than as a word nobody recognizes.
+    const deprecated = new Map();
+    const resolved = names.map((name) => {
+        const canonical = DEPRECATED_SERVICE_ALIASES[name];
+        if (canonical === undefined)
+            return name;
+        deprecated.set(name, canonical);
+        return canonical;
+    });
+    const unsupported = resolved.filter((name) => !allowed.some((service) => service === name));
+    if (unsupported.length > 0) {
+        throw new Error(`${unsupportedMessage(unsupported, flag, whyUnavailable)} ${supported}`);
+    }
+    // Warned only once the selection is valid: a run that fails validation should not also
+    // carry a "still works" claim about a value that never took effect.
+    for (const [used, canonical] of deprecated)
+        onDeprecated?.(used, canonical);
+    return NEON_SERVICES.filter((service) => allowed.includes(service) && resolved.includes(service));
+};
+/**
+ * The sentences explaining why a selection was refused. A real Neon service this command
+ * cannot act on is a different mistake from a typo — different cause, different fix — so the
+ * two are never answered with the same word, and each service carries its reason where the
+ * command supplied one.
+ */
+const unsupportedMessage = (unsupported, flag, whyUnavailable) => {
+    const known = unsupported.filter((name) => NEON_SERVICES.some((service) => service === name));
+    const unknown = unsupported.filter((name) => !known.some((service) => service === name));
+    return [
+        unknown.length > 0
+            ? `Unknown service${unknown.length === 1 ? "" : "s"} ${unknown.join(", ")}.`
+            : undefined,
+        ...known.map((service) => {
+            const why = whyUnavailable[service];
+            return `${service} is not something ${flag} can select${why ? `: ${why}` : ""}.`;
+        }),
+    ]
+        .filter((part) => part !== undefined)
+        .join(" ");
+};
+/** Every spelling of the services flag, so a habit picked up on one command works on another. */
+const SERVICE_FLAG_NAMES = ["s", "service", "services"];
+/**
+ * The yargs option for a services flag, so every command that has one accepts the same
+ * spellings (`-s`, `--service`, `--services`) and the same value syntax. `key` is the name the
+ * command reads off `argv`; the rest become aliases.
+ */
+export const servicesOption = (params) => ({
+    alias: SERVICE_FLAG_NAMES.filter((name) => name !== params.key),
+    describe: [
+        `${params.describe}: ${params.allowed.join(", ")}.`,
+        params.noneMeans !== undefined
+            ? `Pass "${NO_SERVICES}" for ${params.noneMeans}.`
+            : undefined,
+        "Repeat the flag or comma-separate.",
+        params.also,
+    ]
+        .filter((part) => part !== undefined)
+        .join(" "),
+    type: "array",
+    string: true,
+});
+/**
+ * Narrow a yargs value for a services flag to the raw strings, or `undefined` when the flag
+ * was not given. `argv` is untyped at the handler, and `string: true` only guarantees the
+ * element type when the flag was actually parsed as an array.
+ */
+export const servicesFlagValue = (value) => Array.isArray(value) ? value.map(String) : undefined;

package/dist/utils/package_manager.js

@@ -1,4 +1,6 @@
 import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
 import which from "which";
 import { log } from "../log.js";
 // npm first so it's the default/preselected choice; the rest follow in rough
@@ -9,6 +11,42 @@ export const PACKAGE_MANAGERS = [
     "yarn",
     "bun",
 ];
+/**
+ * Lockfiles, and the package manager each one belongs to. npm is last on
+ * purpose: a repo with both a pnpm lockfile and a leftover `package-lock.json`
+ * (which a failed run like the one this fixes can leave behind) is a pnpm repo.
+ */
+const LOCKFILES = [
+    ["pnpm-lock.yaml", "pnpm"],
+    ["yarn.lock", "yarn"],
+    // bun 1.2+ writes the text `bun.lock`; older versions the binary `bun.lockb`.
+    ["bun.lock", "bun"],
+    ["bun.lockb", "bun"],
+    ["package-lock.json", "npm"],
+];
+/**
+ * The package manager the project at `cwd` uses, from its lockfile. Searches
+ * `cwd` and then each parent up to the repo root: in a monorepo the lockfile
+ * sits at the root while we scaffold into a package. Stopping at the root keeps
+ * a stray lockfile above the repository from deciding how we install into it.
+ */
+export const detectProjectPackageManager = (cwd) => {
+    let dir = cwd;
+    for (;;) {
+        for (const [file, pm] of LOCKFILES) {
+            if (existsSync(join(dir, file)))
+                return pm;
+        }
+        // After the lockfiles, not before: the repo root's own lockfile counts.
+        // `.git` is a file rather than a directory in a worktree or submodule.
+        if (existsSync(join(dir, ".git")))
+            return undefined;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+};
 /**
  * The package manager the CLI was invoked through, read from the
  * `npm_config_user_agent` npm sets for `npm exec`/`npx`, `pnpm dlx`, `yarn
@@ -32,11 +70,20 @@ export const detectPackageManager = () => {
 /** The package managers actually on PATH, in {@link PACKAGE_MANAGERS} order. */
 export const installedPackageManagers = () => PACKAGE_MANAGERS.filter((pm) => which.sync(pm, { nothrow: true }) !== null);
 /**
- * Pick a package manager without prompting: the one the CLI was invoked through,
- * else the first one installed, else npm. Used by non-interactive flows (e.g.
- * `config init`) where there's no scaffold prompt to hang a picker off.
+ * Pick a package manager without prompting: the one the project at `cwd` uses,
+ * else the one the CLI was invoked through, else the first one installed, else
+ * npm. Used by non-interactive flows (e.g. `config init`) where there's no
+ * scaffold prompt to hang a picker off.
+ *
+ * The project wins over the invocation on purpose. `npx neon …` inside a pnpm
+ * repo should still install with pnpm — which tool launched us says nothing
+ * about which one owns that project's `node_modules`, and running npm against
+ * pnpm's symlinked tree is what this ordering exists to prevent.
  */
-export const resolvePackageManager = () => detectPackageManager() ?? installedPackageManagers()[0] ?? "npm";
+export const resolvePackageManager = (cwd) => detectProjectPackageManager(cwd) ??
+    detectPackageManager() ??
+    installedPackageManagers()[0] ??
+    "npm";
 /**
  * The argv that adds `packages` as runtime dependencies with `pm`. npm spells it
  * `install`; pnpm/yarn/bun use `add`.

package/dist/utils/service_picker.js

@@ -1,8 +1,8 @@
 import prompts from "prompts";
-import { NEON_SERVICES } from "../config_template.js";
+import { CONFIG_INIT_SERVICES } from "../config_template.js";
 /**
- * The picker's rows, in {@link NEON_SERVICES} order. Titles use the product names from the
- * CLI's README ("Managed Better Auth", "Object Storage") rather than the `neon.ts` field
+ * The picker's rows, in {@link CONFIG_INIT_SERVICES} order. Titles use the product names from
+ * the CLI's README ("Managed Better Auth", "Object Storage") rather than the `neon.ts` field
  * names, since this is the list a user reads before they've seen a policy.
  */
 const CHOICES = [
@@ -17,7 +17,7 @@ const CHOICES = [
         description: "Long-running, without timeouts, and closer to your database.",
     },
     {
-        value: "storage",
+        value: "object-storage",
         title: "Object Storage",
         description: "S3-compatible blob storage that branches with your projects.",
     },
@@ -58,7 +58,7 @@ export const pickServicesInteractively = async () => {
     if (!Array.isArray(services)) {
         throw new Error("Aborted: no services selected.");
     }
-    // Order by NEON_SERVICES rather than selection order so the rendered neon.ts is
+    // Order canonically rather than by selection order so the rendered neon.ts is
     // independent of the order the rows were toggled in.
-    return NEON_SERVICES.filter((service) => services.includes(service));
+    return CONFIG_INIT_SERVICES.filter((service) => services.includes(service));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "2.46.0",
+  "version": "2.47.0",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -62,8 +62,8 @@
     "yoctocolors": "^2.1.2",
     "@neon/sdk": "1.5.0",
     "@neon/config": "0.14.1",
-    "@neon/config-runtime": "0.12.5",
-    "@neon/env": "0.14.1"
+    "@neon/env": "0.15.0",
+    "@neon/config-runtime": "0.12.5"
   },
   "optionalDependencies": {
     "esbuild": "0.28.1"