neon 2.45.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
@@ -593,6 +639,66 @@ $ neon bootstrap . --template hono
 
 The target directory must be empty unless you pass `--force` (a lone `.git` is ignored, so a freshly `git init`ed folder is fine). Symlinks and executable bits in the template are preserved.
 
+## Set up a project for your coding agent (`init`)
+
+`neon init` wires an existing project up to Neon: it signs you in, installs the Neon MCP server and agent skills into your editor, adds the Neon Local Connect extension for VS Code and Cursor, creates or picks a project, writes `DATABASE_URL` into `.env`, and offers to scaffold migrations.
+
+```bash
+$ neon init
+```
+
+Run in a terminal it prompts you through those steps. This is what the retired `neon-init` package used to do; `npx neon init` replaces it.
+
+Two side effects worth knowing before you run it. It **installs or upgrades `neonctl` globally**, with whichever package manager invoked it — the flow drives Neon by shelling out to the CLI rather than calling the API in-process. And it **writes `.neon`** in the project directory, the same context file `neon link` and `neon checkout` use.
+
+### Agent mode
+
+`--agent` turns the same flow into a state machine an AI coding assistant drives. It prints **one JSON object on stdout** and nothing else: a phase response carrying a `status` and a `nextAction` telling the agent what to do next — usually another `neon init` invocation, spelled out as a `command`. The two read-only steps, `status` and `finalize`, return a snapshot instead.
+
+```bash
+$ neon init --agent --data '{"step":"status"}'
+{
+  "auth": { "authenticated": true },
+  "tooling": { "mcpServer": { "configured": true, "scope": "global" }, "skills": { "installed": false, "scope": null } },
+  "project": { "databaseUrl": false },
+  "migrations": { "tool": "prisma", "hasMigrations": false },
+  "recommendations": [
+    { "priority": "high", "message": "No DATABASE_URL found in .env", "command": "neon init --agent --data '{\"step\":\"db\"}'" },
+    { "priority": "medium", "message": "Neon agent skills not detected in this project", "command": "neon init --agent --data '{\"step\":\"skills\",\"install\":true}'" },
+    { "priority": "medium", "message": "prisma detected but no migrations found", "command": "neon init --agent --data '{\"step\":\"migrations\"}'" }
+  ]
+}
+```
+
+`--agent` is implied when stdin is not a TTY and a known agent is detected from the environment (Claude Code, Codex, Cline, Cursor, VS Code, Windsurf).
+
+`--data` takes a JSON object whose `step` selects the phase: `auth`, `db`, `setup`, `getting-started`, `mcp`, `skills`, `migrations`, `neon-auth`, `status`, or `finalize`. Remaining keys are that phase's options. Without `--data`, the orchestrator picks the next phase itself. An unrecognised `step` is refused with the full list.
+
+**Failures are JSON too**, so an agent never has to distinguish "it broke" from "it returned nothing":
+
+```bash
+$ neon init --agent --data '{not json'
+{
+  "success": false,
+  "error": "Invalid JSON in --data flag at position 1. Expected a JSON object."
+}
+$ echo $?
+1
+```
+
+That message reports where parsing stopped and nothing more. `--data` carries whatever you put in it, and the JSON parser's own message quotes a window of the input, so echoing either would put a connection string or an API key on stdout.
+
+**One exception to "JSON on stdout".** Credentials are resolved before any command runs, so a failure in that step — an unknown `--profile` or `NEON_PROFILE`, `--api-key` and `--profile` together, or a `credentials.json` that cannot be read — prints `ERROR: …` on stderr, leaves stdout empty, and exits 1. Treat a non-zero exit with empty stdout as a credential problem and read stderr.
+
+| Option | |
+| --- | --- |
+| `--agent`, `-a` | Emit the JSON state machine instead of prompting |
+| `--data <json>` | Route to one phase, with that phase's options |
+| `--skip-migrations` | Leave the migrations phase out of the flow |
+| `--preview` | Enable preview features (scaffolding a project from a template) |
+
+`neon init` refuses `--profile`; see [Which credential an invocation uses](#which-credential-an-invocation-uses).
+
 ## Snapshots (`snapshots`)
 
 `neon snapshots` (alias `neon snapshot`) manages **snapshots** — point-in-time backups of a branch that you can list, rename, expire, restore into a branch, or schedule automatically. Snapshots are a Beta Neon feature and were previously only available in the Console and REST API; this command group brings them to the CLI.
@@ -776,7 +882,7 @@ When both are only environment variables the key wins, which keeps a CI pipeline
 
 `neon auth` and the `profile` subcommands are outside all of this, because they read the same flags to mean something else: `neon auth --profile work` names where to write a credential, and `neon profile create work --api-key …` names one to store.
 
-`neon init` does not support `--profile` yet. It hands its whole auth flow to `neon-init`, which reads the default credentials directly, so passing the flag fails instead of quietly running as the default account.
+`neon init` does not support `--profile` yet. It runs its own auth flow, which reads the default credentials directly and re-invokes the CLI as a subprocess without passing a profile down, so passing the flag fails instead of quietly running as the default account. `--api-key` and `NEON_API_KEY` reach `neon init` no better and are **not** refused. The flow reads the stored credential and nothing else, so a supplied key is ignored: with a credential on disk `neon init` runs silently as *that* account, and with none it sends you to a browser sign-in. The silent case is the one to watch — it is the same failure `--profile` is refused for, without the refusal. Until that is fixed, sign in as the account you want first, or use another command.
 
 ## API keys (`api-keys`)
 
@@ -876,6 +982,7 @@ API keys in org-7
 | config                                                                     | `init`, `status`, `plan`, `apply`                                                                            | Drive a branch from `neon.ts`      |
 | deploy                                                                     |                                                                                                              | Alias for `config apply`           |
 | bootstrap                                                                  |                                                                                                              | Scaffold a project from a template |
+| init                                                                       |                                                                                                              | Set up a project for a coding agent |
 | bucket                                                                     | `create`, `list`, `delete`, `object list`, `object get`, `object put`, `object delete` (incl. `--recursive`) | Manage buckets and their objects   |
 | [completion](https://neon.com/docs/reference/cli-completion)               |                                                                                                              | Generate a completion script       |
 

package/dist/_shared/paths.js

@@ -4,13 +4,12 @@
  **Deliberately impure.** It reads environment variables and touches the filesystem, which
  * `@neon/config` — the package this used to be a subpath of — must never do from its root
  * export. It lives here instead of there precisely so that a policy-facing package does not
- * carry implementor-only code, and so `neon-init`, which has no workspace dependencies, can use
- * the same resolution as everything else.
+ * carry implementor-only code.
  *
  * It exists because three separate readers each grew their own answer to "where is the
  * config directory", and all three disagreed: `packages/cli` honoured `XDG_CONFIG_HOME` but
- * not `NEONCTL_CONFIG_DIR`, `packages/env` honoured the env var but not XDG, and
- * `packages/init` hardcoded `~/.config/neonctl`. With `XDG_CONFIG_HOME` set, the CLI wrote
+ * not `NEONCTL_CONFIG_DIR`, `packages/env` honoured the env var but not XDG, and the init
+ * flow hardcoded `~/.config/neonctl`. With `XDG_CONFIG_HOME` set, the CLI wrote
  * credentials somewhere the other two never looked.
  *
  * ## The directory

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/bootstrap.js

@@ -1,11 +1,12 @@
 import { existsSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import chalk from "chalk";
-import { BootstrapInputError, ensureTargetUsable, FALLBACK_TEMPLATES, fetchTemplates, findTemplate, scaffoldTemplate, templateIds, } from "neon-init/bootstrap";
 import prompts from "prompts";
 import { credentialInputs } from "../_shared/auth_selection.js";
 import { isCi } from "../env.js";
+import { BootstrapInputError, ensureTargetUsable, FALLBACK_TEMPLATES, fetchTemplates, findTemplate, scaffoldTemplate, templateIds, } from "../init/bootstrap.js";
 import { log } from "../log.js";
+import { getCliName } from "../utils/cli_name.js";
 import { detectPackageManager, installedPackageManagers, runCommand, } from "../utils/package_manager.js";
 // The directory positional is optional: omitting it in an interactive terminal
 // prompts for one. In a non-interactive context a missing directory is an error.
@@ -55,7 +56,7 @@ export const builder = (argv) => argv
         default: true,
     },
     link: {
-        describe: "Run `neon link` in the scaffolded directory after installing. In interactive mode this is offered as a prompt; use --no-link to skip without being asked.",
+        describe: `Run \`${getCliName()} link\` in the scaffolded directory after installing. In interactive mode this is offered as a prompt; use --no-link to skip without being asked.`,
         type: "boolean",
         default: true,
     },
@@ -160,7 +161,7 @@ const resolveTargetDir = async (props, interactive, template) => {
             return resolve(process.cwd(), defaultDirName(template));
         }
         if (!interactive) {
-            throw new Error('No target directory given. Pass one, e.g. `neon bootstrap my-app` (or "." for the current directory).');
+            throw new Error(`No target directory given. Pass one, e.g. \`${getCliName()} bootstrap my-app\` (or "." for the current directory).`);
         }
         const { value } = await prompts({
             onState: onPromptState,
@@ -179,7 +180,7 @@ const resolveTargetDir = async (props, interactive, template) => {
 const defaultDirName = (template) => template.source.subdir.split("/").pop() || template.id;
 /**
  * Download and materialize the template into `targetDir`. The actual
- * download/extract/write lives in the shared `neon-init/bootstrap` core
+ * download/extract/write lives in `src/init/bootstrap.ts`, shared with `neon init`
  * (exec-bit and symlink fidelity, graceful symlink fallback); here we just
  * frame it with progress logging. Returns the number of files written.
  */
@@ -238,11 +239,11 @@ const runPostScaffoldSteps = async (props, targetDir, interactive) => {
     // and tell the user how to finish by hand.
     if (props.link) {
         if (!installed && hasNeonConfig(targetDir)) {
-            log.info("Skipping the Neon link step: `neon link` reads this project's neon.ts " +
+            log.info(`Skipping the Neon link step: \`${getCliName()} link\` reads this project's neon.ts ` +
                 `to pull env vars, which needs its dependencies. Run \`${pm} install\`, ` +
-                "then `neon link`.");
+                `then \`${getCliName()} link\`.`);
         }
-        else if (await confirm("Link this project to a Neon project now? (runs neon link)")) {
+        else if (await confirm(`Link this project to a Neon project now? (runs ${getCliName()} link)`)) {
             await runNeonLink(props, targetDir);
             // link prints its own summary (and pulls env), so end with just the run hint.
             printNextSteps(targetDir, pm, { installed, suggestLink: false });
@@ -366,7 +367,7 @@ const printNextSteps = (targetDir, pm, opts) => {
         log.info("  %s install", pm);
     }
     if (opts.suggestLink) {
-        log.info("  neon link");
+        log.info(`  ${getCliName()} link`);
     }
     log.info("  See the README to run it.");
     log.info("");
@@ -400,7 +401,7 @@ const runAgent = async (props) => {
                 description: template.description,
                 ...(template.services ? { services: template.services } : {}),
             })),
-            next_command_template: `neon bootstrap --agent ${props.directory ? shellArg(props.directory) : "<directory>"} --template <template_id>`,
+            next_command_template: `${getCliName()} bootstrap --agent ${props.directory ? shellArg(props.directory) : "<directory>"} --template <template_id>`,
         });
         return;
     }
@@ -413,7 +414,7 @@ const runAgent = async (props) => {
         emitAgent({
             status: "needs_directory",
             instruction: 'Ask the user which directory to scaffold into (use "." for the current directory), then re-run the next_command_template with it.',
-            next_command_template: `neon bootstrap --agent <directory> --template ${shellArg(template.id)}`,
+            next_command_template: `${getCliName()} bootstrap --agent <directory> --template ${shellArg(template.id)}`,
         });
         return;
     }
@@ -441,7 +442,7 @@ const runAgent = async (props) => {
             {
                 action: "link_neon_project",
                 instruction: "Ask the user whether to link the project to a Neon project now. This runs the link state machine — follow its JSON output for the next step.",
-                command: `${runIn}neon link --agent`,
+                command: `${runIn}${getCliName()} link --agent`,
             },
         ],
         message: `Scaffolded "${template.title}" (${filesWritten} files) into ${dir}. Offer the next_steps to the user: install dependencies, initialize git, then link a Neon project.`,

package/dist/commands/checkout.js

@@ -5,6 +5,7 @@ import { applyContext, contextBranch, readContextFile } from "../context.js";
 import { isCi } from "../env.js";
 import { log } from "../log.js";
 import { createBranch, pickBranchInteractively, } from "../utils/branch_picker.js";
+import { getCliName } from "../utils/cli_name.js";
 import { fillSingleProject } from "../utils/enrichers.js";
 import { looksLikeBranchId } from "../utils/formats.js";
 import { applyPolicyOnCreate, createBranchFromPolicyOnCheckout, } from "./config.js";
@@ -104,8 +105,8 @@ export const handler = async (props) => {
     if (failure) {
         throw new Error([
             `Branch ${branchName} (${branchId}) was created and checked out, but applying neon.ts to it failed: ${failure}`,
-            "The branch is usable but does not match the policy, and `neonctl checkout` never reconciles a branch that already exists.",
-            `Fix the cause above, then run \`neonctl deploy --update-existing\` to apply the policy to it — or, if your policy only configures new branches (keyed on \`!branch.exists\`), delete the branch and check it out again: \`neonctl branches delete ${branchName}\` then \`neonctl checkout ${branchName}\`.`,
+            `The branch is usable but does not match the policy, and \`${getCliName()} checkout\` never reconciles a branch that already exists.`,
+            `Fix the cause above, then run \`${getCliName()} deploy --update-existing\` to apply the policy to it — or, if your policy only configures new branches (keyed on \`!branch.exists\`), delete the branch and check it out again: \`${getCliName()} branches delete ${branchName}\` then \`${getCliName()} checkout ${branchName}\`.`,
         ].join("\n"));
     }
 };
@@ -129,7 +130,7 @@ const resolveBranchId = async (props, projectId) => {
     if (!props.id) {
         const picked = await pickBranchInteractively(branches, {
             message: "Which branch would you like to check out?",
-            nonInteractiveMessage: "No branch specified. Pass a branch name or id (e.g. `neonctl checkout main`), " +
+            nonInteractiveMessage: `No branch specified. Pass a branch name or id (e.g. \`${getCliName()} checkout main\`), ` +
                 "or run interactively to pick one from a list.",
         });
         if (picked.kind === "existing") {
@@ -266,7 +267,7 @@ const resolveProjectId = async (props) => {
     }
     const missingProjectMessage = "Could not determine which Neon project to check out a branch from. " +
         "Provide one via the --project-id flag " +
-        "or a .neon file (created by `neonctl link` / `neonctl set-context`).";
+        `or a .neon file (created by \`${getCliName()} link\` / \`${getCliName()} set-context\`).`;
     if (isCi() || !process.stdout.isTTY) {
         throw new Error(missingProjectMessage);
     }
@@ -274,7 +275,7 @@ const resolveProjectId = async (props) => {
     const { runLink } = await prompts({
         type: "confirm",
         name: "runLink",
-        message: "Run `neonctl link` in the current folder to pick a project now?",
+        message: `Run \`${getCliName()} link\` in the current folder to pick a project now?`,
         initial: true,
     });
     if (!runLink) {
@@ -289,7 +290,7 @@ const resolveProjectId = async (props) => {
     });
     const linked = readContextFile(props.contextFile);
     if (!linked.projectId) {
-        throw new Error("Linking did not produce a project id. Re-run `neonctl checkout` once the directory is linked.");
+        throw new Error(`Linking did not produce a project id. Re-run \`${getCliName()} checkout\` once the directory is linked.`);
     }
     // Carry the freshly-linked org id forward so the merge below keeps it.
     if (linked.orgId) {

package/dist/commands/config.js

@@ -5,13 +5,15 @@ 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";
 import { renderAppliedChanges, renderBranchSettingConflicts, } from "../utils/config_diff.js";
 import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
 import { bundleEntry } from "../utils/esbuild.js";
@@ -119,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();
@@ -216,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(" "));
@@ -284,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 " +
@@ -299,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;
 };
@@ -354,7 +369,7 @@ export const status = async (props) => {
         else {
             // No branch pinned: hint on stderr and exit non-zero (grep-style) so a prompt's
             // `when` hides the segment cleanly instead of rendering a bare icon.
-            log.info("No branch pinned. Run `neonctl checkout <branch>` to pin a branch and pull its env vars.");
+            log.info(`No branch pinned. Run \`${getCliName()} checkout <branch>\` to pin a branch and pull its env vars.`);
             process.exitCode = 1;
         }
         return;

package/dist/commands/data_api.js

@@ -1,5 +1,6 @@
 import { isNeonApiError, retryOnLock } from "../api.js";
 import { log } from "../log.js";
+import { getCliName } from "../utils/cli_name.js";
 import { branchIdFromProps, fillSingleProject, resolveSingleDatabase, } from "../utils/enrichers.js";
 import { writer } from "../writer.js";
 const SETTINGS_FIELDS = [
@@ -221,7 +222,7 @@ const update = async (props) => {
         }
         catch (err) {
             if (isNeonApiError(err) && err.status === 404) {
-                throw new Error(`Data API is not provisioned for ${database} on branch ${branchId}. Run \`neonctl data-api create\` first.`);
+                throw new Error(`Data API is not provisioned for ${database} on branch ${branchId}. Run \`${getCliName()} data-api create\` first.`);
             }
             throw err;
         }
@@ -238,7 +239,7 @@ const update = async (props) => {
     }
     catch (err) {
         if (isNeonApiError(err) && err.status === 404) {
-            throw new Error(`Data API is not provisioned for ${database} on branch ${branchId}. Run \`neonctl data-api create\` first.`);
+            throw new Error(`Data API is not provisioned for ${database} on branch ${branchId}. Run \`${getCliName()} data-api create\` first.`);
         }
         throw err;
     }
@@ -257,7 +258,7 @@ const refreshSchema = async (props) => {
     }
     catch (err) {
         if (isNeonApiError(err) && err.status === 404) {
-            throw new Error(`Data API is not provisioned for ${database} on branch ${branchId}. Run \`neonctl data-api create\` first.`);
+            throw new Error(`Data API is not provisioned for ${database} on branch ${branchId}. Run \`${getCliName()} data-api create\` first.`);
         }
         throw err;
     }