neon 4.17.0 → 4.17.1

package/README.md

@@ -742,7 +742,7 @@ When a package cannot be bundled — a native addon with no esbuild loader, or a
 
 `neon bootstrap` copies a Neon starter template into a new (or current) directory — conceptually like `degit`, but it only pulls from a small set of templates we maintain in the public [`neondatabase/examples`](https://github.com/neondatabase/examples) repo. The template copy needs no Neon login: it downloads files from GitHub.
 
-After scaffolding, an interactive terminal asks about dependency install, git, agent tooling (the Neon plugin, or skills and MCP separately — never both), and `neon link` before running those steps. Dependency install is last, except when the template has a `neon.ts` and you chose to link — then install runs first so link can pull env. `--default` / `-y` skips the template, install, git, and agent pickers, then installs agent tooling for project folders, else the host CLI agent. If none are found, it exits: pass `--agent <name>`, run from a supported agent, or omit `--default` / `-y` in a terminal to pick. `--agent` / `-a` names coding agents, skips agent selection, and is forwarded to `plugins`, or to `skills` and `mcp`, not both. `link --yes` still asks for a project unless one is already linked. `--no-agent-setup` and `--no-link` skip those. Non-interactive without `--default` prints next steps and does not install, set up agents, or link.
+After scaffolding, an interactive terminal asks about dependency install and git, then finishes agent setup before asking whether to link a Neon project. Dependency install is last, except when the template has a `neon.ts` and you chose to link — then install runs first so the link flow can pull env. `--default` / `-y` skips the template, install, git, and agent pickers, then installs agent tooling for project folders, else the host CLI agent. If none are found, it exits: pass `--agent <name>`, run from a supported agent, or omit `--default` / `-y` in a terminal to pick. `--agent` / `-a` names coding agents, skips agent selection, and is forwarded to `plugins`, or to `skills` and `mcp`, not both. Project selection may still be required. `--no-agent-setup` and `--no-link` skip those steps. Non-interactive without `--default` prints next steps and does not install, set up agents, or link.
 
 Pass a target directory (or `.` for the current one). In an interactive terminal you pick the template from a list; in CI / non-interactive contexts pass `--template <id>`.
 
@@ -773,18 +773,19 @@ An empty directory (nothing except `.git`) asks how to set up the directory. Pic
 
 `-y` in an empty directory scaffolds the default template (`bootstrap --default`) and does not add a later `config init` step. `--skip-template` skips scaffolding even with `-y`. `--template <id>` scaffolds that template; combine it with `-y` to skip the remaining bootstrap pickers.
 
-An existing app (or skip-template) installs agent tooling, then `neon link --no-config` unless `.neon` already has a projectId, then asks whether to create `neon.ts`. Saying no skips the services picker and does not write the file. `--no-config` does the same without asking. `-y` writes `config init --services none` unless `--no-config`. `--services` implies creating `neon.ts`.
+An existing app (or skip-template) installs agent tooling, then asks whether to link unless `.neon` already has a projectId, then asks whether to create `neon.ts`. Linking uses the same organization, project, and branch flow as `neon link`. Saying no to `neon.ts` skips the services picker and does not write the file. `--no-config` does the same without asking. `-y` writes `config init --services none` unless `--no-config`. `--services` implies creating `neon.ts`.
 
-In an interactive terminal it offers one of: the Neon plugin (`neon plugins`), skills and MCP separately (`neon skills`, then `neon mcp`), or skip agent setup. It never runs plugin and skills+MCP together.
+In an interactive terminal it offers one of: the Neon plugin (`neon plugins`), skills and MCP separately (`neon skills`, then `neon mcp`), or skip agent setup. Agent selection and setup finish before the link question. It never runs plugin and skills+MCP together.
 
 ```bash
 $ neon init
 $ neon init --skip-template
+$ neon init --skip-template --no-link
 $ neon init -y
 $ neon init --agent cursor --agent claude-code
 ```
 
-Without a TTY, pass `-y`. `--agent` skips agent selection but does not replace `-y` for link or templates.
+Without a TTY, pass `-y`. `--agent` skips agent selection but does not replace `-y` for link or templates. `--no-link` skips project linking without asking, including when a template is scaffolded.
 
 `-y` skips the template picker and the agent-setup offer. Empty dir: `bootstrap --default`. `--skip-template` or an existing app: plugin when Cursor, Claude Code, or Codex is in project folders, else the host CLI agent; otherwise skills and MCP. If none are found, it exits: pass `--agent <name>`, run from a supported agent, or omit `-y` in a terminal to pick. VS Code, GitHub Copilot CLI, and Grok only take the plugin user-level (`neon plugins --global`), so `-y` uses skills and MCP for those.
 
@@ -794,7 +795,7 @@ Without a TTY, pass `-y`. `--agent` skips agent selection but does not replace `
 
 `--config`, `--no-config`, and `--services` apply on the existing-app and `--skip-template` path. A template's own `neon.ts` is left as the template shipped it. Passing those flags while scaffolding prints a warning and still copies the template as shipped. After a new `neon.ts` on a pinned branch, init runs `env pull`.
 
-`-y` forwards `-y` to `plugins` or `skills`/`mcp`, `--default` to nested bootstrap, `--yes --no-config` to `link`, and `--services none` to `config init`. `--agent` is forwarded with them. `mcp -y` is the global install. `link --yes` only skips the "already linked" confirmation; it still asks for a project unless one is already linked.
+`-y` forwards `-y` to `plugins` or `skills`/`mcp`, uses default choices in the built-in link flow, passes `--default` to nested bootstrap, and forwards `--services none` to `config init`. `--agent` is forwarded to agent setup. `mcp -y` is the global install. Default linking skips the "already linked" confirmation; it can still require project selection.
 
 A failed step stops the rest. `--profile` and `--config-dir` are forwarded to each child. `--output json` and `--output yaml` are refused; the commands init runs print their own output.
 
@@ -1228,7 +1229,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` forwards `--profile` and `--config-dir` to the commands it runs. An explicit `--api-key` is passed to those children through `NEON_API_KEY`, not argv.
+`neon init` forwards `--profile` and `--config-dir` to agent and config children and uses them directly for its link flow. An explicit `--api-key` is passed to authenticated children through `NEON_API_KEY`, not argv.
 
 ## API passthrough (`api`)
 

package/dist/auth_recovery.js

@@ -0,0 +1,61 @@
+import { t as storeFor } from "./_chunks/credential_io-D8AR-jvB.js";
+import { log } from "./log.js";
+import { authFailureMessage, getAuthContext, locationFromContext } from "./auth_context.js";
+import { AuthRefreshError } from "./auth.js";
+import { isAccessTokenUsable, refreshStoredCredentials } from "./commands/auth.js";
+//#region src/auth_recovery.ts
+const supersededOnDisk = (rejectedToken) => {
+	if (rejectedToken === void 0) return false;
+	const context = getAuthContext();
+	if (context === null) return false;
+	const at = locationFromContext(context);
+	if (at === null) return false;
+	try {
+		const loaded = storeFor(context.configDir).read(at);
+		return loaded !== null && loaded.credentials.access_token !== rejectedToken && isAccessTokenUsable(loaded.credentials, Date.now());
+	} catch {
+		return false;
+	}
+};
+const recoverFrom401 = async (canRetry) => {
+	const context = getAuthContext();
+	if (context === null || context.source !== "stored-credentials") {
+		log.error(authFailureMessage(context));
+		return false;
+	}
+	if (context.refreshed === true || !canRetry) {
+		log.error(authFailureMessage(context));
+		return false;
+	}
+	if (supersededOnDisk(context.accessToken)) {
+		log.debug("The rejected token has already been replaced on disk; retrying with the current one");
+		return true;
+	}
+	const at = locationFromContext(context);
+	if (at === null || context.oauthHost === void 0 || context.clientId === void 0) {
+		log.error(authFailureMessage(context));
+		return false;
+	}
+	try {
+		if (await refreshStoredCredentials(at, {
+			apiHost: "",
+			oauthHost: context.oauthHost,
+			clientId: context.clientId,
+			configDir: context.configDir
+		})) {
+			log.debug("Refreshed the stored session after a 401; retrying");
+			return true;
+		}
+	} catch (err) {
+		if (err instanceof AuthRefreshError) {
+			log.error(err.message);
+			if (err.terminal) log.error(`Run \`neon auth --profile ${context.profile ?? "DEFAULT"}\` to sign in again.`);
+			return false;
+		}
+		log.debug("Refresh after 401 failed: %s", err instanceof Error ? err.message : "unknown error");
+	}
+	log.error(authFailureMessage(context));
+	return false;
+};
+//#endregion
+export { recoverFrom401 };

package/dist/commands/bootstrap.js

@@ -1,19 +1,20 @@
 import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 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-pitMFzDe.js";
+import { getCliName } from "../utils/cli_name.js";
+import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { writer } from "../writer.js";
 import { FALLBACK_TEMPLATES, ensureTargetUsable, fetchTemplates, findTemplate, scaffoldTemplate, templateIds } from "../init/bootstrap.js";
 import { spawnCliChild } from "../init/child.js";
 import { agentSetupDoneLabel, formatInitDone, printInitBanner, printInitDone, shouldPrintInitBanner } from "../init/chrome.js";
+import { formatInstallCommand, inferPackageManager, installArgs, installedPackageManagers, resolvePackageManager, runCommand } from "../utils/package_manager.js";
+import { runAuthenticatedLink } from "../init/link.js";
 import { coerceAgentFlag } from "../utils/agent_flag.js";
-import { assertNamedAgentTooling, chooseYesAgentTooling, initPluginAgents, initSkillsMcpAgents, planLinkStep, postScaffoldActions, projectContextFile, resolveNamedAgents } from "../init/plan.js";
+import { assertNamedAgentTooling, chooseYesAgentTooling, initPluginAgents, initSkillsMcpAgents, postScaffoldActions, projectContextFile, resolveNamedAgents } from "../init/plan.js";
 import { formatTemplateTitle } from "../init/template_title.js";
-import { pickAgentSetupInteractively } from "../init/wizard.js";
-import { runAgentTooling, runInitSteps } from "../init/tooling.js";
-import { helpCsv, helpEpilogue } from "../utils/help_text.js";
-import { formatInstallCommand, inferPackageManager, installArgs, installedPackageManagers, resolvePackageManager, runCommand } from "../utils/package_manager.js";
+import { pickAgentSetupInteractively, pickInitLinkInteractively } from "../init/wizard.js";
+import { runAgentTooling } from "../init/tooling.js";
 import { existsSync } from "node:fs";
 import { join, relative, resolve } from "node:path";
 import prompts from "prompts";
@@ -47,7 +48,7 @@ const builder = (argv) => argv.usage("$0 bootstrap [directory] [options]").posit
 	},
 	default: {
 		alias: "y",
-		describe: "Quick start: scaffold the default template (or --template), then install, git, agent tooling (project folders, else the host CLI agent; if none, pass --agent or omit --default in a terminal), and link --yes. Skips those pickers; link --yes still asks for a project unless one is already linked",
+		describe: "Quick start: scaffold the default template (or --template), then install, git, agent tooling (project folders, else the host CLI agent; if none, pass --agent or omit --default in a terminal), and link with defaults. Project selection may still be required",
 		type: "boolean",
 		default: false
 	},
@@ -62,7 +63,7 @@ const builder = (argv) => argv.usage("$0 bootstrap [directory] [options]").posit
 		default: true
 	},
 	link: {
-		describe: `Run \`${getCliName()} link\` after scaffolding. Templates with neon.ts link after install so env pull works; otherwise link runs before install. In interactive mode this is offered as a prompt; use --no-link to skip without being asked.`,
+		describe: "Link a Neon project after scaffolding. Templates with neon.ts link after install so env pull works; otherwise linking happens before install. In interactive mode this is offered as a prompt; use --no-link to skip without being asked.",
 		type: "boolean",
 		default: true
 	},
@@ -78,7 +79,7 @@ const builder = (argv) => argv.usage("$0 bootstrap [directory] [options]").posit
 		describe: "Coding agent to install into (repeatable). Forwarded to plugins, or to skills and mcp. Skips agent selection. Values listed below",
 		coerce: coerceAgentFlag
 	}
-}).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", "Skip the pickers; link --yes still asks for a project unless one is already linked").example("$0 bootstrap --list-templates --output json", "Print the template catalog as JSON").example("$0 bootstrap my-app --agent cursor --agent claude-code", "Skip agent selection; install the plugin for those agents").epilogue(helpEpilogue("--agent / -a is forwarded to plugins, or to skills and mcp, not both. It skips agent selection, including with --default.", helpCsv("Plugin agents", initPluginAgents()), helpCsv("Skills and MCP agents", initSkillsMcpAgents()))).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", "Skip the pickers; project selection may still be required").example("$0 bootstrap --list-templates --output json", "Print the template catalog as JSON").example("$0 bootstrap my-app --agent cursor --agent claude-code", "Skip agent selection; install the plugin for those agents").epilogue(helpEpilogue("--agent / -a is forwarded to plugins, or to skills and mcp, not both. It skips agent selection, including with --default.", helpCsv("Plugin agents", initPluginAgents()), helpCsv("Skills and MCP agents", initSkillsMcpAgents()))).strict();
 const handler = async (props) => {
 	if (props.listTemplates) {
 		const templates = await fetchTemplates();
@@ -215,7 +216,6 @@ const runPostScaffoldSteps = async (props, targetDir, interactive, template, nam
 	const agentSetup = props.agentSetup === false ? "skip" : named.length > 0 ? chooseYesAgentTooling(named).setup : await (props.pickAgentSetup ?? pickAgentSetupInteractively)();
 	const canLink = props.link && !(neonConfig && !wantInstall);
 	if (props.link && !canLink) logSkippedLink(pm);
-	const wantLink = canLink && await confirm(`Link this project to a Neon project now? (runs ${getCliName()} link)`);
 	const outcome = await executePostScaffold(props, targetDir, {
 		yes: false,
 		lockAgentSetup: named.length === 0,
@@ -223,7 +223,7 @@ const runPostScaffoldSteps = async (props, targetDir, interactive, template, nam
 		git: wantGit,
 		agentSetup,
 		install: wantInstall,
-		link: wantLink,
+		link: canLink,
 		hasNeonConfig: neonConfig,
 		named
 	});
@@ -239,9 +239,8 @@ const runPostScaffoldSteps = async (props, targetDir, interactive, template, nam
 	return nestedResult(template, targetDir, neonConfig, outcome);
 };
 const installPrompt = (inferred) => inferred ? `Install dependencies with ${inferred}?` : "Install dependencies?";
-/** `link --yes` still asks for a project unless one is already linked. */
 const runDefaultSteps = async (props, targetDir, pm, neonConfig, template, named) => {
-	log.info("Quick start (--default): skipping the template, install, git, and agent pickers. link --yes still asks for a project unless one is already linked.");
+	log.info("Quick start (--default): skipping the template, install, git, and agent pickers. Project selection may still be required.");
 	const wantGit = props.git && !isGitRepo(targetDir);
 	const agentSetup = props.agentSetup === false ? "skip" : named.length > 0 ? chooseYesAgentTooling(named).setup : "skills-mcp";
 	const outcome = await executePostScaffold(props, targetDir, {
@@ -322,12 +321,26 @@ const executePostScaffold = async (props, targetDir, choices) => {
 			logSkippedLink(choices.pm);
 			continue;
 		}
-		await runInitSteps([props.linkNoConfig === true ? planLinkStep({
+		if (!(choices.yes || await (props.pickLink ?? pickInitLinkInteractively)())) continue;
+		await (props.linkProject ?? runAuthenticatedLink)({
+			apiClient: props.apiClient,
+			apiKey: props.apiKey,
+			apiHost: props.apiHost,
+			output: props.output,
+			contextFile: projectContextFile(targetDir, props.contextFile),
 			yes: choices.yes,
-			extra: props.linkExtra
-		}) : choices.yes ? ["link", "--yes"] : ["link"]], {
+			clear: false,
+			checks: true,
+			envPull: true,
+			config: props.linkNoConfig !== true,
 			cwd: targetDir,
-			...kids
+			...props.linkInputs,
+			...props.configDir ? { configDir: props.configDir } : {},
+			...props.profile ? { profile: props.profile } : {},
+			...props.oauthHost ? { oauthHost: props.oauthHost } : {},
+			...props.clientId ? { clientId: props.clientId } : {},
+			...props.forceAuth !== void 0 ? { forceAuth: props.forceAuth } : {},
+			...props.allowUnsafeTls !== void 0 ? { allowUnsafeTls: props.allowUnsafeTls } : {}
 		});
 		linked = true;
 	}

package/dist/commands/branches.js

@@ -3,13 +3,13 @@ import { log } from "../log.js";
 import { retryOnLock } from "../api.js";
 import { contextBranch, readContextFile } from "../context.js";
 import { writer } from "../writer.js";
-import { branchCreateRequest } from "../parameters.gen.js";
 import { EndpointType } from "../utils/api_enums.js";
-import { getComputeUnits } from "../utils/compute_units.js";
 import { looksLikeBranchId, looksLikeLSN, looksLikeTimestamp } from "../utils/formats.js";
 import { branchIdFromProps, branchIdResolve, fillSingleProject } from "../utils/enrichers.js";
-import { parsePointInTime } from "../utils/point_in_time.js";
+import { branchCreateRequest } from "../parameters.gen.js";
+import { getComputeUnits } from "../utils/compute_units.js";
 import { psql } from "../utils/psql.js";
+import { parsePointInTime } from "../utils/point_in_time.js";
 import { parseSchemaDiffParams, schemaDiff } from "./schema_diff.js";
 //#region src/commands/branches.ts
 var branches_exports = /* @__PURE__ */ __exportAll({

package/dist/commands/checkout.js

@@ -4,9 +4,9 @@ import { log } from "../log.js";
 import { isNeonApiError } from "../api.js";
 import { applyContext, contextBranch, readContextFile } from "../context.js";
 import { getCliName } from "../utils/cli_name.js";
+import { createBranch, pickBranchInteractively } from "../utils/branch_picker.js";
 import { looksLikeBranchId } from "../utils/formats.js";
 import { fillSingleProject } from "../utils/enrichers.js";
-import { createBranch, pickBranchInteractively } from "../utils/branch_picker.js";
 import { autoPullEnvAfterPin } from "./env.js";
 import { applyPolicyOnCreate, createBranchFromPolicyOnCheckout, envFlag } from "./config.js";
 import { handler as handler$1 } from "./link.js";

package/dist/commands/claim.js

@@ -3,12 +3,12 @@ import { isCi } from "../env.js";
 import { log } from "../log.js";
 import { getApiClient } from "../api.js";
 import { applyContext, contextBranch, readContextFile } from "../context.js";
-import { claimableDataApiCreateBody, declaredNeonServices } from "../config_services.js";
-import { NEON_SERVICES, deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOption } from "../neon_services.js";
-import { resolveEnvFilePath } from "../env_file.js";
 import { t as credentialInputs } from "../_chunks/auth_selection-pitMFzDe.js";
 import { ClaimableClient, ClaimableServiceError } from "../claimable/api.js";
 import { assertionHasExpired, listClaimableCredentials, readClaimableCredentials, readLinkedClaimableCredentials, removeClaimableCredentials, writeClaimableCredentials } from "../claimable/state.js";
+import { claimableDataApiCreateBody, declaredNeonServices } from "../config_services.js";
+import { NEON_SERVICES, deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOption } from "../neon_services.js";
+import { resolveEnvFilePath } from "../env_file.js";
 import { writer } from "../writer.js";
 import { noPassthrough } from "../utils/flags.js";
 import { pull } from "./env.js";

package/dist/commands/config.js

@@ -10,11 +10,11 @@ import { deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOpt
 import { CONFIG_INIT_NONE_MEANS, CONFIG_INIT_SERVICES, CONFIG_INIT_UNAVAILABLE, FUNCTION_FILENAME, FUNCTION_SLUG, FUNCTION_TEMPLATE, REQUIRED_PACKAGES, renderNeonConfig, renderNeonConfigFromView } from "../config_template.js";
 import { loadEnvFileIntoProcess } from "../env_file.js";
 import { writer } from "../writer.js";
-import { formatInstallCommand, installArgs, resolvePackageManager, runCommand } from "../utils/package_manager.js";
-import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
 import { assertAiGatewayProvisionable, warnAiGateway } from "../utils/ai_gateway_notice.js";
 import { announceTargetBranch } from "../utils/branch_notice.js";
 import { renderAppliedChanges, renderBranchSettingConflicts } from "../utils/config_diff.js";
+import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
+import { formatInstallCommand, installArgs, resolvePackageManager, runCommand } from "../utils/package_manager.js";
 import { bundleEntry } from "../utils/esbuild.js";
 import { pickServicesInteractively } from "../utils/service_picker.js";
 import { zipBundle } from "../utils/zip.js";

package/dist/commands/connection_string.js

@@ -2,8 +2,8 @@ import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { writer } from "../writer.js";
 import { EndpointType } from "../utils/api_enums.js";
 import { branchIdFromProps, fillSingleProject } from "../utils/enrichers.js";
-import { parsePITBranch } from "../utils/point_in_time.js";
 import { psql } from "../utils/psql.js";
+import { parsePITBranch } from "../utils/point_in_time.js";
 //#region src/commands/connection_string.ts
 var connection_string_exports = /* @__PURE__ */ __exportAll({
 	SSL_MODES: () => SSL_MODES,

package/dist/commands/dev.js

@@ -1,9 +1,9 @@
 import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { log } from "../log.js";
+import { isClaimableEnvTarget } from "../claimable/state.js";
 import { getCliName } from "../utils/cli_name.js";
 import { readEnvFile, resolveEnvFilePath } from "../env_file.js";
 import { y as functionBaseUrlKey } from "../_chunks/env_services-CbARRnq9.js";
-import { isClaimableEnvTarget } from "../claimable/state.js";
 import { branchIdResolve } from "../utils/enrichers.js";
 import { bundleEntry } from "../utils/esbuild.js";
 import { a as resolveDevEnv } from "../_chunks/env-B75xufe_.js";

package/dist/commands/env.js

@@ -1,14 +1,14 @@
 import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { log } from "../log.js";
 import { ensureGitignored } from "../context.js";
+import { isClaimableEnvTarget } from "../claimable/state.js";
 import { getCliName } from "../utils/cli_name.js";
 import { deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOption } from "../neon_services.js";
 import { mergeEnvFile, readEnvFile, resolveEnvFilePath } from "../env_file.js";
 import { a as envKeysForSelection, b as isFunctionBaseUrlKey, c as ownedEnvServiceKeys, f as NEON_ENV_VAR_KEYS, i as ENV_PULL_SERVICES, l as parseEnvPullKeys, o as envPullFlagValue, r as ENV_PULL_KEY_HELP } from "../_chunks/env_services-CbARRnq9.js";
-import { isClaimableEnvTarget } from "../claimable/state.js";
-import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
 import { warnAiGateway } from "../utils/ai_gateway_notice.js";
 import { announceTargetBranch } from "../utils/branch_notice.js";
+import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
 import { i as dropClaimableUnsupported, o as resolveNeonEnvVars } from "../_chunks/env-B75xufe_.js";
 import { existsSync } from "node:fs";
 import chalk from "chalk";

package/dist/commands/index.js

@@ -2,13 +2,13 @@ import { t as auth_exports } from "./auth.js";
 import { t as api_exports } from "./api.js";
 import { t as api_keys_exports } from "./api_keys.js";
 import { t as ask_exports } from "./ask.js";
-import { t as bootstrap_exports } from "./bootstrap.js";
-import { t as branches_exports } from "./branches.js";
-import { t as bucket_exports } from "./bucket.js";
 import { t as env_exports } from "./env.js";
 import { t as config_exports } from "./config.js";
 import { t as projects_exports } from "./projects.js";
 import { t as link_exports } from "./link.js";
+import { t as bootstrap_exports } from "./bootstrap.js";
+import { t as branches_exports } from "./branches.js";
+import { t as bucket_exports } from "./bucket.js";
 import { t as checkout_exports } from "./checkout.js";
 import { t as claim_exports } from "./claim.js";
 import { t as connection_string_exports } from "./connection_string.js";

package/dist/commands/init.js

@@ -1,21 +1,22 @@
 import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { log } from "../log.js";
 import { contextBranch, readContextFile } from "../context.js";
+import { t as credentialInputs } from "../_chunks/auth_selection-pitMFzDe.js";
 import { getCliName } from "../utils/cli_name.js";
 import { deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOption } from "../neon_services.js";
 import { CONFIG_INIT_NONE_MEANS, CONFIG_INIT_SERVICES, CONFIG_INIT_UNAVAILABLE } from "../config_template.js";
-import { t as credentialInputs } from "../_chunks/auth_selection-pitMFzDe.js";
+import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { fetchTemplates } from "../init/bootstrap.js";
 import { initChildEnv, spawnCliChild } from "../init/child.js";
 import { agentSetupLabel, configSummaryLabel, formatInitDone, printInitBanner, printInitDone, shouldPrintInitBanner } from "../init/chrome.js";
+import { hasNeonConfigFile } from "./config.js";
+import { runAuthenticatedLink } from "../init/link.js";
 import { coerceAgentFlag } from "../utils/agent_flag.js";
-import { INIT_NEEDS_YES_OR_TERMINAL, assertNamedAgentTooling, directoryIsEmpty, initPluginAgents, initSkillsMcpAgents, linkInputArgv, planExistingInit, resolveNamedAgents } from "../init/plan.js";
+import { INIT_NEEDS_YES_OR_TERMINAL, assertNamedAgentTooling, directoryIsEmpty, initPluginAgents, initSkillsMcpAgents, planExistingInit, resolveNamedAgents } from "../init/plan.js";
 import { canPickAgentsInteractively } from "../utils/agent_picker.js";
-import { pickInitConfigInteractively, pickInitTemplateInteractively } from "../init/wizard.js";
+import { pickInitConfigInteractively, pickInitLinkInteractively, pickInitTemplateInteractively } from "../init/wizard.js";
 import { runAgentTooling, runInitSteps } from "../init/tooling.js";
-import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { handler as handler$1 } from "./bootstrap.js";
-import { hasNeonConfigFile } from "./config.js";
 import { INIT_CONFIG_SERVICES_CONFLICT, INIT_TEMPLATE_KEEPS_CONFIG, configPlanFromResolution, resolveInitConfigChoice, resolveInitTemplateChoice, shouldRefreshEnvAfterNewConfig } from "../init/choices.js";
 import { existsSync, readdirSync } from "node:fs";
 import { resolve } from "node:path";
@@ -34,7 +35,7 @@ const builder = (yargs) => yargs.usage("$0 init [options]").option("context-file
 	alias: "y",
 	type: "boolean",
 	default: false,
-	describe: "Empty dir: scaffold the default template. --skip-template: plugin, or skills and MCP, for project folders, else the host CLI agent. Exits if none. Then link --yes and config init --services none. link --yes still asks for a project unless one is already linked"
+	describe: "Empty dir: scaffold the default template. --skip-template: plugin, or skills and MCP, for project folders, else the host CLI agent. Exits if none. Then link with defaults and create the bare neon.ts policy. Project selection may still be required"
 }).option("skip-template", {
 	type: "boolean",
 	default: false,
@@ -42,6 +43,10 @@ const builder = (yargs) => yargs.usage("$0 init [options]").option("context-file
 }).option("template", {
 	type: "string",
 	describe: "Template to scaffold into an empty directory. Conflicts with --skip-template"
+}).option("link", {
+	type: "boolean",
+	default: true,
+	describe: "Link a Neon project during setup. Use --no-link to skip without being asked"
 }).option("config", {
 	type: "boolean",
 	describe: "Existing app or --skip-template: create neon.ts after linking. Use --no-config to skip. Omitted in a terminal: you will be asked. Scaffolding a template keeps that template's neon.ts"
@@ -80,7 +85,7 @@ const builder = (yargs) => yargs.usage("$0 init [options]").option("context-file
 	alias: "o",
 	hidden: true,
 	describe: "Not supported; the commands init runs print their own output"
-}).example("$0 init", "Set up this directory (template picker if empty)").example("$0 init --skip-template", "Empty dir: agents, link, and neon.ts — no template files").example("$0 init -y", "Default template, or existing-app defaults").example("$0 init --agent cursor --agent claude-code", "Skip agent selection; install the plugin for those agents").epilogue(helpEpilogue("Empty directory: pick a starter template, or skip scaffolding and only set up agents, a Neon project, and neon.ts. That skip is not on `neon bootstrap`.", "Interactive agent setup: plugin (recommended), skills and MCP separately, or skip agent setup. Never both plugin and skills+MCP.", "neon.ts is optional when you skip the template or set up an existing app. Saying no skips the services picker and does not write the file. Scaffolding a template keeps that template's neon.ts.", "-y installs the plugin when Cursor, Claude Code, or Codex is in project folders, else the host CLI agent. Otherwise skills and MCP. If none are found, it exits: pass --agent <name>, run from a supported agent, or omit -y in a terminal to pick. Then link unless already linked. link --yes may still ask for a project.", "--agent / -a is forwarded to plugins, or to skills and mcp, not both. It skips agent selection, including with -y.", helpCsv("Plugin agents", initPluginAgents()), helpCsv("Skills and MCP agents", initSkillsMcpAgents()))).check((argv) => {
+}).example("$0 init", "Set up this directory (template picker if empty)").example("$0 init --skip-template", "Empty dir: agents, link, and neon.ts — no template files").example("$0 init -y", "Default template, or existing-app defaults").example("$0 init --agent cursor --agent claude-code", "Skip agent selection; install the plugin for those agents").epilogue(helpEpilogue("Empty directory: pick a starter template, or skip scaffolding and only set up agents, a Neon project, and neon.ts. That skip is not on `neon bootstrap`.", "Interactive agent setup: plugin (recommended), skills and MCP separately, or skip agent setup. Never both plugin and skills+MCP.", "neon.ts is optional when you skip the template or set up an existing app. Saying no skips the services picker and does not write the file. Scaffolding a template keeps that template's neon.ts.", "-y installs the plugin when Cursor, Claude Code, or Codex is in project folders, else the host CLI agent. Otherwise skills and MCP. If none are found, it exits: pass --agent <name>, run from a supported agent, or omit -y in a terminal to pick. Then link unless already linked. Project selection may still be required.", "--agent / -a is forwarded to plugins, or to skills and mcp, not both. It skips agent selection, including with -y.", helpCsv("Plugin agents", initPluginAgents()), helpCsv("Skills and MCP agents", initSkillsMcpAgents()))).check((argv) => {
 	if (argv.data !== void 0) throw new Error(removedProtocol());
 	if (argv.help !== true && (argv.output === "json" || argv.output === "yaml")) throw new Error(`\`${getCliName()} init\` does not support --output. The commands it runs print their own output.`);
 	return true;
@@ -101,7 +106,7 @@ const parsedInitServices = (raw) => {
 		onDeprecated: (used, canonical) => log.warning(deprecatedServiceMessage(used, canonical))
 	});
 };
-const nestedBootstrapProps = (props, cwd, contextFile, template, linkExtra) => ({
+const nestedBootstrapProps = (props, cwd, contextFile, template, linkInputs) => ({
 	apiClient: props.apiClient,
 	apiKey: props.apiKey,
 	apiHost: props.apiHost,
@@ -113,19 +118,25 @@ const nestedBootstrapProps = (props, cwd, contextFile, template, linkExtra) => (
 	default: template.useDefault,
 	install: true,
 	git: true,
-	link: true,
+	link: props.link !== false,
 	printBanner: false,
 	skipDoneSummary: true,
 	linkNoConfig: true,
 	narrate: "human",
 	...template.selected ? { selectedTemplate: template.selected } : {},
 	...!template.selected && template.id !== void 0 ? { template: template.id } : {},
-	...linkExtra.length > 0 ? { linkExtra } : {},
+	linkInputs,
 	...props.agent !== void 0 ? { agent: props.agent } : {},
 	...props.configDir ? { configDir: props.configDir } : {},
 	...props.profile ? { profile: props.profile } : {},
+	...props.oauthHost ? { oauthHost: props.oauthHost } : {},
+	...props.clientId ? { clientId: props.clientId } : {},
+	...props.forceAuth !== void 0 ? { forceAuth: props.forceAuth } : {},
+	...props.allowUnsafeTls !== void 0 ? { allowUnsafeTls: props.allowUnsafeTls } : {},
 	...props.analytics === false ? { analytics: false } : {},
 	...props.run ? { run: props.run } : {},
+	...props.linkProject ? { linkProject: props.linkProject } : {},
+	...props.pickLink ? { pickLink: props.pickLink } : {},
 	...props.pickAgentSetup ? { pickAgentSetup: props.pickAgentSetup } : {},
 	...props.detectProjectAgents ? { detectProjectAgents: props.detectProjectAgents } : {},
 	...props.detectAgent ? { detectAgent: props.detectAgent } : {},
@@ -193,13 +204,14 @@ const handler = async (props) => {
 	};
 	const services = parsedInitServices(props.services);
 	if (props.config === false && services !== void 0) throw new Error(INIT_CONFIG_SERVICES_CONFLICT);
-	const linkExtra = linkInputArgv({
+	const linkInputs = {
 		...props.orgId ? { orgId: props.orgId } : {},
 		...props.projectId ? { projectId: props.projectId } : {},
 		...props.projectName ? { projectName: props.projectName } : {},
 		...props.regionId ? { regionId: props.regionId } : {},
 		...props.branch ? { branch: props.branch } : {}
-	});
+	};
+	const hasExplicitLinkInputs = props.orgId !== void 0 || props.projectId !== void 0 || props.projectName !== void 0 || props.regionId !== void 0 || props.branch !== void 0;
 	const templateChoice = resolveInitTemplateChoice({
 		empty: directoryIsEmpty(names),
 		yes,
@@ -214,7 +226,7 @@ const handler = async (props) => {
 		const result = await runBootstrap(nestedBootstrapProps(props, cwd, contextFile, {
 			useDefault: yes,
 			...templateChoice.kind === "template" ? { id: templateChoice.id } : {}
-		}, linkExtra));
+		}, linkInputs));
 		printNestedBootstrapDone(result, cwd, templateChoice.kind === "template" ? templateChoice.id : "default");
 		return;
 	}
@@ -228,13 +240,13 @@ const handler = async (props) => {
 			const result = await runBootstrap(nestedBootstrapProps(props, cwd, contextFile, {
 				selected: picked.template,
 				useDefault: false
-			}, linkExtra));
+			}, linkInputs));
 			printNestedBootstrapDone(result, cwd, picked.template.id);
 			return;
 		}
 	}
 	const alreadyLinked = isLinked(contextFile);
-	const shouldLink = !alreadyLinked || linkExtra.length > 0;
+	const shouldLink = props.link !== false && (!alreadyLinked || hasExplicitLinkInputs);
 	const existingConfig = hasNeonConfigFile(cwd);
 	const canAskConfig = props.pickConfig !== void 0 || canPickAgentsInteractively();
 	const agentSetup = await runAgentTooling({
@@ -251,18 +263,27 @@ const handler = async (props) => {
 		...props.detectAgent ? { detectAgent: props.detectAgent } : {},
 		...props.hasProjectPlugins ? { hasProjectPlugins: props.hasProjectPlugins } : {}
 	});
-	await runInitSteps(planExistingInit({
-		linked: !shouldLink,
+	const canAskLink = props.pickLink !== void 0 || canPickAgentsInteractively();
+	const acceptedLink = shouldLink && (yes || !canAskLink || await (props.pickLink ?? pickInitLinkInteractively)());
+	if (acceptedLink) await (props.linkProject ?? runAuthenticatedLink)({
+		apiClient: props.apiClient,
+		apiKey: props.apiKey,
+		apiHost: props.apiHost,
+		output: props.output,
+		contextFile,
 		yes,
-		agentSetup: "skip",
-		config: { kind: "skip" },
-		...linkExtra.length > 0 ? { linkExtra } : {}
-	}), {
+		clear: false,
+		checks: true,
+		envPull: true,
+		config: false,
 		cwd,
-		run,
-		forward,
-		authEnv,
-		narrate: "human"
+		...linkInputs,
+		...props.configDir ? { configDir: props.configDir } : {},
+		...props.profile ? { profile: props.profile } : {},
+		...props.oauthHost ? { oauthHost: props.oauthHost } : {},
+		...props.clientId ? { clientId: props.clientId } : {},
+		...props.forceAuth !== void 0 ? { forceAuth: props.forceAuth } : {},
+		...props.allowUnsafeTls !== void 0 ? { allowUnsafeTls: props.allowUnsafeTls } : {}
 	});
 	const configResolution = resolveInitConfigChoice({
 		flag: props.config,
@@ -317,7 +338,7 @@ Run \`${getCliName()} env pull\` once resolved.`, message);
 				label: "Project",
 				value: projectRow({
 					alreadyLinked,
-					linkedNow: shouldLink
+					linkedNow: acceptedLink
 				})
 			},
 			{

package/dist/commands/ip_allow.js

@@ -2,8 +2,8 @@ import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { log } from "../log.js";
 import { getCliName } from "../utils/cli_name.js";
 import { writer } from "../writer.js";
-import { projectUpdateRequest } from "../parameters.gen.js";
 import { fillSingleProject } from "../utils/enrichers.js";
+import { projectUpdateRequest } from "../parameters.gen.js";
 //#region src/commands/ip_allow.ts
 var ip_allow_exports = /* @__PURE__ */ __exportAll({
 	builder: () => builder,

package/dist/commands/link.js

@@ -16,6 +16,7 @@ var link_exports = /* @__PURE__ */ __exportAll({
 	command: () => command,
 	describe: () => describe,
 	handler: () => handler,
+	runLink: () => runLink,
 	shouldOfferConfigInit: () => shouldOfferConfigInit
 });
 const PROJECTS_LIST_LIMIT = 100;
@@ -94,7 +95,7 @@ const builder = (argv) => argv.usage("$0 link [options]").options({
 	["$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)).strict();
-const handler = async (props) => {
+const runLink = async (props) => {
 	if (props.clear) {
 		clearContext(props.contextFile);
 		return;
@@ -110,19 +111,16 @@ const handler = async (props) => {
 		await runNonInteractive(props, inputs, existing);
 		return;
 	}
-	if (!canPromptInteractively()) {
-		log.error([
-			"Missing inputs and no interactive terminal for prompts.",
-			"",
-			"Use:",
-			nonInteractiveLinkHelp(),
-			orgScopedKeyHint
-		].join("\n"));
-		process.exit(1);
-		return;
-	}
+	if (!canPromptInteractively()) throw new LinkInputError([
+		"Missing inputs and no interactive terminal for prompts.",
+		"",
+		"Use:",
+		nonInteractiveLinkHelp(),
+		orgScopedKeyHint
+	].join("\n"));
 	await runInteractive(props, inputs);
 };
+const handler = runLink;
 const parseInputs = (props) => {
 	let fromParams = {};
 	if (props.params !== void 0 && props.params !== "") {
@@ -430,7 +428,9 @@ const runNonInteractive = async (props, inputs, existing) => {
 	}
 };
 const runInteractive = async (props, inputs) => {
-	if (!props.yes) await confirmRelinkIfNeeded(props);
+	if (!props.yes) {
+		if (!await confirmRelinkIfNeeded(props)) return;
+	}
 	const orgResolution = await resolveOrg(props, inputs.orgId);
 	let orgId;
 	if (orgResolution.kind === "resolved") {
@@ -505,7 +505,7 @@ const runInteractive = async (props, inputs) => {
 };
 const confirmRelinkIfNeeded = async (props) => {
 	const existing = readContextFile(props.contextFile);
-	if (!existing.orgId || !existing.projectId) return;
+	if (!existing.orgId || !existing.projectId) return true;
 	const { proceed } = await prompts({
 		onState: onPromptState,
 		type: "confirm",
@@ -515,8 +515,9 @@ const confirmRelinkIfNeeded = async (props) => {
 	});
 	if (!proceed) {
 		process.stdout.write("Aborted. Existing link preserved.\n");
-		process.exit(0);
+		return false;
 	}
+	return true;
 };
 const promptOrgFromList = async (orgs) => {
 	if (!orgs.length) throw new Error(`You don't belong to any organizations. Create one in the Neon Console first: https://console.neon.tech/`);
@@ -734,6 +735,7 @@ const finalizeLink = async (props, summary) => {
 	const { config: _offerConfig, ...rest } = props;
 	await autoPullEnvAfterPin({
 		...rest,
+		...props.cwd ? { cwd: props.cwd } : {},
 		projectId: summary.projectId,
 		branch: summary.branch,
 		envPull: props.envPull
@@ -756,7 +758,7 @@ const finalizeInteractiveLink = async (props, summary) => {
 */
 const shouldOfferConfigInit = (input) => !input.hasConfig && input.offer;
 const maybeOfferConfigInit = async (props, summary) => {
-	const cwd = process.cwd();
+	const cwd = props.cwd ?? process.cwd();
 	if (!shouldOfferConfigInit({
 		hasConfig: hasNeonConfigFile(cwd),
 		offer: props.config !== false
@@ -777,6 +779,7 @@ const maybeOfferConfigInit = async (props, summary) => {
 		const { config: _offerConfig, ...rest } = props;
 		await autoPullEnvAfterPin({
 			...rest,
+			cwd,
 			projectId: summary.projectId,
 			branch: summary.branch,
 			envPull: props.envPull
@@ -795,4 +798,4 @@ const mustString = (value, name) => {
 	return value;
 };
 //#endregion
-export { builder, command, describe, handler, shouldOfferConfigInit, link_exports as t };
+export { builder, command, describe, handler, runLink, shouldOfferConfigInit, link_exports as t };

package/dist/commands/mcp.js

@@ -2,12 +2,12 @@ import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { log } from "../log.js";
 import { readContextFile } from "../context.js";
 import { getCliName } from "../utils/cli_name.js";
+import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { writer } from "../writer.js";
 import { noPassthrough, single } from "../utils/flags.js";
 import { NEON_MCP_CATEGORIES, NEON_MCP_URL, existingNeonApiKey, installNeonMcpServer, neonMcpUrl, parseMcpCategories, trackedProjectMcpConfig } from "../mcp/install.js";
 import { mcpInstallableAgents, resolveInstallTargets } from "../mcp/targets.js";
 import { canPickAgentsInteractively } from "../utils/agent_picker.js";
-import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { mintMcpApiKey, mintedKeyRevokeCommand, withdrawMintedKey } from "../mcp/mint.js";
 import { confirmMcpInstall } from "../mcp/wizard.js";
 import { resolveMcpPlan } from "../mcp/plan.js";

package/dist/commands/plugins.js

@@ -1,5 +1,6 @@
 import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { log } from "../log.js";
+import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { writer } from "../writer.js";
 import { noPassthrough } from "../utils/flags.js";
 import { getAgentDisplayName } from "../mcp/agents.js";
@@ -8,7 +9,6 @@ import "../init/agents.js";
 import { pluginsInstallableAgents } from "../plugins/targets.js";
 import { canPickAgentsInteractively } from "../utils/agent_picker.js";
 import { NEON_PLUGIN_NAME, PLUGIN_SKILLS, PLUGIN_SOURCE, neonPluginsRetryCommand, pluginsAddArgs, runPluginsCli } from "../plugins/run.js";
-import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { resolvePluginsPlan } from "../plugins/plan.js";
 import { confirmPluginsInstall } from "../plugins/wizard.js";
 //#region src/commands/plugins.ts

package/dist/commands/skills.js

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

package/dist/help.js

@@ -1,8 +1,75 @@
+import { globalOptionsTrailer, helpWidth, wrapHelpText } from "./utils/help_text.js";
 import { consumeBlockIfMatches, consumeNextMatching, drawPointer, splitColumns } from "./utils/ui.js";
 import chalk from "chalk";
 import cliui from "cliui";
 //#region src/help.ts
 const SPACE_WIDTH = 20;
+const DESCRIPTION_GUTTER = 4;
+const wrapDescription = (text) => wrapHelpText(text, Math.max(1, helpWidth() - SPACE_WIDTH - DESCRIPTION_GUTTER));
+const isGlobalOptionsHeader = (header) => /global options:/i.test(header);
+const isTopLevelUsage = (usage) => /^\S+ <command>/.test(usage);
+const renderOptionBlock = (optionsBlock) => {
+	const result = [];
+	const [header, ...body] = optionsBlock;
+	if (header === void 0) return result;
+	result.push(header);
+	body.forEach((line) => {
+		const [option, description] = splitColumns(line);
+		const ui = cliui({
+			width: helpWidth(),
+			wrap: false
+		});
+		if (option.startsWith("-")) {
+			ui.div({
+				text: chalk.green(option),
+				padding: [
+					0,
+					0,
+					0,
+					0
+				]
+			});
+			ui.div({
+				text: chalk.gray(drawPointer(SPACE_WIDTH)),
+				width: SPACE_WIDTH,
+				padding: [
+					0,
+					2,
+					0,
+					0
+				]
+			}, {
+				text: chalk.rgb(210, 210, 210)(wrapDescription(description ?? "")),
+				padding: [
+					0,
+					0,
+					0,
+					0
+				]
+			});
+		} else ui.div({
+			padding: [
+				0,
+				0,
+				0,
+				0
+			],
+			text: "",
+			width: SPACE_WIDTH
+		}, {
+			text: chalk.rgb(210, 210, 210)(wrapDescription(option)),
+			padding: [
+				0,
+				0,
+				0,
+				0
+			]
+		});
+		result.push(ui.toString());
+	});
+	result.push("");
+	return result;
+};
 const formatHelp = (help) => {
 	const lines = help.split("\n");
 	const result = [];
@@ -11,11 +78,16 @@ const formatHelp = (help) => {
 		result.push(chalk.bold(topLevelCommand.replace("[options]", chalk.reset.green("[options]"))));
 		result.push("");
 	}
-	const commandsBlock = consumeBlockIfMatches(lines, /^Commands:/);
-	if (commandsBlock.length > 0) {
+	const consumeCommands = () => {
+		const commandsBlock = consumeBlockIfMatches(lines, /^Commands:/);
+		if (commandsBlock.length === 0) return;
 		const header = commandsBlock.shift();
+		if (header === void 0) return;
 		result.push(header);
-		const ui = cliui({ width: 0 });
+		const ui = cliui({
+			width: helpWidth(),
+			wrap: false
+		});
 		commandsBlock.forEach((line) => {
 			if (/^\s{3,}/.exec(line)) {
 				ui.div({
@@ -28,7 +100,7 @@ const formatHelp = (help) => {
 						0
 					]
 				}, {
-					text: line.trim(),
+					text: wrapDescription(line.trim()),
 					padding: [
 						0,
 						0,
@@ -54,7 +126,7 @@ const formatHelp = (help) => {
 					0
 				]
 			}, {
-				text: description,
+				text: wrapDescription(description),
 				padding: [
 					0,
 					0,
@@ -65,12 +137,17 @@ const formatHelp = (help) => {
 		});
 		result.push(ui.toString());
 		result.push("");
-	}
-	const positionalsBlock = consumeBlockIfMatches(lines, /Positionals:/);
-	if (positionalsBlock.length > 0) {
+	};
+	const consumePositionals = () => {
+		const positionalsBlock = consumeBlockIfMatches(lines, /Positionals:/);
+		if (positionalsBlock.length === 0) return;
 		const header = positionalsBlock.shift();
+		if (header === void 0) return;
 		result.push(header);
-		const ui = cliui({ width: 0 });
+		const ui = cliui({
+			width: helpWidth(),
+			wrap: false
+		});
 		positionalsBlock.forEach((line) => {
 			const [positional, description] = splitColumns(line);
 			ui.div({
@@ -83,7 +160,7 @@ const formatHelp = (help) => {
 					0
 				]
 			}, {
-				text: description,
+				text: wrapDescription(description),
 				padding: [
 					0,
 					0,
@@ -94,73 +171,42 @@ const formatHelp = (help) => {
 		});
 		result.push(ui.toString());
 		result.push("");
-	}
+	};
+	consumeCommands();
+	consumePositionals();
 	const descriptionBlock = consumeBlockIfMatches(lines, /^(?!.*options:)/i);
 	if (descriptionBlock.length > 0) {
 		result.push(...descriptionBlock);
 		result.push("");
 	}
+	consumeCommands();
+	consumePositionals();
+	const optionBlocks = [];
 	while (true) {
 		const optionsBlock = consumeBlockIfMatches(lines, /.*options:/i);
 		if (optionsBlock.length === 0) break;
-		result.push(optionsBlock.shift());
-		optionsBlock.forEach((line) => {
-			const [option, description] = splitColumns(line);
-			const ui = cliui({ width: 0 });
-			if (option.startsWith("-")) {
-				ui.div({
-					text: chalk.green(option),
-					padding: [
-						0,
-						0,
-						0,
-						0
-					]
-				});
-				ui.div({
-					text: chalk.gray(drawPointer(SPACE_WIDTH)),
-					width: SPACE_WIDTH,
-					padding: [
-						0,
-						2,
-						0,
-						0
-					]
-				}, {
-					text: chalk.rgb(210, 210, 210)(description ?? ""),
-					padding: [
-						0,
-						0,
-						0,
-						0
-					]
-				});
-			} else ui.div({
-				padding: [
-					0,
-					0,
-					0,
-					0
-				],
-				text: "",
-				width: SPACE_WIDTH
-			}, {
-				text: chalk.rgb(210, 210, 210)(option),
-				padding: [
-					0,
-					0,
-					0,
-					0
-				]
-			});
-			result.push(ui.toString());
-		});
+		optionBlocks.push(optionsBlock);
+	}
+	for (const block of optionBlocks) {
+		const header = block[0];
+		if (header !== void 0 && !isGlobalOptionsHeader(header)) result.push(...renderOptionBlock(block));
+	}
+	const globalBlocks = optionBlocks.filter((block) => {
+		const header = block[0];
+		return header !== void 0 && isGlobalOptionsHeader(header);
+	});
+	if (topLevelCommand !== null && isTopLevelUsage(topLevelCommand)) for (const block of globalBlocks) result.push(...renderOptionBlock(block));
+	else if (globalBlocks.length > 0 && topLevelCommand !== null) {
+		result.push(globalOptionsTrailer(topLevelCommand));
 		result.push("");
 	}
 	const exampleBlock = consumeBlockIfMatches(lines, /Examples:/);
 	if (exampleBlock.length > 0) {
 		result.push(exampleBlock.shift());
-		const ui = cliui({ width: 0 });
+		const ui = cliui({
+			width: helpWidth(),
+			wrap: false
+		});
 		for (const line of exampleBlock) {
 			const [command, description] = splitColumns(line);
 			ui.div({
@@ -173,7 +219,7 @@ const formatHelp = (help) => {
 				]
 			});
 			ui.div({
-				text: chalk.reset(description),
+				text: chalk.reset(wrapDescription(description)),
 				padding: [
 					0,
 					0,
@@ -188,7 +234,16 @@ const formatHelp = (help) => {
 };
 const showHelp = async (argv) => {
 	const help = await argv.getHelp();
-	process.stderr.write(formatHelp(help).join("\n") + "\n");
+	const text = `${formatHelp(help).join("\n")}\n`;
+	await new Promise((resolve, reject) => {
+		process.stdout.write(text, (err) => {
+			if (err) {
+				reject(err);
+				return;
+			}
+			resolve();
+		});
+	});
 	process.exit(0);
 };
 //#endregion

package/dist/index.js

@@ -1,17 +1,17 @@
-import { t as storeFor } from "./_chunks/credential_io-D8AR-jvB.js";
 import { log } from "./log.js";
 import pkg_default from "./pkg.js";
 import { isNeonApiError, messageFromBody } from "./api.js";
-import { authFailureMessage, getAuthContext, locationFromContext } from "./auth_context.js";
+import { getAuthContext } from "./auth_context.js";
 import { r as defaultDir } from "./_chunks/paths-DMq0Lt7a.js";
 import { ensureConfigDir } from "./config.js";
 import { currentContextFile, enrichFromContext } from "./context.js";
 import { analyticsMiddleware, closeAnalytics, getAnalyticsEventProperties, initAnalyticsClientMiddleware, sendError, trackEvent } from "./analytics.js";
 import { NETWORK_ERROR_MESSAGE, isNetworkError, matchErrorCode } from "./errors.js";
 import { AuthRefreshError, defaultClientID } from "./auth.js";
+import { ensureAuth } from "./commands/auth.js";
+import { recoverFrom401 } from "./auth_recovery.js";
 import { getCliName } from "./utils/cli_name.js";
 import { showHelp } from "./help.js";
-import { ensureAuth, isAccessTokenUsable, refreshStoredCredentials } from "./commands/auth.js";
 import { rewriteUnknownAgentArg } from "./init/plan.js";
 import commands_default from "./commands/index.js";
 import { fillInArgs, resolveApiKeyFromEnv } from "./utils/middlewares.js";
@@ -100,6 +100,7 @@ builder = builder.scriptName(pkg_default.name).locale("en").usage("$0 <command>
 	},
 	"context-file": {
 		describe: "Context file",
+		group: "Global options:",
 		type: "string",
 		default: currentContextFile
 	},
@@ -124,63 +125,6 @@ builder = builder.scriptName(pkg_default.name).locale("en").usage("$0 <command>
 }).alias("help", "h").middleware(async (args) => {
 	if (args.help || args._.length === 1 && !NO_SUBCOMMANDS_VERBS.includes(args._[0])) await showHelp(builder);
 }).middleware(ensureAuth).middleware(enrichFromContext).middleware(analyticsMiddleware).command(commands_default).strictCommands().version(pkg_default.version).group("version", "Global options:").alias("version", "v").completion().scriptName(getCliName()).epilog("For more information, visit https://neon.com/docs/reference/neon-cli").wrap(null).fail(false);
-function supersededOnDisk(rejectedToken) {
-	if (rejectedToken === void 0) return false;
-	const context = getAuthContext();
-	if (context === null) return false;
-	const at = locationFromContext(context);
-	if (at === null) return false;
-	try {
-		const loaded = storeFor(context.configDir).read(at);
-		return loaded !== null && loaded.credentials.access_token !== rejectedToken && isAccessTokenUsable(loaded.credentials, Date.now());
-	} catch {
-		return false;
-	}
-}
-async function recoverFrom401(canRetry) {
-	const context = getAuthContext();
-	if (context === null || context.source !== "stored-credentials") {
-		log.error(authFailureMessage(context));
-		return false;
-	}
-	if (context.refreshed === true) {
-		log.error(authFailureMessage(context));
-		return false;
-	}
-	if (!canRetry) {
-		log.error(authFailureMessage(context));
-		return false;
-	}
-	if (supersededOnDisk(context.accessToken)) {
-		log.debug("The rejected token has already been replaced on disk; retrying with the current one");
-		return true;
-	}
-	const at = locationFromContext(context);
-	if (at === null || context.oauthHost === void 0 || context.clientId === void 0) {
-		log.error(authFailureMessage(context));
-		return false;
-	}
-	try {
-		if (await refreshStoredCredentials(at, {
-			apiHost: "",
-			oauthHost: context.oauthHost,
-			clientId: context.clientId,
-			configDir: context.configDir
-		})) {
-			log.debug("Refreshed the stored session after a 401; retrying");
-			return true;
-		}
-	} catch (err) {
-		if (err instanceof AuthRefreshError) {
-			log.error(err.message);
-			if (err.terminal) log.error(`Run \`neon auth --profile ${context.profile ?? "DEFAULT"}\` to sign in again.`);
-			return false;
-		}
-		log.debug("Refresh after 401 failed: %s", err instanceof Error ? err.message : "unknown error");
-	}
-	log.error(authFailureMessage(context));
-	return false;
-}
 async function handleError(msg, err, canRetry) {
 	if (process.argv.some((arg) => arg === "--help" || arg === "-h")) {
 		await showHelp(builder);

package/dist/init/link.js

@@ -0,0 +1,38 @@
+import { isNeonApiError } from "../api.js";
+import { r as defaultDir } from "../_chunks/paths-DMq0Lt7a.js";
+import "../config.js";
+import "../auth.js";
+import { ensureAuth } from "../commands/auth.js";
+import { recoverFrom401 } from "../auth_recovery.js";
+import { runLink } from "../commands/link.js";
+//#region src/init/link.ts
+const isUnauthorized = (error) => isNeonApiError(error) && error.status === 401;
+const authenticationFailed = () => /* @__PURE__ */ new Error("Authentication failed.");
+const runAuthenticatedLink = async (props) => {
+	const authenticated = {
+		...props,
+		_: ["link"],
+		configDir: props.configDir ?? defaultDir,
+		oauthHost: props.oauthHost ?? process.env.NEON_OAUTH_HOST ?? "https://oauth2.neon.tech",
+		clientId: props.clientId ?? "neonctl",
+		help: false
+	};
+	await ensureAuth(authenticated);
+	try {
+		await runLink(authenticated);
+		return;
+	} catch (error) {
+		if (!isUnauthorized(error)) throw error;
+		if (!await recoverFrom401(true)) throw authenticationFailed();
+	}
+	await ensureAuth(authenticated);
+	try {
+		await runLink(authenticated);
+	} catch (error) {
+		if (!isUnauthorized(error)) throw error;
+		await recoverFrom401(false);
+		throw authenticationFailed();
+	}
+};
+//#endregion
+export { runAuthenticatedLink };

package/dist/init/wizard.js

@@ -91,5 +91,17 @@ const pickInitConfigInteractively = async () => {
 	if (value === void 0) throw new Error("Aborted.");
 	return value === true;
 };
+const pickInitLinkInteractively = async () => {
+	requireInteractive();
+	const { value } = await prompts({
+		onState: restoreCursorOnAbort,
+		type: "confirm",
+		name: "value",
+		message: "Link this project to a Neon project now?",
+		initial: true
+	});
+	if (value === void 0) throw new Error("Aborted.");
+	return value === true;
+};
 //#endregion
-export { INIT_TEMPLATE_PICKER_INITIAL, initTemplatePickerChoices, pickAgentSetupInteractively, pickInitConfigInteractively, pickInitTemplateInteractively };
+export { INIT_TEMPLATE_PICKER_INITIAL, initTemplatePickerChoices, pickAgentSetupInteractively, pickInitConfigInteractively, pickInitLinkInteractively, pickInitTemplateInteractively };

package/dist/test_utils/fixtures.js

@@ -85,6 +85,7 @@ const test = test$1.extend({
 						expect(code).toBe(options?.code ?? 0);
 						if (options.snapshot !== false) expect(output).toMatchSnapshot();
 						if (options.stderr !== void 0) expect(strip(error).replace(/\s+/g, " ").trim()).toEqual(typeof options.stderr === "string" ? options.stderr.toString().replace(/\s+/g, " ") : options.stderr);
+						if (options.stdout !== void 0) expect(strip(output).replace(/\s+/g, " ").trim()).toEqual(typeof options.stdout === "string" ? options.stdout.toString().replace(/\s+/g, " ") : options.stdout);
 						resolve({
 							stdout: output,
 							stderr: error,

package/dist/utils/help_text.js

@@ -1,10 +1,13 @@
+import { parseColumns } from "../human_table.js";
 //#region src/utils/help_text.ts
 const HELP_WRAP = 78;
 const WRAP_INDENT = "    ";
 const helpWidth = () => {
-	const columns = process.stderr.columns ?? process.stdout.columns;
-	if (typeof columns !== "number" || !Number.isFinite(columns) || columns < 1) return 78;
-	return Math.max(24, columns - 1);
+	const fromStdout = process.stdout.columns;
+	if (typeof fromStdout === "number" && Number.isFinite(fromStdout) && fromStdout >= 1) return Math.max(24, fromStdout - 1);
+	const fromEnv = parseColumns(process.env.COLUMNS);
+	if (fromEnv !== void 0) return Math.max(24, fromEnv - 1);
+	return 78;
 };
 const helpCsv = (label, items, width = helpWidth()) => {
 	if (items.length === 0) return "";
@@ -24,6 +27,31 @@ const helpCsv = (label, items, width = helpWidth()) => {
 	lines.push(line);
 	return lines.join("\n");
 };
+const wrapHelpText = (text, width) => {
+	if (width < 1) return text;
+	const words = text.trim().split(/\s+/).filter((word) => word !== "");
+	if (words.length === 0) return text;
+	const lines = [];
+	let line = "";
+	for (const word of words) {
+		if (line === "") {
+			line = word;
+			continue;
+		}
+		if (line.length + 1 + word.length <= width) {
+			line = `${line} ${word}`;
+			continue;
+		}
+		lines.push(line);
+		line = word;
+	}
+	if (line !== "") lines.push(line);
+	return lines.join("\n");
+};
 const helpEpilogue = (...blocks) => ["", ...blocks.filter((block) => block !== "")].join("\n");
+const globalOptionsTrailer = (usage) => {
+	const cli = usage.trim().split(/\s+/)[0];
+	return `Global options: see ${cli === "" ? "neon" : cli} --help`;
+};
 //#endregion
-export { HELP_WRAP, helpCsv, helpEpilogue, helpWidth };
+export { HELP_WRAP, globalOptionsTrailer, helpCsv, helpEpilogue, helpWidth, wrapHelpText };

package/dist/writer.js

@@ -7,7 +7,8 @@ const writeYaml = (chunks) => {
 	return YAML.stringify(chunks.length === 1 ? chunks[0].data : Object.fromEntries(chunks.map(({ config, data }, idx) => [config.title ? toSnakeCase(config.title) : idx, data])), null, 2);
 };
 const writeJson = (chunks) => {
-	return JSON.stringify(chunks.length === 1 ? chunks[0].data : Object.fromEntries(chunks.map(({ config, data }, idx) => [config.title ? toSnakeCase(config.title) : idx, data])), null, 2);
+	const json = JSON.stringify(chunks.length === 1 ? chunks[0].data : Object.fromEntries(chunks.map(({ config, data }, idx) => [config.title ? toSnakeCase(config.title) : idx, data])), null, 2);
+	return json === void 0 ? json : `${json}\n`;
 };
 const writeTable = (chunks, out, width) => {
 	chunks.forEach(({ data, config }, i) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "4.17.0",
+  "version": "4.17.1",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -63,9 +63,9 @@
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
     "yoctocolors": "^2.1.2",
-    "@neon/config-runtime": "1.3.0",
+    "@neon/config": "1.4.0",
     "@neon/sdk": "4.1.0",
-    "@neon/config": "1.4.0"
+    "@neon/config-runtime": "1.3.0"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0",
@@ -98,8 +98,8 @@
     "typescript": "^5.9.0",
     "vitest": "^3.0.9",
     "@neon-internals/cli-core": "0.0.0",
-    "@neon-internals/env-core": "0.0.12",
     "@neon/e2e-harness": "0.0.0",
+    "@neon-internals/env-core": "0.0.12",
     "@neon/functions": "0.9.0"
   },
   "publishConfig": {