neon 4.5.2 → 4.7.0

package/README.md

@@ -256,14 +256,14 @@ The Neon CLI supports autocompletion, which you can configure in a few easy step
 `link` resolves what it can and **verifies every identifier you pass** before writing, so a `.neon` is never left half-written or pointing at something that doesn't exist:
 
 - **org** is inferred from the project (so `--project-id` alone is enough); it's omitted only when the project has no organization (personal account).
-- **project** is taken from `--project-id` (or chosen interactively / via `--agent`).
+- **project** is taken from `--project-id` (or chosen interactively).
 - **branch** is left to an explicit [`neon checkout <branch>`](#checkout) — `link` never silently pins a project's default branch (that would make later commands quietly target, say, production). It only records a branch when you pass `--branch`, when one is already pinned for the same project (preserved), when you pick one in the interactive picker, or for a freshly **created** project (whose single branch is unambiguous).
 
 When a branch ends up pinned, `link` also runs [`env pull`](#env-pull) so the branch's Neon env vars (`DATABASE_URL`, …) land in a local `.env`. With no branch pinned there is nothing to pull, so `link` instead nudges you to run `neon checkout`. Pass `--no-env-pull` to skip the pull (for example when injecting env at runtime with `neon-env run` or `neon dev`).
 
 > **Migrating from `set-context`?** `set-context` is **deprecated** in favor of `link` (see [below](#set-context-is-deprecated)). It still works exactly as before for now (a raw write), it just prints a deprecation warning. The `.neon` `branchId` field is also superseded by `branch` (which stores the branch **name** when known); old `branchId` files are still read and are upgraded to `branch` the next time `link`/`checkout` writes the context.
 
-There are three modes:
+There are two modes:
 
 **Interactive (default)** — guided prompts for humans:
 
@@ -322,64 +322,21 @@ neon link --no-checks --org-id org-abc123 --project-id polished-snowflake-123456
 
 Every supplied identifier is checked before anything is written, with actionable errors — e.g. `Project '…' not found`, `You don't have access to project '…'`, `Organization '…' not found, or your API key doesn't have access to it`, `Project '…' belongs to organization 'A', not 'B'`, or `Branch '…' not found in project '…'. Available branches: …`.
 
-**Agent mode (`--agent`)** — a JSON state machine designed for AI coding assistants. Each invocation returns a single JSON object with a `status` discriminator describing the next step, the available options, and the exact follow-up command to run.
+**Agents and scripts (no TTY):** List, then link. `neon link --help` prints the same recipe.
 
 ```bash
-$ neon link --agent
-{
-  "status": "needs_org",
-  "instruction": "Ask the user which of these 2 organizations they want to link the current directory to. After they pick one, re-run the next_command_template with the chosen --org-id value.",
-  "options": [
-    { "id": "org-abc123", "name": "Personal Org" },
-    { "id": "org-team",   "name": "Team Org" }
-  ],
-  "next_command_template": "neon link --agent --org-id <org_id>"
-}
-
-$ neon link --agent --org-id org-abc123
-{
-  "status": "needs_project",
-  "instruction": "Ask the user whether to link to one of these 1 existing projects (use next_command_template with --project-id) or create a new project (use create_option.next_command_template).",
-  "options": [
-    { "id": "polished-snowflake-12345678", "name": "my-app" }
-  ],
-  "create_option": {
-    "instruction": "To create a new project, ask the user for a project name. The region can be omitted to receive a follow-up needs_project_details response that lists available regions.",
-    "next_command_template": "neon link --agent --org-id org-abc123 --project-name <name> --region-id <region_id>"
-  },
-  "next_command_template": "neon link --agent --org-id org-abc123 --project-id <project_id>"
-}
-
-$ neon link --agent --org-id org-abc123 --project-id polished-snowflake-12345678
-{
-  "status": "linked",
-  "context_file": "/path/to/cwd/.neon",
-  "context": {
-    "orgId": "org-abc123",
-    "projectId": "polished-snowflake-12345678"
-  },
-  "project": { "id": "polished-snowflake-12345678" },
-  "message": "Linked /path/to/cwd/.neon to project polished-snowflake-12345678 (org org-abc123). No branch pinned — run `neon checkout <branch>` (omit the branch to list options) to pin one and pull its env vars."
-}
+neon orgs list --output json
+neon projects list --org-id <org-id> --output json
+neon link --project-id <project-id>
+neon link --org-id <org-id> --project-name <name> --region-id aws-us-east-2
 ```
 
-The `linked` response omits `branch` unless one was pinned (via `--branch`, an existing pin, or project creation); pass `--branch <name|id>` to include it. The agent flow also handles project creation: if the agent sends `--project-name` without `--region-id`, the next response is `needs_project_details` with the list of supported regions.
-
-**Organization-scoped API keys** (those created at the organization level rather than the user level) cannot list user organizations or call the regions endpoint. `link` handles this transparently:
-
-- If the API key is org-scoped and at least one project already exists in the org, the CLI auto-detects the `org_id` from the first project. In interactive mode it prints an informational message; in `--agent` mode it skips straight to `needs_project`.
-- If the API key is org-scoped and no projects exist yet, `--agent` returns a `needs_org` response with `options: []` and an instruction telling the user to find their org ID in the Neon Console. Interactive mode prints an error pointing to `--org-id`.
-- When the regions endpoint is not allowed, `link` falls back to a built-in static region list.
+Organization-scoped API keys cannot list user organizations (`orgs list`) or call the regions endpoint:
 
-**Agent error contract**: any unexpected failure in `--agent` mode is reported as JSON to stdout with exit code 1, so agents can always parse the response:
-
-```json
-{
-  "status": "error",
-  "code": "CLIENT_ERROR",
-  "message": "user has no access to projects"
-}
-```
+- Pass `--org-id` (Neon Console → Settings) or `--project-id` (org is inferred from the project).
+- If the key is org-scoped and at least one project already exists, interactive `link` auto-detects the org from the first project and prints an informational message.
+- If no projects exist yet, interactive `link` errors pointing at `--org-id`.
+- When the regions endpoint is not allowed, interactive create falls back to a built-in static region list. Non-interactive create already requires `--region-id`.
 
 **Offline writes (`--no-checks`)** — write the `.neon` with no API calls at all: no org inference, no existence/access verification, no env pull. Because nothing can be resolved offline, it requires both `--org-id` and `--project-id` (`--branch` optional, stored verbatim). Handy for scripted/CI setups or re-creating a `.neon` from values you already trust:
 
@@ -710,6 +667,12 @@ $ neon bootstrap my-app
 
 # Scaffold a specific template into the current directory (no prompts)
 $ neon bootstrap . --template hono
+
+# List templates
+$ neon bootstrap --list-templates
+
+# Machine-readable catalog
+$ neon bootstrap --list-templates --output json
 ```
 
 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.

package/dist/commands/bootstrap.js

@@ -3,8 +3,9 @@ import { isCi } from "../env.js";
 import { log } from "../log.js";
 import { getCliName } from "../utils/cli_name.js";
 import { t as credentialInputs } from "../_chunks/auth_selection-ktL6uoEe.js";
-import { BootstrapInputError, FALLBACK_TEMPLATES, ensureTargetUsable, fetchTemplates, findTemplate, scaffoldTemplate, templateIds } from "../init/bootstrap.js";
-import { DO_NOT_SUBSTITUTE_HINT, formatInstallCommand, inferPackageManager, installArgs, installedPackageManagers, resolvePackageManager, runCommand } from "../utils/package_manager.js";
+import { writer } from "../writer.js";
+import { FALLBACK_TEMPLATES, ensureTargetUsable, fetchTemplates, findTemplate, scaffoldTemplate, templateIds } from "../init/bootstrap.js";
+import { formatInstallCommand, inferPackageManager, installArgs, installedPackageManagers, resolvePackageManager, runCommand } from "../utils/package_manager.js";
 import { existsSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import chalk from "chalk";
@@ -16,6 +17,7 @@ var bootstrap_exports = /* @__PURE__ */ __exportAll({
 	describe: () => describe,
 	handler: () => handler
 });
+const removedAgent = () => `\`${getCliName()} bootstrap --agent\` was removed. List templates with \`${getCliName()} bootstrap --list-templates --output json\`. Scaffold with \`${getCliName()} bootstrap <directory> --template <id>\` or \`${getCliName()} bootstrap <directory> --default\`.`;
 const command = "bootstrap [directory]";
 const describe = "Scaffold a new project from a Neon starter template";
 const builder = (argv) => argv.usage("$0 bootstrap [directory] [options]").positional("directory", {
@@ -28,7 +30,7 @@ const builder = (argv) => argv.usage("$0 bootstrap [directory] [options]").posit
 	},
 	"list-templates": {
 		alias: ["list", "ls"],
-		describe: "List available templates and exit.",
+		describe: "List available templates and exit. --output json and --output yaml print a machine-readable catalog.",
 		type: "boolean",
 		default: false
 	},
@@ -38,9 +40,8 @@ const builder = (argv) => argv.usage("$0 bootstrap [directory] [options]").posit
 		default: false
 	},
 	agent: {
-		describe: "Emit a JSON state-machine response designed for AI agents instead of prompting. The output is a single JSON object with a discriminated `status` field describing the next step.",
-		type: "boolean",
-		default: false
+		hidden: true,
+		type: "boolean"
 	},
 	default: {
 		alias: "y",
@@ -63,20 +64,33 @@ const builder = (argv) => argv.usage("$0 bootstrap [directory] [options]").posit
 		type: "boolean",
 		default: true
 	}
-}).example("$0 bootstrap my-app", "Create ./my-app from an interactively chosen template").example("$0 bootstrap . --template hono", "Scaffold the Hono template into the current directory").example("$0 bootstrap my-app --default", "Quick start: scaffold the default template and run setup without prompting").example("$0 bootstrap my-app --template hono --agent", "Scaffold without prompting and emit the JSON state machine for AI agents").strict();
+}).example("$0 bootstrap my-app", "Create ./my-app from an interactively chosen template").example("$0 bootstrap . --template hono", "Scaffold the Hono template into the current directory").example("$0 bootstrap my-app --default", "Quick start: scaffold the default template and run setup without prompting").example("$0 bootstrap --list-templates --output json", "Print the template catalog as JSON").check((argv) => {
+	if (argv.agent === true) throw new Error(removedAgent());
+	return true;
+}).strict();
 const handler = async (props) => {
 	if (props.listTemplates) {
 		const templates = await fetchTemplates();
+		if (props.output === "json" || props.output === "yaml") {
+			writer(props).end(templates.map((t) => ({
+				id: t.id,
+				title: t.title,
+				description: t.description,
+				services: t.services ?? []
+			})), { fields: [
+				"id",
+				"title",
+				"description",
+				"services"
+			] });
+			return;
+		}
 		for (const t of templates) {
 			const services = t.services && t.services.length > 0 ? ` [${t.services.join(" · ")}]` : "";
 			process.stdout.write(`${t.id} — ${t.description}${services}\n`);
 		}
 		return;
 	}
-	if (props.agent) {
-		await runAgentSafely(props);
-		return;
-	}
 	const templates = await resolveTemplateList(props);
 	const interactive = !props.default && Boolean(process.stdout.isTTY) && !isCi();
 	const template = await resolveSelectedTemplate(props, interactive, templates);
@@ -163,15 +177,6 @@ const scaffold = async (template, targetDir) => {
 	log.info("Scaffolded %d files into %s.", filesWritten, targetDir);
 	return filesWritten;
 };
-/**
-* After a human scaffold, offer the things you almost always do next: install
-* dependencies, initialize a git repo, and link the directory to a Neon
-* project. In an interactive terminal each is a y/n prompt (skippable up front
-* with --no-install / --no-git / --no-link); `--default` runs install + git
-* without asking; otherwise we just print the manual steps so nothing runs
-* behind the user's back. Agent mode never reaches here — it returns these as
-* structured `next_steps` instead (see {@link runAgent}).
-*/
 const runPostScaffoldSteps = async (props, targetDir, interactive) => {
 	const inferred = inferPackageManager(targetDir);
 	const defaultPm = resolvePackageManager(targetDir);
@@ -307,103 +312,6 @@ const printNextSteps = (targetDir, pm, opts) => {
 	log.info("  See the README to run it.");
 	log.info("");
 };
-const runAgentSafely = async (props) => {
-	try {
-		await runAgent(props);
-	} catch (err) {
-		emitAgent(toAgentError(err));
-		process.exit(1);
-	}
-};
-/**
-* The `--agent` flow: resolve what the flags determine and emit one JSON object
-* describing either the next input needed (`needs_template` / `needs_directory`)
-* or the terminal result (`scaffolded`). Unlike interactive mode it never
-* prompts and never runs install/git/link itself — those come back as structured
-* `next_steps` so the agent can confirm with the user and run them (the link
-* step chains into `neon link --agent`).
-*/
-const runAgent = async (props) => {
-	if (!props.template) {
-		const templates = await fetchTemplates();
-		emitAgent({
-			status: "needs_template",
-			instruction: `Ask the user which template to scaffold, then re-run the next_command_template with the chosen --template value${props.directory ? "" : " and a target directory"}.`,
-			options: templates.map((template) => ({
-				id: template.id,
-				title: template.title,
-				description: template.description,
-				...template.services ? { services: template.services } : {}
-			})),
-			next_command_template: `${getCliName()} bootstrap --agent ${props.directory ? shellArg(props.directory) : "<directory>"} --template <template_id>`
-		});
-		return;
-	}
-	const templates = await resolveTemplateList(props);
-	const template = findTemplate(templates, props.template);
-	if (!template) throw new BootstrapInputError(`Unknown template "${props.template}". Available templates: ${templateIds(templates)}.`, "UNKNOWN_TEMPLATE");
-	if (props.directory === void 0) {
-		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: `${getCliName()} bootstrap --agent <directory> --template ${shellArg(template.id)}`
-		});
-		return;
-	}
-	const targetDir = resolve(process.cwd(), props.directory === "." ? "" : props.directory);
-	ensureTargetUsable(targetDir, props.force);
-	const filesWritten = await scaffold(template, targetDir);
-	const dir = displayDir(targetDir);
-	const runIn = isCurrentDir(targetDir) ? "" : `cd ${shellArg(dir)} && `;
-	const installPm = resolvePackageManager(targetDir);
-	emitAgent({
-		status: "scaffolded",
-		directory: targetDir,
-		template: {
-			id: template.id,
-			title: template.title
-		},
-		files_written: filesWritten,
-		next_steps: [
-			{
-				action: "install_dependencies",
-				instruction: `Ask the user whether to install dependencies, then run this in the project directory. ${DO_NOT_SUBSTITUTE_HINT}`,
-				command: `${runIn}${formatInstallCommand(installPm)}`
-			},
-			{
-				action: "initialize_git",
-				instruction: "Ask the user whether to initialize a git repository in the project directory.",
-				command: `${runIn}git init`
-			},
-			{
-				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}${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.`
-	});
-};
-const emitAgent = (response) => {
-	process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
-};
-const toAgentError = (err) => {
-	if (err instanceof BootstrapInputError) return {
-		status: "error",
-		code: err.agentCode,
-		message: err.message
-	};
-	if (err instanceof Error) return {
-		status: "error",
-		code: "INTERNAL_ERROR",
-		message: err.message
-	};
-	return {
-		status: "error",
-		code: "INTERNAL_ERROR",
-		message: String(err)
-	};
-};
 const isCurrentDir = (targetDir) => relative(process.cwd(), targetDir) === "";
 /**
 * The path to show the user: the bare relative path for the common
@@ -415,10 +323,6 @@ const displayDir = (targetDir) => {
 	if (rel === "") return ".";
 	return rel.startsWith("..") ? targetDir : rel;
 };
-const shellArg = (value) => {
-	if (/^[A-Za-z0-9._:/-]+$/.test(value)) return value;
-	return `'${value.replace(/'/g, `'\\''`)}'`;
-};
 const onPromptState = (state) => {
 	if (state.aborted) {
 		process.stdout.write("\x1B[?25h");

package/dist/commands/env.js

@@ -19,8 +19,7 @@ var env_exports = /* @__PURE__ */ __exportAll({
 	command: () => "env",
 	describe: () => describe,
 	handler: () => handler,
-	pull: () => pull,
-	renderAgentPullNote: () => renderAgentPullNote
+	pull: () => pull
 });
 const command = "env";
 const describe = "Manage a branch's Neon env variables locally";
@@ -229,8 +228,7 @@ const pickSelectedVars = (vars, selectedKeys) => {
 * On by default; `--no-env-pull` opts out (e.g. when env is injected at runtime via
 * `neon-env run` / `neon dev`, or to keep secrets out of the working tree). The pin is the
 * command's primary effect and has already succeeded by the time this runs, so a pull failure
-* degrades to a warning rather than failing the command. Returns what happened so
-* `link --agent` can fold an accurate note into its JSON message.
+* degrades to a warning rather than failing the command.
 */
 const autoPullEnvAfterPin = async (props) => {
 	if (!props.envPull) {
@@ -250,21 +248,6 @@ Run \`${getCliName()} env pull\` once resolved (e.g. \`${getCliName()} deploy\`
 	}
 };
 /**
-* Render the one-line env-pull note appended to `link --agent`'s JSON `message`, so an agent
-* reading the structured output knows whether its branch env is already on disk.
-*/
-const renderAgentPullNote = (result) => {
-	switch (result.status) {
-		case "written": {
-			const credential = result.credential?.issued ? ` Issued a new branch credential, so ${result.credential.keys.join(", ")} changed.` : "";
-			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 \`${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 \`${getCliName()} env pull\` once resolved.`;
-	}
-};
-/**
 * Keep only the recognized Neon variables from the resolved set, so a stray inherited
 * value never lands in the user's `.env` file. (Today `resolveNeonEnvVars` only emits Neon
 * vars, but filtering keeps the contract explicit and future-proof.)
@@ -278,4 +261,4 @@ const pickNeonVars = (vars) => {
 	return out;
 };
 //#endregion
-export { ENV_PULL_SKIPPED_HINT, autoPullEnvAfterPin, builder, command, describe, handler, pull, renderAgentPullNote, env_exports as t };
+export { ENV_PULL_SKIPPED_HINT, autoPullEnvAfterPin, builder, command, describe, handler, pull, env_exports as t };

package/dist/commands/link.js

@@ -5,8 +5,9 @@ import { isNeonApiError, messageFromBody } from "../api.js";
 import { applyContext, contextBranch, readContextFile, setContext, updateContextFile } from "../context.js";
 import { getCliName } from "../utils/cli_name.js";
 import { createBranch, pickBranchInteractively } from "../utils/branch_picker.js";
-import { autoPullEnvAfterPin, renderAgentPullNote } from "./env.js";
+import { autoPullEnvAfterPin } from "./env.js";
 import { hasNeonConfigFile, initCmd } from "./config.js";
+import { helpEpilogue } from "../utils/help_text.js";
 import { REGIONS } from "./projects.js";
 import prompts from "prompts";
 //#region src/commands/link.ts
@@ -18,6 +19,19 @@ var link_exports = /* @__PURE__ */ __exportAll({
 });
 const PROJECTS_LIST_LIMIT = 100;
 const CREATE_NEW_SENTINEL = "__create_new__";
+const canPromptInteractively = () => !isCi() && Boolean(process.stdin.isTTY) && Boolean(process.stdout.isTTY);
+const nonInteractiveLinkCommands = () => {
+	const cli = getCliName();
+	return [
+		`${cli} orgs list --output json`,
+		`${cli} projects list --org-id <org-id> --output json`,
+		`${cli} link --project-id <project-id>`,
+		`${cli} link --org-id <org-id> --project-name <name> --region-id aws-us-east-2`
+	];
+};
+const nonInteractiveLinkHelp = () => nonInteractiveLinkCommands().map((command) => `  ${command}`).join("\n");
+const orgScopedKeyHint = "Organization-scoped API keys cannot list orgs; pass --org-id.";
+const removedAgent = () => `\`${getCliName()} link --agent\` was removed.\nUse:\n${nonInteractiveLinkHelp()}\n${orgScopedKeyHint}`;
 const command = "link";
 const describe = "Link the current directory to a Neon project";
 const builder = (argv) => argv.usage("$0 link [options]").options({
@@ -47,9 +61,8 @@ const builder = (argv) => argv.usage("$0 link [options]").options({
 		type: "string"
 	},
 	agent: {
-		describe: "Emit a JSON state-machine response designed for AI agents instead of prompting. The output is a single JSON object with a discriminated `status` field describing the next step.",
-		type: "boolean",
-		default: false
+		hidden: true,
+		type: "boolean"
 	},
 	yes: {
 		alias: "y",
@@ -78,7 +91,10 @@ const builder = (argv) => argv.usage("$0 link [options]").options({
 	["$0 link --branch-id br-…", "Pin a branch in the already-linked project"],
 	["$0 link --no-checks --org-id org-… --project-id polished-snowflake-12345678", "Write the context offline (no API calls, no verification)"],
 	["$0 link --clear", "Forget the current org/project/branch context"]
-]);
+]).epilogue(helpEpilogue("Non-interactive (CI, scripts, agents):", ...nonInteractiveLinkCommands().map((command) => `  ${command}`), orgScopedKeyHint)).check((argv) => {
+	if (argv.agent === true) throw new Error(removedAgent());
+	return true;
+});
 const handler = async (props) => {
 	if (props.clear) {
 		clearContext(props.contextFile);
@@ -88,10 +104,6 @@ const handler = async (props) => {
 		runWithoutChecks(props);
 		return;
 	}
-	if (props.agent) {
-		await runAgentSafely(props);
-		return;
-	}
 	const inputs = parseInputs(props);
 	validateInputs(inputs);
 	const existing = readContextFile(props.contextFile);
@@ -99,14 +111,13 @@ const handler = async (props) => {
 		await runNonInteractive(props, inputs, existing);
 		return;
 	}
-	if (isCi()) {
+	if (!canPromptInteractively()) {
 		log.error([
-			"Missing inputs and CI environment detected (no TTY for prompts).",
+			"Missing inputs and no interactive terminal for prompts.",
 			"",
-			"Use one of:",
-			`  ${getCliName()} link --agent                                                    (JSON state machine for agents)`,
-			`  ${getCliName()} link --project-id <project>                                     (link to an existing project; org is inferred)`,
-			`  ${getCliName()} link --org-id <org> --project-name <name> --region-id <region>  (create a new project and link)`
+			"Use:",
+			nonInteractiveLinkHelp(),
+			orgScopedKeyHint
 		].join("\n"));
 		process.exit(1);
 		return;
@@ -195,20 +206,6 @@ const runWithoutChecks = (props) => {
 		projectId: inputs.projectId,
 		branch: inputs.branch
 	});
-	if (props.agent) {
-		emitAgent({
-			status: "linked",
-			context_file: props.contextFile,
-			context: {
-				orgId: inputs.orgId,
-				projectId: inputs.projectId,
-				branch: inputs.branch
-			},
-			project: { id: inputs.projectId },
-			message: `Wrote ${props.contextFile} without checks (org ${inputs.orgId}, project ${inputs.projectId}${inputs.branch ? `, branch ${inputs.branch}` : ""}). No verification or env pull was performed.`
-		});
-		return;
-	}
 	printSummary(props, {
 		contextFile: props.contextFile,
 		orgId: inputs.orgId,
@@ -218,25 +215,14 @@ const runWithoutChecks = (props) => {
 		noChecks: true
 	});
 };
-/**
-* A bad user-supplied identifier (project/org/branch that doesn't exist or
-* isn't accessible). Carries an `agentCode` so `--agent` mode can report a
-* precise `status: error` code instead of a generic INTERNAL_ERROR, while the
-* human path just prints the clear `message`.
-*/
 var LinkInputError = class extends Error {
-	constructor(message, agentCode) {
+	constructor(message) {
 		super(message);
 		this.name = "LinkInputError";
-		this.agentCode = agentCode;
 	}
 };
 const httpStatus = (err) => isNeonApiError(err) ? err.status : void 0;
-/**
-* Fetch a project, turning the common failure modes into clear, actionable
-* errors. 401 is rethrown so the global handler can refresh credentials;
-* everything else surfaces as a `LinkInputError` the user (or agent) can act on.
-*/
+/** 401 must reach the global handler so it can refresh credentials. */
 const fetchProjectOrThrow = async (props, projectId) => {
 	try {
 		const { data } = await props.apiClient.getProject(projectId);
@@ -244,8 +230,8 @@ const fetchProjectOrThrow = async (props, projectId) => {
 	} catch (err) {
 		const status = httpStatus(err);
 		if (status === 401) throw err;
-		if (status === 403) throw new LinkInputError(`You don't have access to project '${projectId}'. Check that your API key's account or organization can see it.`, "NO_ACCESS");
-		if (status === 404) throw new LinkInputError(`Project '${projectId}' not found. Double-check the project ID — or that your API key has access to it.`, "NOT_FOUND");
+		if (status === 403) throw new LinkInputError(`You don't have access to project '${projectId}'. Check that your API key's account or organization can see it.`);
+		if (status === 404) throw new LinkInputError(`Project '${projectId}' not found. Double-check the project ID — or that your API key has access to it.`);
 		throw err;
 	}
 };
@@ -263,7 +249,7 @@ const verifyOrgAccess = async (props, orgId) => {
 	} catch (err) {
 		const status = httpStatus(err);
 		if (status === 401) throw err;
-		if (status === 403 || status === 404) throw new LinkInputError(`Organization '${orgId}' not found, or your API key doesn't have access to it. Find your org ID in the Neon Console under Settings.`, status === 403 ? "NO_ACCESS" : "NOT_FOUND");
+		if (status === 403 || status === 404) throw new LinkInputError(`Organization '${orgId}' not found, or your API key doesn't have access to it. Find your org ID in the Neon Console under Settings.`);
 		throw err;
 	}
 };
@@ -278,7 +264,7 @@ const resolveBranchRef = async (props, projectId, branchRef) => {
 	const { data } = await props.apiClient.listProjectBranches({ projectId });
 	const match = data.branches.find((b) => b.id === branchRef) ?? data.branches.find((b) => b.name === branchRef);
 	if (match) return match;
-	throw new LinkInputError(`Branch '${branchRef}' not found in project '${projectId}'. Available branches: ${data.branches.length > 0 ? data.branches.map((b) => `${b.id}${b.name ? ` (${b.name})` : ""}`).join(", ") : "(none)"}. Pin one with \`${getCliName()} checkout <branch>\`.`, "NOT_FOUND");
+	throw new LinkInputError(`Branch '${branchRef}' not found in project '${projectId}'. Available branches: ${data.branches.length > 0 ? data.branches.map((b) => `${b.id}${b.name ? ` (${b.name})` : ""}`).join(", ") : "(none)"}. Pin one with \`${getCliName()} checkout <branch>\`.`);
 };
 /**
 * The value to persist for a branch: prefer its human-readable **name** (nicer
@@ -301,7 +287,7 @@ const branchPersistValue = (branch) => branch.name ?? branch.id;
 const resolveOrgForProject = async (props, inputs, existing, projectId) => {
 	const projectOrg = (await fetchProjectOrThrow(props, projectId)).org_id ?? void 0;
 	if (inputs.orgId) {
-		if (projectOrg && projectOrg !== inputs.orgId) throw new LinkInputError(`Project '${projectId}' belongs to organization '${projectOrg}', not '${inputs.orgId}'. Omit --org-id to use the project's own org, or pass the matching ID.`, "ORG_MISMATCH");
+		if (projectOrg && projectOrg !== inputs.orgId) throw new LinkInputError(`Project '${projectId}' belongs to organization '${projectOrg}', not '${inputs.orgId}'. Omit --org-id to use the project's own org, or pass the matching ID.`);
 		if (!projectOrg) await verifyOrgAccess(props, inputs.orgId);
 		return inputs.orgId;
 	}
@@ -568,135 +554,6 @@ const promptRegion = async (props) => {
 	});
 	return regionId;
 };
-const runAgentSafely = async (props) => {
-	try {
-		const inputs = parseInputs(props);
-		validateInputs(inputs);
-		await runAgent(props, inputs);
-	} catch (err) {
-		emitAgent(toAgentError(err));
-		process.exit(1);
-	}
-};
-const runAgent = async (props, inputs) => {
-	const { projectId, projectName, regionId, branch } = inputs;
-	const existing = readContextFile(props.contextFile);
-	if (projectId) {
-		const orgId = await resolveOrgForProject(props, inputs, existing, projectId);
-		const pinnedBranch = await resolvePinnedBranch(props, inputs, existing, projectId);
-		applyContext(props.contextFile, {
-			orgId,
-			projectId,
-			branch: pinnedBranch
-		});
-		const orgSuffix = orgId ? ` (org ${orgId})` : "";
-		if (pinnedBranch) {
-			const pullNote = renderAgentPullNote(await autoPullEnvAfterPin({
-				...props,
-				projectId,
-				branch: pinnedBranch,
-				envPull: props.envPull
-			}));
-			emitAgent({
-				status: "linked",
-				context_file: props.contextFile,
-				context: {
-					orgId,
-					projectId,
-					branch: pinnedBranch
-				},
-				project: { id: projectId },
-				message: `Linked ${props.contextFile} to project ${projectId}${orgSuffix} on branch ${pinnedBranch}.${pullNote}`
-			});
-			return;
-		}
-		emitAgent({
-			status: "linked",
-			context_file: props.contextFile,
-			context: {
-				orgId,
-				projectId
-			},
-			project: { id: projectId },
-			message: `Linked ${props.contextFile} to project ${projectId}${orgSuffix}. No branch pinned — run \`${getCliName()} checkout <branch>\` (omit the branch to list options) to pin one and pull its env vars.`
-		});
-		return;
-	}
-	const orgResolution = await resolveOrg(props, inputs.orgId);
-	if (orgResolution.kind === "needs_selection") {
-		emitAgent(buildNeedsOrgResponse(orgResolution));
-		return;
-	}
-	const orgId = orgResolution.orgId;
-	if (projectName && !regionId) {
-		const regions = await fetchRegions(props);
-		emitAgent({
-			status: "needs_project_details",
-			instruction: `Ask the user which region to create project "${projectName}" in. After they pick one, re-run the next_command_template with the chosen --region-id value.`,
-			regions: regions.map((region) => ({
-				id: region.region_id,
-				name: region.name,
-				default: region.default
-			})),
-			next_command_template: `${getCliName()} link --agent --org-id ${shellArg(orgId)} --project-name ${shellArg(projectName)} --region-id <region_id>`
-		});
-		return;
-	}
-	if (projectName && regionId) {
-		await verifyOrgAccess(props, orgId);
-		const created = await createProject(props, {
-			orgId,
-			name: projectName,
-			regionId
-		});
-		applyContext(props.contextFile, {
-			orgId,
-			projectId: created.project.id,
-			branch: created.branchName
-		});
-		const pullNote = renderAgentPullNote(await autoPullEnvAfterPin({
-			...props,
-			projectId: created.project.id,
-			branch: created.branchName,
-			envPull: props.envPull
-		}));
-		emitAgent({
-			status: "linked",
-			context_file: props.contextFile,
-			context: {
-				orgId,
-				projectId: created.project.id,
-				branch: created.branchName
-			},
-			project: {
-				id: created.project.id,
-				name: created.project.name,
-				region_id: created.project.region_id
-			},
-			message: `Created project ${created.project.id} ("${created.project.name ?? projectName}") in ${created.project.region_id ?? regionId} and linked ${props.contextFile} on branch ${created.branchName}.${pullNote}`
-		});
-		return;
-	}
-	const projects = await listAllProjects(props, orgId);
-	const branchNote = branch ? ` A branch was requested (--branch ${branch}) but a branch can only be pinned once a project is chosen — re-run with --project-id first, then \`${getCliName()} checkout ${branch}\`.` : "";
-	emitAgent({
-		status: "needs_project",
-		instruction: (projects.length === 0 ? `Organization ${orgId} has no projects yet. Ask the user for a name for the new project, then re-run the create_option.next_command_template.` : `Ask the user whether to link to one of these ${projects.length} existing projects (use next_command_template with --project-id) or create a new project (use create_option.next_command_template).`) + branchNote,
-		options: projects.map((project) => ({
-			id: project.id,
-			name: project.name,
-			region_id: project.region_id
-		})),
-		create_option: {
-			instruction: "To create a new project, ask the user for a project name. The region can be omitted to receive a follow-up needs_project_details response that lists available regions.",
-			next_command_template: `${getCliName()} link --agent --org-id ${shellArg(orgId)} --project-name <name> --region-id <region_id>`
-		},
-		next_command_template: `${getCliName()} link --agent --org-id ${shellArg(orgId)} --project-id <project_id>`
-	});
-};
-const emitAgent = (response) => {
-	process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
-};
 const ORG_KEY_LIMITED_FRAGMENT = "not allowed for organization API keys";
 const isOrgKeyLimitedError = (err) => {
 	if (!isNeonApiError(err)) return false;
@@ -754,56 +611,6 @@ const detectOrgIdFromProjects = async (props) => {
 		return;
 	}
 };
-const buildNeedsOrgResponse = (resolution) => {
-	if (resolution.orgKeyLimited) return {
-		status: "needs_org",
-		instruction: "This Neon API key is organization-scoped, so the CLI cannot list the user's organizations and no existing project was found to auto-detect the org ID. Ask the user for their Neon organization ID (visible in the Neon Console under the org's Settings page, formatted like `org-bitter-breeze-12345678`) and re-run the next_command_template with that --org-id.",
-		options: [],
-		next_command_template: `${getCliName()} link --agent --org-id <org_id>`
-	};
-	const orgs = resolution.orgs;
-	return {
-		status: "needs_org",
-		instruction: orgs.length === 0 ? "The user does not belong to any organizations. Ask them to create one in the Neon Console (https://console.neon.tech/) before linking." : `Ask the user which of these ${orgs.length} organization${orgs.length === 1 ? "" : "s"} they want to link the current directory to. After they pick one, re-run the next_command_template with the chosen --org-id value.`,
-		options: orgs.map((org) => ({
-			id: org.id,
-			name: org.name
-		})),
-		next_command_template: `${getCliName()} link --agent --org-id <org_id>`
-	};
-};
-const toAgentError = (err) => {
-	if (err instanceof LinkInputError) return {
-		status: "error",
-		code: err.agentCode,
-		message: err.message
-	};
-	if (isNeonApiError(err)) {
-		const status = err.status;
-		const apiMessage = messageFromBody(err.data);
-		const message = apiMessage !== void 0 && apiMessage.length > 0 ? apiMessage : err.message;
-		let code = "API_ERROR";
-		if (status === 401 || status === 403) code = "AUTH_ERROR";
-		else if (status !== void 0 && status >= 400 && status < 500) code = "CLIENT_ERROR";
-		else if (status !== void 0 && status >= 500) code = "SERVER_ERROR";
-		else if (err.code === "ECONNABORTED") code = "TIMEOUT";
-		return {
-			status: "error",
-			code,
-			message
-		};
-	}
-	if (err instanceof Error) return {
-		status: "error",
-		code: "INTERNAL_ERROR",
-		message: err.message
-	};
-	return {
-		status: "error",
-		code: "INTERNAL_ERROR",
-		message: String(err)
-	};
-};
 const listAllProjects = async (props, orgId) => {
 	const result = [];
 	let cursor;
@@ -965,10 +772,6 @@ const onPromptState = (state) => {
 		process.exit(1);
 	}
 };
-const shellArg = (value) => {
-	if (/^[A-Za-z0-9._:/-]+$/.test(value)) return value;
-	return `'${value.replace(/'/g, `'\\''`)}'`;
-};
 const mustString = (value, name) => {
 	if (value === void 0) throw new Error(`Internal error: expected ${name} to be set.`);
 	return value;

package/dist/commands/mcp.js

@@ -4,13 +4,13 @@ import { readContextFile } from "../context.js";
 import { getCliName } from "../utils/cli_name.js";
 import { writer } from "../writer.js";
 import { noPassthrough, single } from "../utils/flags.js";
+import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { NEON_MCP_CATEGORIES, NEON_MCP_URL, existingNeonApiKey, installNeonMcpServer, neonMcpUrl, parseMcpCategories, trackedProjectMcpConfig } from "../mcp/install.js";
 import { mintMcpApiKey, mintedKeyRevokeCommand, withdrawMintedKey } from "../mcp/mint.js";
 import { canPickAgentsInteractively } from "../utils/agent_picker.js";
 import { mcpInstallableAgents, resolveInstallTargets } from "../mcp/targets.js";
 import { confirmMcpInstall } from "../mcp/wizard.js";
 import { resolveMcpPlan } from "../mcp/plan.js";
-import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 //#region src/commands/mcp.ts
 var mcp_exports = /* @__PURE__ */ __exportAll({
 	builder: () => builder,

package/dist/commands/plugins.js

@@ -2,11 +2,11 @@ import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { log } from "../log.js";
 import { writer } from "../writer.js";
 import { noPassthrough } from "../utils/flags.js";
+import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { NEON_MCP_URL } from "../mcp/install.js";
 import { getAgentDisplayName } from "../mcp/agents.js";
 import "../init/agents.js";
 import { canPickAgentsInteractively } from "../utils/agent_picker.js";
-import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { pluginsInstallableAgents } from "../plugins/targets.js";
 import { resolvePluginsPlan } from "../plugins/plan.js";
 import { NEON_PLUGIN_NAME, PLUGIN_SKILLS, PLUGIN_SOURCE, neonPluginsRetryCommand, pluginsAddArgs, runPluginsCli } from "../plugins/run.js";

package/dist/commands/skills.js

@@ -2,10 +2,10 @@ import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { log } from "../log.js";
 import { writer } from "../writer.js";
 import { noPassthrough } from "../utils/flags.js";
+import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { getAgentDisplayName } from "../mcp/agents.js";
 import "../init/agents.js";
 import { canPickAgentsInteractively } from "../utils/agent_picker.js";
-import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { skillsHelpValues, skillsYesHelp } from "../skills/catalog.js";
 import { mappedSkillsAgentNames, skillsInstallableAgents } from "../skills/targets.js";
 import { confirmSkillsInstall, confirmSkillsUpdate } from "../skills/wizard.js";

package/dist/init/bootstrap.js

@@ -305,12 +305,7 @@ const downloadTemplate = async (template) => {
 	if (files.length === 0) throw new Error(`Template subdirectory "${subdir}" was not found in ${owner}/${repo}@${ref}.`);
 	return files;
 };
-/**
-* A bad caller-supplied input that an agent (or human) can correct: an unknown
-* template id or a non-empty target directory. Carries an `agentCode` so an
-* agent surface can report a precise error code instead of a generic
-* INTERNAL_ERROR, while a human path just surfaces the clear `message`.
-*/
+/** `agentCode` lets programmatic callers branch without parsing human-readable messages. */
 var BootstrapInputError = class extends Error {
 	constructor(message, agentCode) {
 		super(message);

package/dist/utils/cli_name.js

@@ -1,17 +1,6 @@
 import { basename } from "node:path";
 //#region src/utils/cli_name.ts
-/**
-* The name this CLI was invoked as: `neon` (current) or `neonctl` (legacy alias).
-*
-* Use this for any user-facing string that suggests a command to run — help text,
-* error hints, and especially `--agent` `next_command_template` values, which an agent
-* executes verbatim. Hardcoding `neonctl` breaks those on installs of the `neon` package,
-* which no longer ships a `neonctl` binary (removed in `neon@2.38.0`).
-*
-* Derived from `process.argv[1]`, which is fixed for the process lifetime, so the result
-* is stable whether this is called at module load or per invocation. Mirrors the name used
-* for yargs `.scriptName()` in `index.ts`.
-*/
+/** Command hints must use the invoked binary so users can run them verbatim. */
 const getCliName = () => basename(process.argv[1] ?? "") === "neonctl" ? "neonctl" : "neon";
 //#endregion
 export { getCliName };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "4.5.2",
+  "version": "4.7.0",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -64,8 +64,8 @@
     "yargs": "17.7.2",
     "yoctocolors": "^2.1.2",
     "@neon/config": "1.0.4",
-    "@neon/config-runtime": "1.0.4",
-    "@neon/sdk": "2.3.0"
+    "@neon/sdk": "2.3.0",
+    "@neon/config-runtime": "1.0.4"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0",