neon 2.45.0 → 2.47.0

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,9 +4,12 @@ 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";
 import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
 export const command = "env";
 export const describe = "Manage a branch's Neon env variables locally";
@@ -15,7 +18,7 @@ export const describe = "Manage a branch's Neon env variables locally";
  * `--no-env-pull`. Names the two ways to get the branch's vars without an on-disk file written
  * eagerly: an explicit `neonctl env pull`, or runtime injection via `neon-env run`.
  */
-export const ENV_PULL_SKIPPED_HINT = "Skipped env pull (--no-env-pull). Run `neonctl env pull` to write this branch’s env vars " +
+export const ENV_PULL_SKIPPED_HINT = `Skipped env pull (--no-env-pull). Run \`${getCliName()} env pull\` to write this branch’s env vars ` +
     "(DATABASE_URL, …) into a local .env, or inject them at runtime with `neon-env run -- <your dev command>`.";
 export const builder = (argv) => argv
     .usage("$0 env <sub-command> [options]")
@@ -33,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;
@@ -82,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).");
@@ -101,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) {
@@ -115,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
@@ -142,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.
@@ -165,7 +285,7 @@ export const autoPullEnvAfterPin = async (props) => {
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         log.warning("Branch pinned, but pulling its Neon env vars failed: %s\n" +
-            "Run `neonctl env pull` once resolved (e.g. `neonctl deploy` if a declared service " +
+            `Run \`${getCliName()} env pull\` once resolved (e.g. \`${getCliName()} deploy\` if a declared service ` +
             "is missing), or inject them at runtime with `neon-env run -- <your dev command>`.", message);
         return { status: "failed", message };
     }
@@ -182,15 +302,17 @@ 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":
             return " No Neon env vars to pull for this branch yet.";
         case "skipped":
-            return (" Skipped env pull (--no-env-pull); run `neonctl env pull` later, " +
+            return (` Skipped env pull (--no-env-pull); run \`${getCliName()} env pull\` later, ` +
                 "or inject env at runtime with `neon-env run -- <your dev command>`.");
         case "failed":
-            return ` Could not pull env vars (${result.message}); run \`neonctl env pull\` once resolved.`;
+            return ` Could not pull env vars (${result.message}); run \`${getCliName()} env pull\` once resolved.`;
     }
 };
 /**

package/dist/commands/functions.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { isNeonApiError, retryOnLock } from "../api.js";
 import { createDeployment, deleteFunction, getFunction, listFunctions, } from "../functions_api.js";
 import { log } from "../log.js";
+import { getCliName } from "../utils/cli_name.js";
 import { branchIdFromProps, fillSingleProject } from "../utils/enrichers.js";
 import { bundleEntry } from "../utils/esbuild.js";
 import { zipBundle } from "../utils/zip.js";
@@ -146,7 +147,7 @@ const parseEnv = (entries) => {
     }
     return JSON.stringify(map);
 };
-const statusHint = (slug, projectId, branchId) => `Check status with: neonctl function get ${slug} --project-id ${projectId} --branch ${branchId}`;
+const statusHint = (slug, projectId, branchId) => `Check status with: ${getCliName()} function get ${slug} --project-id ${projectId} --branch ${branchId}`;
 // Emit the resolved deployment together with the function's invocation_url, so the
 // deploy output shows where the function is reachable (not just the deployment id).
 const emitDeployResult = (props, deployment, fn) => {
@@ -172,7 +173,7 @@ const deploy = async (props) => {
         props.runtime !== undefined;
     if (!hasOption) {
         throw new Error("Provide at least one option to deploy, e.g. --src or --env. " +
-            "See: neonctl function deploy --help.");
+            `See: ${getCliName()} function deploy --help.`);
     }
     // Cheap, offline validation first - fail before any network round-trip.
     if (!SLUG_PATTERN.test(props.slug)) {

package/dist/commands/init.js

@@ -1,7 +1,11 @@
-import { detectAgent, enrichResponse, interactiveInit, orchestrate, routeDataStep, } from "neon-init";
 import { credentialInputs } from "../_shared/auth_selection.js";
-import { sendError } from "../analytics.js";
-import { log } from "../log.js";
+import { closeAnalytics, sendError } from "../analytics.js";
+import { detectAgent } from "../init/detect_agent.js";
+import { enrichResponse } from "../init/enrich_output.js";
+import { interactiveInit } from "../init/interactive.js";
+import { orchestrate } from "../init/orchestrate.js";
+import { routeDataStep } from "../init/route_command.js";
+import { STDOUT_FD, writeAllSync } from "../utils/write_sync.js";
 export const command = "init";
 export const describe = "Initialize a project with Neon using your AI coding assistant";
 export const builder = (yargs) => yargs
@@ -29,62 +33,103 @@ export const builder = (yargs) => yargs
     describe: "Enable preview features (e.g. project bootstrapping from templates).",
 })
     .strict(false);
+/**
+ * The agent-facing half of `neon init` speaks JSON, and it speaks it on **stdout**:
+ * one object, no prefix, nothing else. `log.info` would prefix every line with
+ * `INFO: ` and send it to stderr, which is right for a diagnostic and wrong for the
+ * payload an agent is expected to parse.
+ */
+const writeAgentResponse = (result) => {
+    writeAllSync(STDOUT_FD, `${JSON.stringify(enrichResponse(result), null, 2)}\n`);
+};
+/**
+ * A failure has to arrive in the shape the caller asked for. An agent parses stdout and
+ * has no branch for "empty stdout, exit 1" — it cannot tell a broken credentials file
+ * from a phase that legitimately produced nothing — so the error goes out as JSON too.
+ */
+const writeAgentFailure = (error) => {
+    writeAllSync(STDOUT_FD, `${JSON.stringify({ success: false, error: error.message }, null, 2)}\n`);
+};
+/** ` at position 12`, or nothing when the parser did not report one. */
+const parsePosition = (parseError) => {
+    const message = parseError instanceof Error ? parseError.message : "";
+    const at = message.match(/at position (\d+)/);
+    return at === null ? "" : ` at position ${at[1]}`;
+};
 export const handler = async (argv) => {
-    // `init` delegates its whole auth flow to `neon-init`, which reads the default credentials
-    // directly and re-invokes the CLI as a subprocess. It has no way to be told which profile
-    // to use, so honouring a selection here is not possible yet — and silently running as the
-    // default account would be worse than refusing, because naming an account is the entire
-    // job of the thing being ignored.
+    // Auto-detect agent from environment. When --agent is explicitly passed,
+    // always detect (the user asked for agent mode). Otherwise, require
+    // non-TTY stdin to distinguish agent from human in terminal.
     //
-    // `NEON_PROFILE` counts just as much as the flag. Checking only the flag left the case that
-    // is easier to hit by accident: a profile exported once into a shell then silently
-    // disregarded by every `neon init` run in it.
-    const selectedProfile = argv.profile?.trim() || credentialInputs().profileEnv.trim();
-    if (selectedProfile) {
-        const how = argv.profile?.trim()
-            ? "--profile was passed, so"
-            : "NEON_PROFILE is set, so";
-        throw new Error(`${how} \`neon init\` would run as the default account instead of "${selectedProfile}", and it does not support profile selection yet. Run it without one, or set the project up with \`neon --profile ${selectedProfile} link\`.`);
-    }
+    // Resolved before anything can fail, so that every failure this handler sees —
+    // including the profile refusal — is reported in the shape the caller can read.
+    // Failures raised by `ensureAuth` are not among them: it resolves credentials
+    // above its own `init` skip, so an unknown profile, a contradictory
+    // `--api-key`/`--profile` pair, and a damaged credentials file all report on
+    // stderr before this runs.
+    const agent = (argv.agent || !process.stdin.isTTY ? detectAgent() : null) ||
+        undefined;
+    const isAgentMode = argv.agent || agent !== undefined;
     try {
-        // Auto-detect agent from environment. When --agent is explicitly passed,
-        // always detect (the user asked for agent mode). Otherwise, require
-        // non-TTY stdin to distinguish agent from human in terminal.
-        const agent = (argv.agent || !process.stdin.isTTY ? detectAgent() : null) ||
-            undefined;
-        const isAgentMode = argv.agent || agent !== undefined;
+        // The init flow reads the default credentials directly and re-invokes the CLI as a
+        // subprocess. It has no way to be told which profile to use, so honouring a selection
+        // here is not possible yet — and silently running as the default account would be
+        // worse than refusing, because naming an account is the entire job of the thing being
+        // ignored.
+        //
+        // `NEON_PROFILE` counts just as much as the flag. Checking only the flag left the case
+        // that is easier to hit by accident: a profile exported once into a shell then
+        // silently disregarded by every `neon init` run in it.
+        const selectedProfile = argv.profile?.trim() || credentialInputs().profileEnv.trim();
+        if (selectedProfile) {
+            const how = argv.profile?.trim()
+                ? "--profile was passed, so"
+                : "NEON_PROFILE is set, so";
+            throw new Error(`${how} \`neon init\` would run as the default account instead of "${selectedProfile}", and it does not support profile selection yet. Run it without one, or set the project up with \`neon --profile ${selectedProfile} link\`.`);
+        }
         // --data with a "step" field routes to the appropriate phase
         if (argv.data && isAgentMode) {
             let data;
             try {
                 data = JSON.parse(argv.data);
             }
-            catch {
-                log.error("Invalid JSON in --data flag. Expected a JSON object.");
-                process.exit(1);
-                return;
+            catch (parseError) {
+                // Neither the payload nor the parser's message may appear here. `--data`
+                // carries whatever the caller put in it — a connection string, an API key —
+                // and V8 quotes a window of the input around the syntax error, so both would
+                // travel into the error message, onto stdout, and into `sendError`'s
+                // analytics payload. `shared/cli-core/src/credentials.ts` discards the same
+                // message for the same reason. The position is a number and says enough.
+                throw new Error(`Invalid JSON in --data flag${parsePosition(parseError)}. Expected a JSON object.`);
             }
             if (typeof data.step === "string") {
-                const result = await routeDataStep(data, agent);
-                log.info(JSON.stringify(enrichResponse(result), null, 2));
+                writeAgentResponse(await routeDataStep(data, agent));
                 return;
             }
         }
         if (isAgentMode) {
-            const result = await orchestrate({
+            writeAgentResponse(await orchestrate({
                 agent,
                 skipMigrations: argv.skipMigrations,
                 preview: argv.preview,
-            });
-            log.info(JSON.stringify(enrichResponse(result), null, 2));
+            }));
         }
         else {
             await interactiveInit({ preview: argv.preview });
         }
     }
-    catch {
-        const exitError = new Error(`failed to run neon-init`);
-        sendError(exitError, "NEON_INIT_FAILED");
-        process.exit(1);
+    catch (error) {
+        const cause = error instanceof Error ? error : new Error(String(error));
+        if (isAgentMode) {
+            // Agent mode answers and exits here, so nothing else will report this. Attribute
+            // it to init and flush before exiting — `process.exit` drops in-flight events.
+            sendError(cause, "NEON_INIT_FAILED");
+            writeAgentFailure(cause);
+            await closeAnalytics();
+            process.exit(1);
+        }
+        // A human gets the top-level handler's single `ERROR: <message>` line on stderr, and
+        // its `sendError`. Reporting here as well would file one failure as two events.
+        throw cause;
     }
 };

package/dist/commands/ip_allow.js

@@ -1,5 +1,6 @@
 import { log } from "../log.js";
 import { projectUpdateRequest } from "../parameters.gen.js";
+import { getCliName } from "../utils/cli_name.js";
 import { fillSingleProject } from "../utils/enrichers.js";
 import { writer } from "../writer.js";
 const IP_ALLOW_FIELDS = [
@@ -68,7 +69,7 @@ const list = async (props) => {
 const add = async (props) => {
     if (props.ips.length <= 0) {
         throw new Error(`Enter individual IP addresses, define ranges with a dash, or use CIDR notation for more flexibility.
-       Example: neonctl ip-allow add 192.168.1.1, 192.168.1.20-192.168.1.50, 192.168.1.0/24 --project-id <id>`);
+       Example: ${getCliName()} ip-allow add 192.168.1.1, 192.168.1.20-192.168.1.50, 192.168.1.0/24 --project-id <id>`);
     }
     const project = {};
     const { data } = await props.apiClient.getProject(props.projectId);
@@ -90,7 +91,7 @@ const add = async (props) => {
 };
 const remove = async (props) => {
     if (props.ips.length <= 0) {
-        throw new Error(`Remove individual IP addresses and ranges. Example: neonctl ip-allow remove 192.168.1.1 --project-id <id>`);
+        throw new Error(`Remove individual IP addresses and ranges. Example: ${getCliName()} ip-allow remove 192.168.1.1 --project-id <id>`);
     }
     const project = {};
     const { data } = await props.apiClient.getProject(props.projectId);