neon 2.45.0 → 2.46.0

package/README.md

@@ -593,6 +593,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 +836,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 +936,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/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

@@ -12,6 +12,7 @@ import { loadEnvFileIntoProcess } from "../env_file.js";
 import { log } from "../log.js";
 import { assertAiGatewayProvisionable, warnAiGateway, } from "../utils/ai_gateway_notice.js";
 import { announceTargetBranch } from "../utils/branch_notice.js";
+import { 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";
@@ -354,7 +355,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;
     }

package/dist/commands/env.js

@@ -7,6 +7,7 @@ import { mergeEnvFile, readEnvFile, resolveEnvFilePath } from "../env_file.js";
 import { log } from "../log.js";
 import { warnAiGateway } from "../utils/ai_gateway_notice.js";
 import { announceTargetBranch } from "../utils/branch_notice.js";
+import { 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 +16,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]")
@@ -165,7 +166,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 };
     }
@@ -187,10 +188,10 @@ export const renderAgentPullNote = (result) => {
         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);