neon 7.0.1 → 7.0.3

package/README.md

@@ -47,10 +47,17 @@ brew upgrade neonctl
 To upgrade a binary version, download the latest binary file, as described above, and replace your old binary with the new one.
 
 Global npm, pnpm, Bun, and Homebrew installs check for updates once per day.
-When an update is available, terminal commands periodically print the matching
-upgrade command. Set `NO_UPDATE_NOTIFIER=1` to disable these checks. The notifier
+When an update is available, terminal commands print the matching upgrade command
+every three days. Set `NO_UPDATE_NOTIFIER=1` to disable these checks. The notifier
 does not run in CI, for machine-readable output, or from standalone binaries.
 
+On macOS and Linux, the same terminal commands warn once a day when more than one
+global `neon` install is on PATH, listing each one in PATH order. A project's
+`node_modules/.bin`, which `npx` and package scripts add, doesn't count. When one
+of them is Homebrew, the warning recommends `brew uninstall neonctl`, which
+leaves `neon` running the other install, such as npm. While duplicates remain, the update notice is held back;
+`NO_UPDATE_NOTIFIER=1` silences both.
+
 ## Connect
 
 Run the following command to authenticate a connection to Neon:

package/dist/commands/api.js

@@ -1,6 +1,6 @@
 import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
-import { describeOperation, getEndpoints, loadSpec } from "../utils/openapi.js";
 import { writer } from "../writer.js";
+import { describeOperation, getEndpoints, loadSpec } from "../utils/openapi.js";
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import YAML from "yaml";

package/dist/commands/bootstrap.js

@@ -4,13 +4,13 @@ import { log } from "../log.js";
 import { recordCommandSuccessExtras, recordScaffoldedTemplate } from "../analytics.js";
 import { getCliName } from "../utils/cli_name.js";
 import { helpCsv, helpEpilogue } from "../utils/help_text.js";
+import { coerceAgentFlag } from "../utils/agent_flag.js";
+import { assertNamedAgentTooling, chooseYesAgentTooling, initPluginAgents, initSkillsMcpAgents, postScaffoldActions, projectContextFile, resolveNamedAgents } from "../init/plan.js";
+import { 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 { 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, postScaffoldActions, projectContextFile, resolveNamedAgents } from "../init/plan.js";
 import { formatTemplateTitle } from "../init/template_title.js";
 import { pickAgentSetupInteractively, pickInitLinkInteractively } from "../init/wizard.js";
 import { runAgentTooling } from "../init/tooling.js";

package/dist/commands/branches.js

@@ -2,11 +2,11 @@ import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { log } from "../log.js";
 import { retryOnLock } from "../api.js";
 import { contextBranch, readContextFile } from "../context.js";
+import { branchCreateRequest } from "../parameters.gen.js";
 import { writer } from "../writer.js";
 import { EndpointType } from "../utils/api_enums.js";
 import { looksLikeBranchId, looksLikeLSN, looksLikeTimestamp } from "../utils/formats.js";
 import { branchIdFromProps, branchIdResolve, fillSingleProject } from "../utils/enrichers.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";

package/dist/commands/bucket.js

@@ -1,9 +1,9 @@
 import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { log } from "../log.js";
 import { isNeonApiError, retryOnLock } from "../api.js";
+import { createProjectBranchBucket, deleteProjectBranchBucket, deleteProjectBranchBucketObject, deleteProjectBranchBucketObjectsByPrefix, getProjectBranchBucketObject, listProjectBranchBucketObjects, listProjectBranchBuckets, presignUpload } from "../storage_api.js";
 import { writer } from "../writer.js";
 import { branchIdFromProps, fillSingleProject } from "../utils/enrichers.js";
-import { createProjectBranchBucket, deleteProjectBranchBucket, deleteProjectBranchBucketObject, deleteProjectBranchBucketObjectsByPrefix, getProjectBranchBucketObject, listProjectBranchBucketObjects, listProjectBranchBuckets, presignUpload } from "../storage_api.js";
 import { createReadStream, createWriteStream } from "node:fs";
 import { basename } from "node:path";
 import { stat, unlink } from "node:fs/promises";

package/dist/commands/config.js

@@ -10,12 +10,12 @@ import { editNeonConfig } from "../config_edit.js";
 import { toNeonConfigView } from "../config_format.js";
 import { declaredNeonServices } from "../config_services.js";
 import { loadEnvFileIntoProcess } from "../env_file.js";
+import { formatInstallCommand, installArgs, resolvePackageManager, runCommand } from "../utils/package_manager.js";
 import { writer } from "../writer.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, renderCustomDomainFollowup } from "../utils/config_diff.js";
-import { formatInstallCommand, installArgs, resolvePackageManager, runCommand } from "../utils/package_manager.js";
 import { bundleEntry } from "../utils/esbuild.js";
 import { readGitContext } from "../utils/git.js";
 import { resolveHookEnv, runDeployAfterHook, runDeployBeforeHook } from "../utils/hooks.js";

package/dist/commands/dev.js

@@ -13,8 +13,8 @@ import { existsSync, mkdirSync, rmSync, statSync, writeFileSync } from "node:fs"
 import { basename, dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import chalk from "chalk";
-import { bundleAsIs, describeNativeFinding, findUndeclaredNativePackages, resolveEsbuildEntry } from "@neon/config-runtime";
 import { spawn, spawnSync } from "node:child_process";
+import { bundleAsIs, describeNativeFinding, findUndeclaredNativePackages, resolveEsbuildEntry } from "@neon/config-runtime";
 import { once } from "node:events";
 import { createServer } from "node:net";
 //#region src/commands/dev.ts

package/dist/commands/ip_allow.js

@@ -1,9 +1,9 @@
 import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { log } from "../log.js";
 import { getCliName } from "../utils/cli_name.js";
+import { projectUpdateRequest } from "../parameters.gen.js";
 import { writer } from "../writer.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/manifest.js

@@ -0,0 +1,316 @@
+import { getCliName } from "../utils/cli_name.js";
+import { Parser } from "yargs/helpers";
+//#region src/commands/manifest.ts
+/**
+* Every top-level command, in help order, with the metadata yargs needs to list and route it.
+* A command's module (and everything it imports) loads only when yargs selects that command,
+* so `neon --help` and `neon projects list` don't pay for `init`, `dev`, or `psql`.
+*
+* `command`, `aliases`, and `describe` must equal the module's own exports; `manifest.test.ts`
+* enforces that. `load` uses a literal specifier so bundlers can see and package each chunk.
+*/
+const commandManifest = [
+	{
+		command: "auth",
+		aliases: ["login"],
+		describe: "Sign in with a browser. See --help for API keys and profiles",
+		load: () => import("./auth.js")
+	},
+	{
+		command: "profile",
+		aliases: ["profiles"],
+		describe: "Manage named sets of Neon credentials",
+		load: () => import("./profile.js")
+	},
+	{
+		command: "api-keys",
+		aliases: ["api-key"],
+		describe: "Manage API keys",
+		load: () => import("./api_keys.js")
+	},
+	{
+		command: "api [path]",
+		describe: "Call any Neon API route directly (authenticated passthrough)",
+		load: () => import("./api.js")
+	},
+	{
+		command: "me",
+		describe: "Show current user",
+		load: () => import("./user.js")
+	},
+	{
+		command: "orgs",
+		aliases: ["org"],
+		describe: "Manage organizations",
+		load: () => import("./orgs.js")
+	},
+	{
+		command: "projects",
+		aliases: ["project"],
+		describe: "Manage projects",
+		load: () => import("./projects.js")
+	},
+	{
+		command: "ip-allow",
+		describe: "Manage IP Allow",
+		load: () => import("./ip_allow.js")
+	},
+	{
+		command: "vpc",
+		describe: "Manage VPC endpoints and project VPC restrictions",
+		load: () => import("./vpc_endpoints.js")
+	},
+	{
+		command: "neon-auth",
+		describe: "Manage Neon Auth",
+		load: () => import("./neon_auth.js")
+	},
+	{
+		command: "branches",
+		aliases: ["branch"],
+		describe: "Manage branches",
+		load: () => import("./branches.js")
+	},
+	{
+		command: "databases",
+		aliases: ["database", "db"],
+		describe: "Manage databases",
+		load: () => import("./databases.js")
+	},
+	{
+		command: "roles",
+		aliases: ["role"],
+		describe: "Manage roles",
+		load: () => import("./roles.js")
+	},
+	{
+		command: "operations",
+		aliases: ["operation"],
+		describe: "Manage operations",
+		load: () => import("./operations.js")
+	},
+	{
+		command: "logs",
+		describe: "Query branch logs",
+		load: () => import("./logs.js")
+	},
+	{
+		command: "snapshots",
+		aliases: ["snapshot"],
+		describe: "Manage snapshots",
+		load: () => import("./snapshots.js")
+	},
+	{
+		command: "inspect",
+		aliases: ["inspection"],
+		describe: "Inspect a branch's Postgres health and configuration",
+		load: () => import("./inspect.js")
+	},
+	{
+		command: "connection-string [branch]",
+		aliases: ["cs"],
+		describe: "Get connection string",
+		load: () => import("./connection_string.js")
+	},
+	{
+		command: "psql [branch]",
+		describe: "Connect to a database via psql",
+		load: () => import("./psql.js")
+	},
+	{
+		command: "set-context",
+		describe: `Deprecated: use \`${getCliName()} link\`. Set the .neon context (raw write).`,
+		load: () => import("./set_context.js")
+	},
+	{
+		command: "checkout [id|name]",
+		describe: "Pin a branch in the local context (.neon) so subsequent commands target it",
+		load: () => import("./checkout.js")
+	},
+	{
+		command: "git",
+		aliases: [],
+		describe: "Sync the checked-out Neon branch to your git branch (Preview)",
+		load: () => import("./git.js")
+	},
+	{
+		command: "link",
+		describe: "Link the current directory to a Neon project",
+		load: () => import("./link.js")
+	},
+	{
+		command: "open",
+		describe: "Open the linked project in the Neon Console",
+		load: () => import("./open.js")
+	},
+	{
+		command: "claim",
+		aliases: ["claimable"],
+		describe: "Create and claim temporary Neon projects",
+		load: () => import("./claim.js")
+	},
+	{
+		command: "init",
+		describe: "Set up coding agents and this directory for Neon. -y is Recommended. -y with Custom flags applies those answers without prompts.",
+		load: () => import("./init.js")
+	},
+	{
+		command: "mcp",
+		describe: "Install the Neon MCP server into coding agents",
+		load: () => import("./mcp.js")
+	},
+	{
+		command: "plugins",
+		aliases: ["plugin"],
+		describe: "Install the Neon plugin into coding agents",
+		load: () => import("./plugins.js")
+	},
+	{
+		command: "skills",
+		aliases: ["skill"],
+		describe: "Install Neon agent skills into coding agents",
+		load: () => import("./skills.js")
+	},
+	{
+		command: "ask",
+		describe: "Ask a question about Neon",
+		load: () => import("./ask.js")
+	},
+	{
+		command: "data-api",
+		describe: "Manage the Neon Data API for a database",
+		load: () => import("./data_api.js")
+	},
+	{
+		command: "functions",
+		aliases: ["function"],
+		describe: "Manage Neon Functions",
+		load: () => import("./functions.js")
+	},
+	{
+		command: "triggers",
+		aliases: ["trigger"],
+		describe: "Manage function triggers",
+		load: () => import("./triggers.js")
+	},
+	{
+		command: "credentials",
+		aliases: ["credential"],
+		describe: "Manage branch credentials",
+		load: () => import("./credentials.js")
+	},
+	{
+		command: "dev",
+		describe: "Run Neon Functions locally with a dev server",
+		load: () => import("./dev.js")
+	},
+	{
+		command: "diff [compare-branch]",
+		describe: "Show a git-style schema diff between the current branch and another branch",
+		load: () => import("./diff.js")
+	},
+	{
+		command: "config",
+		describe: "Manage a branch with a neon.ts policy",
+		load: () => import("./config.js")
+	},
+	{
+		command: "status",
+		describe: "Show the branch's live Neon state (alias of `config status`)",
+		load: () => import("./status.js")
+	},
+	{
+		command: "deploy",
+		describe: "Apply a neon.ts policy to a branch (alias for `config apply`)",
+		load: () => import("./deploy.js")
+	},
+	{
+		command: "env",
+		describe: "Manage a branch's Neon env variables locally",
+		load: () => import("./env.js")
+	},
+	{
+		command: "buckets",
+		aliases: ["bucket"],
+		describe: "Manage branch object-storage buckets and their objects",
+		load: () => import("./bucket.js")
+	},
+	{
+		command: "bootstrap [directory]",
+		describe: "Scaffold a new project from a Neon starter template, then install agent tooling and link a Neon project",
+		load: () => import("./bootstrap.js")
+	}
+];
+const COMPLETION_COMMAND = "completion";
+const COMPLETION_FLAG = "--get-yargs-completions";
+const verbOf = (entry) => entry.command.split(" ")[0];
+const entryByName = new Map(commandManifest.flatMap((entry) => [verbOf(entry), ...entry.aliases ?? []].map((name) => [name, entry])));
+/**
+* The command yargs 17 will run for these top-level positionals: it walks them in order,
+* skips `completion`, runs the first one that names a command, and stops at the first one
+* that doesn't (`kRunYargsParserAndExecuteCommands` in yargs-factory.js).
+*/
+const selectCommand = (positionals) => {
+	const first = positionals.find((p) => String(p) !== COMPLETION_COMMAND);
+	return first === void 0 ? void 0 : entryByName.get(String(first));
+};
+/**
+* The command whose builder yargs 17 runs to complete `--get-yargs-completions <words>`: the
+* first word that is a command's canonical name, at any position; aliases don't count there
+* (`defaultCompletion` in completion.js looks words up in the handler map, keyed by name).
+*/
+const selectCompletionCommand = (words) => words.map((word) => commandManifest.find((entry) => verbOf(entry) === word)).find((entry) => entry);
+function assertHasGetOptions(argv) {
+	if (!("getOptions" in argv) || typeof argv.getOptions !== "function") throw new Error("yargs no longer exposes getOptions(); update preloadCommand for the installed yargs");
+}
+const loaded = /* @__PURE__ */ new Map();
+/**
+* Import the module of the command yargs is about to run, before it runs, so its builder can
+* stay synchronous. Parses argv with yargs' own parser and the top-level options yargs will
+* use, so an option value that happens to be a command name (`--api-key projects`) can't
+* change the answer.
+*/
+const preloadCommand = async (cli, args) => {
+	const doubleDash = args.indexOf("--");
+	const completionAt = (doubleDash === -1 ? args : args.slice(0, doubleDash)).indexOf(COMPLETION_FLAG);
+	let entry;
+	if (completionAt >= 0) entry = selectCompletionCommand(args.slice(completionAt + 1));
+	else {
+		assertHasGetOptions(cli);
+		const options = cli.getOptions();
+		const { argv } = Parser.detailed([...args], {
+			...options,
+			configuration: {
+				...options?.configuration,
+				"populate--": true,
+				"parse-positional-numbers": false
+			}
+		});
+		entry = selectCommand(argv._);
+	}
+	if (entry && !loaded.has(entry)) loaded.set(entry, await entry.load());
+	return entry;
+};
+/**
+* The manifest as yargs command modules. The builder is synchronous when `preloadCommand`
+* already imported the module, which is every invocation it predicts correctly. A mispredicted
+* command still runs, because yargs 17 awaits a builder's promise when it runs a command; shell
+* completion does not await it, so a mispredicted completion lists no subcommands.
+*/
+const lazyCommands = commandManifest.map((entry) => ({
+	command: entry.command,
+	aliases: entry.aliases,
+	describe: entry.describe,
+	builder: (argv) => {
+		const mod = loaded.get(entry);
+		return mod ? mod.builder(argv) : entry.load().then((m) => {
+			loaded.set(entry, m);
+			return m.builder(argv);
+		});
+	},
+	handler: async (args) => {
+		return (loaded.get(entry) ?? await entry.load()).handler?.(args);
+	}
+}));
+//#endregion
+export { commandManifest, lazyCommands, preloadCommand, selectCommand, selectCompletionCommand };

package/dist/commands/mcp.js

@@ -4,11 +4,11 @@ import { readContextFile } from "../context.js";
 import { recordCommandSuccessExtras } from "../analytics.js";
 import { getCliName } from "../utils/cli_name.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 { mcpInstallableAgents, resolveInstallTargets } from "../mcp/targets.js";
 import { writer } from "../writer.js";
 import { noPassthrough, single } from "../utils/flags.js";
 import { AGENT_MCP_SKIP_MESSAGE } from "../init/copy.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 { mintMcpApiKey, mintedKeyRevokeCommand, withdrawMintedKey } from "../mcp/mint.js";
 import { canPickAgentsInteractively, skippableAgentPicker } from "../utils/agent_picker.js";
 import { resolveMcpPlan } from "../mcp/plan.js";

package/dist/commands/plugins.js

@@ -2,13 +2,13 @@ import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { log } from "../log.js";
 import { recordCommandSuccessExtras } from "../analytics.js";
 import { helpCsv, helpEpilogue } from "../utils/help_text.js";
-import { writer } from "../writer.js";
-import { noPassthrough } from "../utils/flags.js";
-import { AGENT_PLUGIN_SKIP_MESSAGE } from "../init/copy.js";
 import { getAgentDisplayName } from "../mcp/agents.js";
 import { NEON_MCP_URL } from "../mcp/install.js";
 import "../init/agents.js";
 import { pluginsInstallableAgents } from "../plugins/targets.js";
+import { writer } from "../writer.js";
+import { noPassthrough } from "../utils/flags.js";
+import { AGENT_PLUGIN_SKIP_MESSAGE } from "../init/copy.js";
 import { canPickAgentsInteractively, skippableAgentPicker } from "../utils/agent_picker.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/profile.js

@@ -11,10 +11,10 @@ import { auth, revokeToken } from "../auth.js";
 import { t as credentialInputs } from "../_chunks/auth_selection-pitMFzDe.js";
 import { readOutgoingCredential, retirePreviousCredential, revokeTokenSet, withdrawKey } from "../retire_credential.js";
 import { authFlow, usableCredential } from "./auth.js";
+import { identityFromAuthDetails, isApiKeyMethod, mintedKeyName, notAnApiKeyMessage } from "../profile_keys.js";
 import { writer } from "../writer.js";
 import { noPassthrough, single } from "../utils/flags.js";
 import { orgIdForProject } from "./api_keys.js";
-import { identityFromAuthDetails, isApiKeyMethod, mintedKeyName, notAnApiKeyMessage } from "../profile_keys.js";
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import { isAbsolute, relative } from "node:path";
 import prompts from "prompts";

package/dist/commands/projects.js

@@ -4,8 +4,8 @@ import { log } from "../log.js";
 import { isNeonApiError, messageFromBody } from "../api.js";
 import { updateContextFile } from "../context.js";
 import { getCliName } from "../utils/cli_name.js";
-import { writer } from "../writer.js";
 import { projectCreateRequest, projectUpdateRequest } from "../parameters.gen.js";
+import { writer } from "../writer.js";
 import { getComputeUnits } from "../utils/compute_units.js";
 import { psql } from "../utils/psql.js";
 import prompts from "prompts";

package/dist/commands/skills.js

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

package/dist/index.js

@@ -12,8 +12,8 @@ import { getCliName } from "./utils/cli_name.js";
 import { ensureAuth } from "./commands/auth.js";
 import { recoverFrom401 } from "./auth_recovery.js";
 import { UsageError, failOnUsageError, isBareParentCommand, showHelp, showUsageErrorHelp } from "./help.js";
+import { lazyCommands, preloadCommand } from "./commands/manifest.js";
 import { rewriteUnknownAgentArg } from "./init/plan.js";
-import commands_default from "./commands/index.js";
 import { recoverFromSSO } from "./sso_recovery.js";
 import { notifyIfUpdateAvailable } from "./update_notifier.js";
 import { fillInArgs, resolveApiKeyFromEnv } from "./utils/middlewares.js";
@@ -128,7 +128,7 @@ builder = builder.scriptName(pkg_default.name).locale("en").usage("$0 <command>
 	if (args.help) await showHelp(builder);
 }, true).middleware(async (args) => {
 	if (args._.length === 1 && !NO_SUBCOMMANDS_VERBS.includes(args._[0]) || args._.length > 1 && isBareParentCommand(builder, args._)) 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(failOnUsageError);
+}).middleware(ensureAuth).middleware(enrichFromContext).middleware(analyticsMiddleware).command(lazyCommands).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(failOnUsageError);
 async function handleError(msg, err, canRetry) {
 	if (process.argv.some((arg) => arg === "--help" || arg === "-h")) {
 		await showHelp(builder);
@@ -194,6 +194,7 @@ async function handleError(msg, err, canRetry) {
 (async () => {
 	let attempts = 0;
 	const MAX_ATTEMPTS = 2;
+	await preloadCommand(builder, hideBin(process.argv));
 	while (attempts < MAX_ATTEMPTS) try {
 		const args = await builder.argv;
 		trackEvent("cli_command_success", commandSuccessProperties(args));

package/dist/init/mode.js

@@ -1,5 +1,5 @@
-import { NON_TTY_AGENT_SETUP, NO_AGENT_SETUP_CONFLICT } from "./copy.js";
 import { INIT_NEEDS_YES_OR_TERMINAL } from "./plan.js";
+import { NON_TTY_AGENT_SETUP, NO_AGENT_SETUP_CONFLICT } from "./copy.js";
 //#region src/init/mode.ts
 const hasInitMcpFlags = (input) => input.mcpConfigLocation !== void 0 || input.mcpAuth !== void 0 || input.mcpProjectScoped === true;
 const hasSkillsFlag = (skills) => skills !== void 0 && skills.length > 0;

package/dist/init/run.js

@@ -8,16 +8,16 @@ import { readLinkedClaimableCredentials } from "../claimable/state.js";
 import { getCliName } from "../utils/cli_name.js";
 import { deprecatedServiceMessage, parseServices, servicesFlagValue } from "../neon_services.js";
 import { CONFIG_INIT_NONE_MEANS, CONFIG_INIT_SERVICES, CONFIG_INIT_UNAVAILABLE } from "../config_template.js";
-import { CANCELLED_BODY, CLAIMABLE_ACCOUNT_FLAGS, CLAIMABLE_ALREADY_LINKED, CLAIMABLE_MCP_API_KEY, CLAIMABLE_NO_LINK, MCP_SCOPED_NEEDS_PROJECT, NON_TTY_LINK_NEEDS_AUTH, NO_AGENTS_FALLBACK_STATUS, PROGRESS, YES_LINK_NEEDS_AUTH, claimableNext, claimableThenServicesNext, envPullFailedNext, existingConfigNext, extraServicesNext, installFailedNext, mcpConfigLocationSkipped, mcpConfigLocationUnavailable, namedAgentsUnavailable, skippedLinkNext, unattendedUnauthedNext } from "./copy.js";
-import { agentsRowValue, configRowValue, formatInitDone, headingForKind, printInitBanner, printInitDone, printInitProgress, projectRowValue, shouldPrintInitBanner } from "./chrome.js";
-import { inferPackageManager, resolvePackageManager } from "../utils/package_manager.js";
-import { ConfigInstallFailed, hasNeonConfigFile, initCmd, neonConfigFilename } from "../commands/config.js";
-import { runAuthenticatedLink } from "./link.js";
 import { getAgentDisplayName } from "../mcp/agents.js";
 import { mcpInstallableAgents } from "../mcp/targets.js";
 import { missingPluginsCommands, pluginsInstallableAgents } from "../plugins/targets.js";
 import { skillsInstallableAgents } from "../skills/targets.js";
 import { FALLBACK_SKILLS_AGENTS, assertNamedAgentTooling, funnelAgentSetup, planInitToolingSteps, recommendedTooling, resolveNamedAgents, splitInitTooling } from "./plan.js";
+import { inferPackageManager, resolvePackageManager } from "../utils/package_manager.js";
+import { CANCELLED_BODY, CLAIMABLE_ACCOUNT_FLAGS, CLAIMABLE_ALREADY_LINKED, CLAIMABLE_MCP_API_KEY, CLAIMABLE_NO_LINK, MCP_SCOPED_NEEDS_PROJECT, NON_TTY_LINK_NEEDS_AUTH, NO_AGENTS_FALLBACK_STATUS, PROGRESS, YES_LINK_NEEDS_AUTH, claimableNext, claimableThenServicesNext, envPullFailedNext, existingConfigNext, extraServicesNext, installFailedNext, mcpConfigLocationSkipped, mcpConfigLocationUnavailable, namedAgentsUnavailable, skippedLinkNext, unattendedUnauthedNext } from "./copy.js";
+import { agentsRowValue, configRowValue, formatInitDone, headingForKind, printInitBanner, printInitDone, printInitProgress, projectRowValue, shouldPrintInitBanner } from "./chrome.js";
+import { ConfigInstallFailed, hasNeonConfigFile, initCmd, neonConfigFilename } from "../commands/config.js";
+import { runAuthenticatedLink } from "./link.js";
 import { pullInitEnv } from "./auth.js";
 import { InitCancelled, raceSigint, restoreCursor } from "./cancelled.js";
 import { pickAgentSetupInteractively, pickInitAgentsInteractively, pickInitConfigInteractively, pickInitMcpAuthInteractively, pickInitMcpConfigLocationInteractively, pickInitModeInteractively, pickInitPackageManagerInteractively, pickInitProjectSetupInteractively, pickInitServicesInteractively, pickInitSkillsInteractively } from "./wizard.js";

package/dist/init/tooling.js

@@ -1,7 +1,7 @@
 import { log } from "../log.js";
 import { getCliName } from "../utils/cli_name.js";
-import { PROGRESS } from "./copy.js";
 import { assertNamedAgentTooling, chooseYesAgentTooling, collectYesAgents, initYesSupportedAgents, noDetectedAgentsMessage, planAgentSteps, planToolingSteps, planYesAgentSteps, resolveInitAgentSetup } from "./plan.js";
+import { PROGRESS } from "./copy.js";
 import { detectAgent } from "./detect_host.js";
 import { AgentSelectionSkipped, canPickAgentsInteractively } from "../utils/agent_picker.js";
 import { mcpInstallError, reportMcpInstall } from "../commands/mcp.js";

package/dist/init/wizard.js

@@ -1,9 +1,9 @@
 import { CONFIG_INIT_SERVICES } from "../config_template.js";
-import { AGENT_DETECTED_DESCRIPTION, AGENT_MCP_PICKER_MESSAGE, AGENT_MCP_SKIP_MESSAGE, AGENT_OTHER_DESCRIPTION, AGENT_PICKER_MESSAGE, AGENT_PLUGIN_SKIP_MESSAGE, AGENT_SETUP_MESSAGE, AGENT_SETUP_PLUGIN_DESCRIPTION, AGENT_SETUP_PLUGIN_TITLE, AGENT_SETUP_SKILLS_DESCRIPTION, AGENT_SETUP_SKILLS_TITLE, AGENT_SETUP_SKIP_DESCRIPTION, AGENT_SETUP_SKIP_TITLE, AGENT_SKILLS_PICKER_MESSAGE, AGENT_SKILLS_SKIP_MESSAGE, CONFIG_CONFIRM_HINT, CONFIG_CONFIRM_MESSAGE, MCP_AUTH_API_KEY_DESCRIPTION, MCP_AUTH_API_KEY_TITLE, MCP_AUTH_MESSAGE, MCP_AUTH_OAUTH_DESCRIPTION, MCP_AUTH_OAUTH_TITLE, MCP_SCOPE_GLOBAL_DESCRIPTION, MCP_SCOPE_GLOBAL_TITLE, MCP_SCOPE_MESSAGE, MCP_SCOPE_PROJECT_DESCRIPTION, MCP_SCOPE_PROJECT_TITLE, MODE_CUSTOM_DESCRIPTION, MODE_CUSTOM_TITLE, MODE_MESSAGE, MODE_RECOMMENDED_DESCRIPTION, MODE_RECOMMENDED_TITLE, PACKAGE_MANAGER_MESSAGE, PROJECT_SETUP_CLAIMABLE_DESCRIPTION, PROJECT_SETUP_CLAIMABLE_TITLE, PROJECT_SETUP_LINK_DESCRIPTION, PROJECT_SETUP_LINK_TITLE, PROJECT_SETUP_MESSAGE, SERVICES_HINT, SERVICES_MESSAGE, SKILLS_PICKER_MESSAGE, agentMissingCommandDescription } from "./copy.js";
-import { installedPackageManagers } from "../utils/package_manager.js";
-import { POSTGRES_SERVICE_CHOICE, keepPostgresSelected } from "../utils/service_picker.js";
 import { getAgentDisplayName, listMcpAgentIds } from "../mcp/agents.js";
 import { INIT_NEEDS_YES_OR_TERMINAL } from "./plan.js";
+import { installedPackageManagers } from "../utils/package_manager.js";
+import { AGENT_DETECTED_DESCRIPTION, AGENT_MCP_PICKER_MESSAGE, AGENT_MCP_SKIP_MESSAGE, AGENT_OTHER_DESCRIPTION, AGENT_PICKER_MESSAGE, AGENT_PLUGIN_SKIP_MESSAGE, AGENT_SETUP_MESSAGE, AGENT_SETUP_PLUGIN_DESCRIPTION, AGENT_SETUP_PLUGIN_TITLE, AGENT_SETUP_SKILLS_DESCRIPTION, AGENT_SETUP_SKILLS_TITLE, AGENT_SETUP_SKIP_DESCRIPTION, AGENT_SETUP_SKIP_TITLE, AGENT_SKILLS_PICKER_MESSAGE, AGENT_SKILLS_SKIP_MESSAGE, CONFIG_CONFIRM_HINT, CONFIG_CONFIRM_MESSAGE, MCP_AUTH_API_KEY_DESCRIPTION, MCP_AUTH_API_KEY_TITLE, MCP_AUTH_MESSAGE, MCP_AUTH_OAUTH_DESCRIPTION, MCP_AUTH_OAUTH_TITLE, MCP_SCOPE_GLOBAL_DESCRIPTION, MCP_SCOPE_GLOBAL_TITLE, MCP_SCOPE_MESSAGE, MCP_SCOPE_PROJECT_DESCRIPTION, MCP_SCOPE_PROJECT_TITLE, MODE_CUSTOM_DESCRIPTION, MODE_CUSTOM_TITLE, MODE_MESSAGE, MODE_RECOMMENDED_DESCRIPTION, MODE_RECOMMENDED_TITLE, PACKAGE_MANAGER_MESSAGE, PROJECT_SETUP_CLAIMABLE_DESCRIPTION, PROJECT_SETUP_CLAIMABLE_TITLE, PROJECT_SETUP_LINK_DESCRIPTION, PROJECT_SETUP_LINK_TITLE, PROJECT_SETUP_MESSAGE, SERVICES_HINT, SERVICES_MESSAGE, SKILLS_PICKER_MESSAGE, agentMissingCommandDescription } from "./copy.js";
+import { POSTGRES_SERVICE_CHOICE, keepPostgresSelected } from "../utils/service_picker.js";
 import { canPickAgentsInteractively, pickAgentsInteractively } from "../utils/agent_picker.js";
 import { NEON_SKILL_CATALOG, listSkillIds } from "../skills/catalog.js";
 import { InitCancelled, restoreCursorVisibilityOnAbort } from "./cancelled.js";

package/dist/mcp/install.js

@@ -1,7 +1,7 @@
 import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
-import { execFileSync } from "node:child_process";
 import { agents, upsertServer } from "add-mcp";
+import { execFileSync } from "node:child_process";
 //#region src/mcp/install.ts
 const NEON_MCP_URL = "https://mcp.neon.tech/mcp";
 const NEON_MCP_NAME = "Neon";

package/dist/mcp/mint.js

@@ -1,8 +1,8 @@
 import { log } from "../log.js";
 import { isNeonApiError } from "../api.js";
 import { getCliName } from "../utils/cli_name.js";
-import { orgIdForProject } from "../commands/api_keys.js";
 import { mintedKeyName } from "../profile_keys.js";
+import { orgIdForProject } from "../commands/api_keys.js";
 //#region src/mcp/mint.ts
 const cannotMintMessage = "This CLI credential cannot mint API keys. Organization and project-scoped keys cannot create other keys. Sign in with `neon auth` or pass a personal API key.";
 function mintedKeyRevokeCommand(key) {

package/dist/notices.js

@@ -0,0 +1,47 @@
+import { log } from "./log.js";
+import { writeJsonFile } from "./utils/json_file.js";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+//#region src/notices.ts
+/**
+* When each terminal notice was last shown, so a notice repeats on its own interval rather
+* than on every command. Kept apart from the update cache: that cache is tied to one install
+* source and rewritten by a background worker, while a notice can come from any copy.
+*
+* Throttling is best effort. Two commands started together can both show a due notice.
+*/
+const NOTICES_FILE = "notices.json";
+/**
+* Keeps ids this version doesn't know, so an older and a newer CLI sharing one config
+* directory don't erase each other's timestamps.
+*/
+const parseNoticeLog = (raw) => {
+	let value;
+	try {
+		value = JSON.parse(raw);
+	} catch {
+		return {};
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return {};
+	return Object.fromEntries(Object.entries(value).filter((entry) => typeof entry[1] === "number" && Number.isFinite(entry[1])));
+};
+const isNoticeDue = (shownAt, now, intervalMs) => shownAt === void 0 || now - shownAt >= intervalMs;
+const readNoticeLog = (path) => {
+	try {
+		return parseNoticeLog(readFileSync(path, "utf8"));
+	} catch {
+		return {};
+	}
+};
+const showNotice = ({ configDir, id, intervalMs, message, now = Date.now() }) => {
+	const path = join(configDir, NOTICES_FILE);
+	const shown = readNoticeLog(path);
+	if (!isNoticeDue(shown[id], now, intervalMs)) return;
+	log.warning("%s", message);
+	writeJsonFile(path, {
+		...shown,
+		[id]: now
+	}, "CLI notice log");
+};
+//#endregion
+export { isNoticeDue, parseNoticeLog, showNotice };

package/dist/plugins/targets.js

@@ -1,8 +1,8 @@
 import { detectInstalledAgents, listMcpAgentIds, tryResolveAddMcpAgentId, uniqueAgentIds } from "../mcp/agents.js";
 import "../init/agents.js";
 import { delimiter, dirname, join, resolve } from "node:path";
-import which from "which";
 import { detectProjectAgents } from "add-mcp";
+import which from "which";
 //#region src/plugins/targets.ts
 const CLAUDE_CODE = { target: "claude-code" };
 const PLUGINS_TARGET_BY_TYPE = {

package/dist/test_utils/fixtures.js

@@ -26,8 +26,15 @@ const reserveClosedPort = () => new Promise((resolve, reject) => {
 const test = test$1.extend({
 	runMockServer: async ({}, use) => {
 		let startedServer;
-		await use(async (mockDir) => {
+		await use(async (mockDir, onRequest) => {
 			const app = express();
+			if (onRequest) app.use((req, _res, next) => {
+				onRequest({
+					method: req.method,
+					path: req.path
+				});
+				next();
+			});
 			app.use(express.json());
 			app.use("/", emocks(join(process.cwd(), "mocks", mockDir), { "404": (_req, res) => res.status(404).send({ message: "Not Found" }) }));
 			const server = await new Promise((resolve) => {

package/dist/update_notifier.js

@@ -1,25 +1,29 @@
 import { isCi } from "./env.js";
 import { log } from "./log.js";
-import { recommendedCliUpgradeCommand } from "./utils/package_manager.js";
-import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { writeJsonFile } from "./utils/json_file.js";
+import { showNotice } from "./notices.js";
+import { detectCliInstallMethod, recommendedCliUpgradeCommand } from "./utils/package_manager.js";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
+import which from "which";
 import semver from "semver";
 //#region src/update_notifier.ts
-const CHECK_INTERVAL_MS = 864e5;
-const NOTIFY_INTERVAL_MS = 3 * CHECK_INTERVAL_MS;
+const DAY_MS = 864e5;
+const CHECK_INTERVAL_MS = DAY_MS;
+const UPDATE_NOTICE_INTERVAL_MS = 3 * DAY_MS;
+const DUPLICATE_NOTICE_INTERVAL_MS = DAY_MS;
 const CACHE_FILE = "update-check.json";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const parseUpdateCheckCache = (raw) => {
 	try {
 		const value = JSON.parse(raw);
-		if (!isRecord(value) || typeof value.checkedAt !== "number" || !Number.isFinite(value.checkedAt) || value.source !== "homebrew" && value.source !== "npm" || value.latestVersion !== void 0 && typeof value.latestVersion !== "string" || value.notifiedAt !== void 0 && (typeof value.notifiedAt !== "number" || !Number.isFinite(value.notifiedAt))) return;
+		if (!isRecord(value) || typeof value.checkedAt !== "number" || !Number.isFinite(value.checkedAt) || value.source !== "homebrew" && value.source !== "npm" || value.latestVersion !== void 0 && typeof value.latestVersion !== "string") return;
 		return {
 			checkedAt: value.checkedAt,
 			source: value.source,
-			...value.latestVersion === void 0 ? {} : { latestVersion: value.latestVersion },
-			...value.notifiedAt === void 0 ? {} : { notifiedAt: value.notifiedAt }
+			...value.latestVersion === void 0 ? {} : { latestVersion: value.latestVersion }
 		};
 	} catch {
 		return;
@@ -32,20 +36,7 @@ const readUpdateCheckCache = (cachePath) => {
 		return;
 	}
 };
-const writeUpdateCheckCache = (cachePath, cache) => {
-	const temporaryPath = `${cachePath}.${process.pid}.tmp`;
-	try {
-		writeFileSync(temporaryPath, `${JSON.stringify(cache)}\n`, { mode: 384 });
-		renameSync(temporaryPath, cachePath);
-		return true;
-	} catch (error) {
-		try {
-			rmSync(temporaryPath, { force: true });
-		} catch {}
-		log.debug("Could not write the CLI update cache: %s", error instanceof Error ? error.message : String(error));
-		return false;
-	}
-};
+const writeUpdateCheckCache = (cachePath, cache) => writeJsonFile(cachePath, cache, "CLI update cache");
 const formatUpdateNotice = ({ currentVersion, latestVersion, upgradeCommand }) => {
 	if (semver.valid(currentVersion) === null || semver.valid(latestVersion) === null || !semver.gt(latestVersion, currentVersion)) return;
 	return `Neon CLI update available: ${currentVersion} → ${latestVersion}\n${upgradeCommand}`;
@@ -84,6 +75,71 @@ const spawnUpdateWorker = (cachePath, source) => {
 		log.debug("Could not start the CLI update check: %s", error instanceof Error ? error.message : String(error));
 	}
 };
+const INSTALL_LABELS = {
+	homebrew: "Homebrew",
+	bun: "Bun",
+	pnpm: "pnpm",
+	npm: "npm"
+};
+/**
+* `npm exec`, `npx`, package scripts, and `dlx` prepend a project's or a cache's
+* `node_modules/.bin`, which is gone from PATH once the command ends.
+*/
+const isPackageBin = (executable) => {
+	const bin = dirname(executable);
+	return basename(bin) === ".bin" && basename(dirname(bin)) === "node_modules";
+};
+/**
+* Every distinct `command` executable on `path`, in PATH order, leaving out
+* package-local `node_modules/.bin` entries. Entries that resolve to the same
+* file (a repeated PATH directory, Homebrew's `bin` and `opt` links) count once.
+*/
+const findCliInstalls = (command, path) => {
+	const seen = /* @__PURE__ */ new Set();
+	const installs = [];
+	for (const executable of which.sync(command, {
+		all: true,
+		nothrow: true,
+		path
+	}) ?? []) {
+		if (isPackageBin(executable)) continue;
+		const target = realpathSync(executable);
+		if (seen.has(target)) continue;
+		seen.add(target);
+		installs.push({
+			method: detectCliInstallMethod(target),
+			path: executable
+		});
+	}
+	return installs;
+};
+const formatDuplicateInstallNotice = ({ installs, otherNeonctl }) => {
+	if (installs.length < 2) return void 0;
+	const lines = ["Multiple Neon CLI installs found on PATH:", ...installs.map(({ method, path }, index) => {
+		const labels = [...method === void 0 ? [] : [INSTALL_LABELS[method]], ...index === 0 ? ["first on PATH"] : []];
+		return labels.length === 0 ? `  ${path}` : `  ${path} (${labels.join(", ")})`;
+	})];
+	if (!installs.some(({ method }) => method === "homebrew")) {
+		lines.push("Keep one and uninstall the others.");
+		return lines.join("\n");
+	}
+	lines.push(installs.some(({ method }) => method === "npm") ? "Remove the Homebrew install to use npm:" : "Remove the Homebrew install:", "  brew uninstall neonctl");
+	if (!otherNeonctl) lines.push("This also removes the `neonctl` command; run `neon` instead.");
+	lines.push("Then open a new shell.");
+	return lines.join("\n");
+};
+const duplicateInstallNotice = () => {
+	try {
+		const installs = findCliInstalls("neon", process.env.PATH);
+		return formatDuplicateInstallNotice({
+			installs,
+			otherNeonctl: findCliInstalls("neonctl", process.env.PATH).some(({ method }) => method !== "homebrew")
+		});
+	} catch (error) {
+		log.debug("Could not check PATH for other Neon CLI installs: %s", error instanceof Error ? error.message : String(error));
+		return;
+	}
+};
 const isPackagedExecutable = () => "pkg" in process;
 const shouldRunUpdateNotifier = ({ commandPath, currentBranch, disabled, isCi: runningInCi, isPackaged, output, stderrIsTty, stdoutIsTty }) => !runningInCi && !disabled && !isPackaged && output === "table" && stdoutIsTty && stderrIsTty && commandPath.length > 0 && commandPath[0] !== "completion" && !isCurrentBranchProbe({
 	commandPath,
@@ -100,37 +156,43 @@ const notifyIfUpdateAvailable = ({ commandPath, configDir, currentBranch, curren
 		stderrIsTty: process.stderr.isTTY === true,
 		stdoutIsTty: process.stdout.isTTY === true
 	})) return;
+	const now = Date.now();
+	if (process.platform !== "win32") {
+		const duplicateNotice = duplicateInstallNotice();
+		if (duplicateNotice !== void 0) {
+			showNotice({
+				configDir,
+				id: "duplicate-installs",
+				intervalMs: DUPLICATE_NOTICE_INTERVAL_MS,
+				message: duplicateNotice,
+				now
+			});
+			return;
+		}
+	}
 	const command = recommendedCliUpgradeCommand(fileURLToPath(import.meta.url));
 	if (command === void 0) return;
 	const cachePath = join(configDir, CACHE_FILE);
-	const now = Date.now();
 	const source = updateSource(command);
 	const cache = cacheForUpdateSource(readUpdateCheckCache(cachePath), source);
-	let nextCache = cache;
-	if (cache?.latestVersion !== void 0 && (cache.notifiedAt === void 0 || now - cache.notifiedAt >= NOTIFY_INTERVAL_MS)) {
-		const notice = formatUpdateNotice({
-			currentVersion,
-			latestVersion: cache.latestVersion,
-			upgradeCommand: command
-		});
-		if (notice !== void 0) {
-			log.warning("%s", notice);
-			nextCache = {
-				...cache,
-				notifiedAt: now
-			};
-		}
-	}
-	if (!shouldRefreshUpdateCheck(cache, now)) {
-		if (nextCache !== cache && nextCache !== void 0) writeUpdateCheckCache(cachePath, nextCache);
-		return;
-	}
-	nextCache = {
-		...nextCache,
+	const notice = cache?.latestVersion === void 0 ? void 0 : formatUpdateNotice({
+		currentVersion,
+		latestVersion: cache.latestVersion,
+		upgradeCommand: command
+	});
+	if (notice !== void 0) showNotice({
+		configDir,
+		id: "update",
+		intervalMs: UPDATE_NOTICE_INTERVAL_MS,
+		message: notice,
+		now
+	});
+	if (!shouldRefreshUpdateCheck(cache, now)) return;
+	if (writeUpdateCheckCache(cachePath, {
+		...cache,
 		checkedAt: now,
 		source
-	};
-	if (writeUpdateCheckCache(cachePath, nextCache)) spawnUpdateWorker(cachePath, source);
+	})) spawnUpdateWorker(cachePath, source);
 };
 const recordLatestVersion = (cachePath, source, latestVersion) => {
 	if (semver.valid(latestVersion) === null) return;
@@ -142,4 +204,4 @@ const recordLatestVersion = (cachePath, source, latestVersion) => {
 	});
 };
 //#endregion
-export { cacheForUpdateSource, formatUpdateNotice, notifyIfUpdateAvailable, parseUpdateCheckCache, recordLatestVersion, shouldRefreshUpdateCheck, shouldRunUpdateNotifier, spawnUpdateWorkerProcess, writeUpdateCheckCache };
+export { cacheForUpdateSource, findCliInstalls, formatDuplicateInstallNotice, formatUpdateNotice, notifyIfUpdateAvailable, parseUpdateCheckCache, recordLatestVersion, shouldRefreshUpdateCheck, shouldRunUpdateNotifier, spawnUpdateWorkerProcess, writeUpdateCheckCache };

package/dist/utils/json_file.js

@@ -0,0 +1,20 @@
+import { log } from "../log.js";
+import { renameSync, rmSync, writeFileSync } from "node:fs";
+//#region src/utils/json_file.ts
+/** Renames a temporary file into place so a concurrent reader never sees a partial write. */
+const writeJsonFile = (path, value, description) => {
+	const temporaryPath = `${path}.${process.pid}.tmp`;
+	try {
+		writeFileSync(temporaryPath, `${JSON.stringify(value)}\n`, { mode: 384 });
+		renameSync(temporaryPath, path);
+		return true;
+	} catch (error) {
+		try {
+			rmSync(temporaryPath, { force: true });
+		} catch {}
+		log.debug("Could not write the %s: %s", description, error instanceof Error ? error.message : String(error));
+		return false;
+	}
+};
+//#endregion
+export { writeJsonFile };

package/dist/utils/package_manager.js

@@ -159,12 +159,23 @@ const resolvePackageManager = (cwd) => inferPackageManager(cwd) ?? installedPack
 * as {@link resolvePackageManager} minus the lockfile walk.
 */
 const resolveInvokingPackageManager = () => detectInvokingPackageManager() ?? installedPackageManagers()[0] ?? "npm";
+/** How the CLI file at `path` was installed globally, or undefined when it can't be told. */
+const detectCliInstallMethod = (path) => {
+	const normalized = path.replace(/\\/g, "/").toLowerCase();
+	if (normalized.includes("/cellar/neonctl/")) return "homebrew";
+	if (normalized.includes("/.bun/install/global/node_modules/neon/")) return "bun";
+	if (normalized.includes("/pnpm/global/") && normalized.includes("/.pnpm/neon@") && normalized.includes("/node_modules/neon/")) return "pnpm";
+	if (normalized.includes("/lib/node_modules/neon/") || normalized.includes("/npm/node_modules/neon/")) return "npm";
+};
+const CLI_UPGRADE_COMMANDS = {
+	homebrew: "brew upgrade neonctl",
+	bun: "bun i -g neon@latest",
+	pnpm: "pnpm i -g neon@latest",
+	npm: "npm i -g neon@latest"
+};
 const recommendedCliUpgradeCommand = (modulePath) => {
-	const path = modulePath.replace(/\\/g, "/").toLowerCase();
-	if (path.includes("/cellar/neonctl/")) return "brew upgrade neonctl";
-	if (path.includes("/.bun/install/global/node_modules/neon/")) return "bun i -g neon@latest";
-	if (path.includes("/pnpm/global/") && path.includes("/.pnpm/neon@") && path.includes("/node_modules/neon/")) return "pnpm i -g neon@latest";
-	if (path.includes("/lib/node_modules/neon/") || path.includes("/npm/node_modules/neon/")) return "npm i -g neon@latest";
+	const method = detectCliInstallMethod(modulePath);
+	return method === void 0 ? void 0 : CLI_UPGRADE_COMMANDS[method];
 };
 /**
 * The argv for an install with `pm`: every dependency in the manifest when
@@ -333,4 +344,4 @@ const runCommand = (cmd, args, cwd, env) => new Promise((resolvePromise) => {
 	});
 });
 //#endregion
-export { DO_NOT_SUBSTITUTE_HINT, MISSING_BINARY_HINT, commandEnv, detectInvokingPackageManager, detectProjectPackageManager, formatExecCommand, formatInstallCommand, globalInstallCommand, inferPackageManager, installArgs, installedPackageManagers, recommendedCliUpgradeCommand, resolveInvokingPackageManager, resolvePackageManager, runCommand };
+export { DO_NOT_SUBSTITUTE_HINT, MISSING_BINARY_HINT, commandEnv, detectCliInstallMethod, detectInvokingPackageManager, detectProjectPackageManager, formatExecCommand, formatInstallCommand, globalInstallCommand, inferPackageManager, installArgs, installedPackageManagers, recommendedCliUpgradeCommand, resolveInvokingPackageManager, resolvePackageManager, runCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "7.0.1",
+  "version": "7.0.3",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -99,9 +99,9 @@
     "tsx": "4.22.3",
     "typescript": "^5.9.0",
     "vitest": "^3.0.9",
+    "@neon-internals/cli-core": "0.0.0",
     "@neon-internals/env-core": "0.0.26",
     "@neon/e2e-harness": "0.0.0",
-    "@neon-internals/cli-core": "0.0.0",
     "@neon/functions": "0.11.0"
   },
   "publishConfig": {
@@ -134,6 +134,9 @@
     "test": "pnpm --filter neonctl... build && vitest run",
     "test:ci": "pnpm build && vitest run",
     "test:e2e": "pnpm build && vitest run --config vitest.e2e.config.ts",
+    "test:perf": "pnpm --filter neon... build && vitest run src/perf_budget.test.ts",
+    "perf": "tsx scripts/perf/perf.ts",
+    "perf:ci-report": "tsx scripts/perf/ci-report.ts",
     "test:conformance": "vitest run --config tests/psql-conformance/vitest.config.ts"
   }
 }