neon 6.4.0 → 7.0.1

package/README.md

@@ -966,15 +966,12 @@ The plugins CLI installs every plugin it finds in the Neon plugin package. Today
 
 `neon snapshots` (alias `neon snapshot`) manages **snapshots** — point-in-time backups of a branch that you can list, rename, expire, restore into a branch, or schedule automatically. Snapshots are a Beta Neon feature and were previously only available in the Console and REST API; this command group brings them to the CLI.
 
-Every sub-command resolves the project through the standard chain (`--project-id`, then the `.neon` context file, then a single-project auto-detect). Branch-scoped sub-commands (`create`, `schedule`) default to the branch pinned in `.neon`, falling back to the project's default branch, and accept `--branch <id|name>`. The `get`, `update`, `delete`, and `restore` sub-commands take a snapshot **id, unique name, or slug** as their positional argument. An id wins. A unique name still wins over another snapshot's matching slug, so a name you already use keeps targeting that snapshot. Slug is used when no name matches. An ambiguous name errors and asks you to use the id.
+Every sub-command resolves the project through the standard chain (`--project-id`, then the `.neon` context file, then a single-project auto-detect). Branch-scoped sub-commands (`create`, `schedule`) default to the branch pinned in `.neon`, falling back to the project's default branch, and accept `--branch <id|name>`. The `get`, `update`, `delete`, and `restore` sub-commands take a snapshot **id or name** as their positional argument (an id wins; an ambiguous name errors and asks you to use the id).
 
 ```bash
 # Snapshot the head of the current/default branch
 neon snapshots create --name pre-migration
 
-# Give the snapshot a slug (unique in the project; omit to let the API generate one)
-neon snapshots create --branch main --name "Before migration" --slug before-migration
-
 # Snapshot a specific branch at a point in time (RFC 3339 timestamp OR LSN — mutually exclusive)
 neon snapshots create --branch main --timestamp 2025-01-01T00:00:00Z
 neon snapshots create --branch main --lsn 0/1F3C8A0 --expires-at 2025-12-31T23:59:59Z
@@ -982,7 +979,6 @@ neon snapshots create --branch main --lsn 0/1F3C8A0 --expires-at 2025-12-31T23:5
 # List / inspect
 neon snapshots list
 neon snapshots get pre-migration
-neon snapshots get before-migration
 
 # Rename or change expiration (omit both to error; --expires-at and --clear-expiration conflict)
 neon snapshots update snap-1234 --name nightly

package/dist/commands/bucket.js

@@ -82,7 +82,7 @@ const builder = (argv) => argv.usage("$0 bucket <sub-command> [options]").option
 		demandOption: true
 	}).options(scopeOptions),
 	handler: (args) => deleteBucket(args)
-}).command("object <sub-command>", "List, download, upload or delete objects in a bucket", (yargs) => yargs.usage("$0 bucket object <sub-command> [options]").command({
+}).command("object", "List, download, upload or delete objects in a bucket", (yargs) => yargs.usage("$0 bucket object <sub-command> [options]").command({
 	command: "list <target>",
 	aliases: ["ls"],
 	describe: "List objects in a bucket. By default folders are collapsed (like \"aws s3 ls\"); pass --recursive for a flat listing of every key",
@@ -153,7 +153,7 @@ const builder = (argv) => argv.usage("$0 bucket <sub-command> [options]").option
 		}
 	}),
 	handler: (args) => deleteObject(args)
-}).demandCommand(1, "").strictCommands());
+}).strictCommands());
 const handler = (args) => {
 	return args;
 };

package/dist/commands/config.js

@@ -476,7 +476,7 @@ const builder = (argv) => argv.usage("$0 config <sub-command> [options]").option
 	kind: "bucket",
 	name: args.name,
 	access: args.access
-}))).demandCommand(1, "Specify what to add: auth, data-api, ai-gateway, function, or bucket.")).command("init", "Scaffold a neon.ts policy and install the Neon config packages", (yargs) => yargs.options({
+})))).command("init", "Scaffold a neon.ts policy and install the Neon config packages", (yargs) => yargs.options({
 	install: {
 		describe: "Install @neon/config and @neon/env if they're missing. On by default; use --no-install to just print the command.",
 		type: "boolean",

package/dist/commands/functions.js

@@ -129,7 +129,7 @@ const builder = (argv) => argv.usage("$0 function <sub-command> [options]").opti
 	describe: "Function slug",
 	type: "string",
 	demandOption: true
-}), (args) => deleteFn(args)).command(["domains", "domain"], "Manage custom domains on the branch (beta)", (yargs) => yargs.demandCommand(1).command("list", "List custom domains on the branch", (yargs) => yargs, (args) => listDomains(args)).command("register <domain>", "Point a domain you already own at a function on the branch", (yargs) => yargs.positional("domain", {
+}), (args) => deleteFn(args)).command(["domains", "domain"], "Manage custom domains on the branch (beta)", (yargs) => yargs.command("list", "List custom domains on the branch", (yargs) => yargs, (args) => listDomains(args)).command("register <domain>", "Point a domain you already own at a function on the branch", (yargs) => yargs.positional("domain", {
 	describe: "Domain you already own (for example docs.example.com)",
 	type: "string",
 	demandOption: true

package/dist/commands/snapshots.js

@@ -17,7 +17,6 @@ var snapshots_exports = /* @__PURE__ */ __exportAll({
 const SNAPSHOT_FIELDS = [
 	"id",
 	"name",
-	"slug",
 	"source_branch_id",
 	"expires_at",
 	"created_at"
@@ -39,10 +38,8 @@ const SNAPSHOT_FREQUENCIES = [
 	"weekly",
 	"monthly"
 ];
-/** Matches createSnapshot.query.slug in the Management API spec. */
-const SNAPSHOT_SLUG = /^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$/;
 const SNAPSHOT_REF = {
-	describe: "Snapshot id, unique name, or slug. Lookup order: id, unique name, slug.",
+	describe: "Snapshot id or name. An id match wins over a name.",
 	type: "string"
 };
 /** Narrow an arbitrary string to a supported {@link SnapshotFrequency}. */
@@ -53,7 +50,7 @@ const aliases = ["snapshot"];
 const builder = (argv) => argv.usage("$0 snapshots <sub-command> [options]").options({ "project-id": {
 	describe: "Project ID",
 	type: "string"
-} }).middleware(fillSingleProject).command("list", "List snapshots in the project", (yargs) => yargs, (args) => list(args)).command("get <id>", "Get a snapshot by id, unique name, or slug", (yargs) => yargs.positional("id", SNAPSHOT_REF), (args) => get(args)).command("create", "Create a snapshot from a branch", (yargs) => yargs.options({
+} }).middleware(fillSingleProject).command("list", "List snapshots in the project", (yargs) => yargs, (args) => list(args)).command("get <id>", "Get a snapshot by id or name", (yargs) => yargs.positional("id", SNAPSHOT_REF), (args) => get(args)).command("create", "Create a snapshot from a branch", (yargs) => yargs.strict().options({
 	branch: {
 		alias: "b",
 		describe: "Branch id or name to snapshot. Defaults to the branch in your context, or the project's default branch.",
@@ -63,10 +60,6 @@ const builder = (argv) => argv.usage("$0 snapshots <sub-command> [options]").opt
 		describe: "A name for the snapshot",
 		type: "string"
 	},
-	slug: {
-		describe: "User-defined resource ID, unique in the project (1-63 characters: start with a lowercase letter, then lowercase letters, digits, or hyphens, ending with a letter or digit). Omit to let the API generate one. It cannot be changed later.",
-		type: "string"
-	},
 	timestamp: {
 		describe: "Take the snapshot at this point in time (RFC 3339, e.g. 2025-01-01T00:00:00Z). Must fall within the branch's restore window. Mutually exclusive with --lsn.",
 		type: "string"
@@ -82,10 +75,9 @@ const builder = (argv) => argv.usage("$0 snapshots <sub-command> [options]").opt
 }).conflicts("timestamp", "lsn").example([
 	["$0 snapshots create", "Snapshot the head of the context/default branch"],
 	["$0 snapshots create --branch main --name pre-migration", "Snapshot the head of main with a name"],
-	["$0 snapshots create --branch main --name \"Before migration\" --slug before-migration", "Snapshot main with a display name and a slug"],
 	["$0 snapshots create --branch main --timestamp 2025-01-01T00:00:00Z", "Snapshot main at a point in time"],
 	["$0 snapshots create --branch main --lsn 0/1F3C8A0 --expires-at 2025-12-31T23:59:59Z", "Snapshot main at an LSN, auto-deleting at the given time"]
-]), (args) => create(args)).command("update <id>", "Update a snapshot's name or expiration by id, unique name, or slug", (yargs) => yargs.positional("id", SNAPSHOT_REF).options({
+]), (args) => create(args)).command("update <id>", "Update a snapshot's name or expiration", (yargs) => yargs.positional("id", SNAPSHOT_REF).options({
 	name: {
 		describe: "Rename the snapshot",
 		type: "string"
@@ -98,7 +90,7 @@ const builder = (argv) => argv.usage("$0 snapshots <sub-command> [options]").opt
 		describe: "Clear the expiration so the snapshot is kept indefinitely.",
 		type: "boolean"
 	}
-}).conflicts("expires-at", "clear-expiration"), (args) => update(args)).command("delete <id>", "Delete a snapshot by id, unique name, or slug", (yargs) => yargs.positional("id", SNAPSHOT_REF), (args) => deleteSnapshot(args)).command("restore <id>", "Restore a snapshot (id, unique name, or slug) into a branch", (yargs) => yargs.positional("id", SNAPSHOT_REF).options({
+}).conflicts("expires-at", "clear-expiration"), (args) => update(args)).command("delete <id>", "Delete a snapshot by id or name", (yargs) => yargs.positional("id", SNAPSHOT_REF), (args) => deleteSnapshot(args)).command("restore <id>", "Restore a snapshot into a branch", (yargs) => yargs.positional("id", SNAPSHOT_REF).options({
 	name: {
 		describe: "Name for the newly restored branch. Auto-generated when omitted.",
 		type: "string"
@@ -154,7 +146,7 @@ const builder = (argv) => argv.usage("$0 snapshots <sub-command> [options]").opt
 		describe: "Full schedule as JSON, for multi-entry schedules, e.g. '[{\"frequency\":\"daily\",\"hour\":3,\"retention_seconds\":604800}]'. Overrides the single-entry flags.",
 		type: "string"
 	}
-}).example([["$0 snapshots schedule set --branch main --frequency daily --hour 3 --retention 604800", "A daily 03:00 snapshot kept for 7 days"], ["$0 snapshots schedule set --branch main --schedule '[{\"frequency\":\"weekly\",\"day\":1,\"hour\":2},{\"frequency\":\"daily\",\"hour\":3}]'", "A multi-entry schedule via JSON"]]), (args) => scheduleSet(args)).demandCommand(1, "Specify `get` or `set`."), () => {});
+}).example([["$0 snapshots schedule set --branch main --frequency daily --hour 3 --retention 604800", "A daily 03:00 snapshot kept for 7 days"], ["$0 snapshots schedule set --branch main --schedule '[{\"frequency\":\"weekly\",\"day\":1,\"hour\":2},{\"frequency\":\"daily\",\"hour\":3}]'", "A multi-entry schedule via JSON"]]), (args) => scheduleSet(args)), () => {});
 const handler = (args) => {
 	return args;
 };
@@ -167,8 +159,9 @@ const toIso = (value, flag) => {
 	return new Date(ms).toISOString();
 };
 /**
-* Unique names precede slugs so existing name-based commands keep targeting
-* the named snapshot when another snapshot's slug matches that name.
+* Resolve a snapshot from an id **or** a name. Snapshot names are not guaranteed
+* unique, so an id match wins; a name that resolves to more than one snapshot is a
+* hard error asking the user to disambiguate by id.
 */
 const resolveSnapshot = async (props) => {
 	const { data: { snapshots } } = await props.apiClient.listSnapshots(props.projectId);
@@ -177,11 +170,8 @@ const resolveSnapshot = async (props) => {
 	const byName = snapshots.filter((s) => s.name === props.id);
 	if (byName.length === 1) return byName[0];
 	if (byName.length > 1) throw new Error(`Multiple snapshots are named "${props.id}". Re-run with the snapshot id:\n${byName.map((s) => `  ${s.id}`).join("\n")}`);
-	const bySlug = snapshots.find((s) => s.slug === props.id);
-	if (bySlug) return bySlug;
-	throw new Error(`Snapshot "${props.id}" not found.\nAvailable snapshots: ${snapshots.map((s) => formatSnapshotRef(s)).join(", ") || "none"}`);
+	throw new Error(`Snapshot "${props.id}" not found.\nAvailable snapshots: ${snapshots.map((s) => `${s.name} (${s.id})`).join(", ") || "none"}`);
 };
-const formatSnapshotRef = (snapshot) => snapshot.slug ? `${snapshot.name} (${snapshot.id}, slug: ${snapshot.slug})` : `${snapshot.name} (${snapshot.id})`;
 const list = async (props) => {
 	const { data: { snapshots } } = await props.apiClient.listSnapshots(props.projectId);
 	writer(props).end(snapshots, {
@@ -201,14 +191,12 @@ const get = async (props) => {
 const create = async (props) => {
 	if (props.lsn !== void 0 && !looksLikeLSN(props.lsn)) throw new Error(`Invalid --lsn value: "${props.lsn}". Expected an LSN like 0/1F3C8A0.`);
 	if (props.timestamp !== void 0 && !looksLikeTimestamp(props.timestamp)) throw new Error(`Invalid --timestamp value: "${props.timestamp}". Use an RFC 3339 timestamp, e.g. 2025-01-01T00:00:00Z.`);
-	if (props.slug !== void 0 && !SNAPSHOT_SLUG.test(props.slug)) throw new Error(`Invalid --slug value: "${props.slug}". Use 1-63 characters: start with a lowercase letter, then lowercase letters, digits, or hyphens, and end with a letter or digit.`);
 	const { branchId } = await resolveBranchRef({
 		...props,
 		branch: props.branch
 	});
 	const { data } = await retryOnLock(() => props.apiClient.createSnapshot(props.projectId, branchId, {
 		name: props.name,
-		slug: props.slug,
 		timestamp: props.timestamp,
 		lsn: props.lsn,
 		expires_at: props.expiresAt ? toIso(props.expiresAt, "--expires-at") : void 0

package/dist/commands/vpc_endpoints.js

@@ -28,10 +28,9 @@ const builder = (argv) => {
 			},
 			"region-id": {
 				describe: `The region ID. Possible values: ${REGIONS.join(", ")}`,
-				type: "string",
-				demandOption: true
+				type: "string"
 			}
-		}).middleware(fillSingleOrg).command("list", "List configured VPC endpoints for this organization.", (yargs) => yargs, async (args) => {
+		}).middleware(fillSingleOrg).command("list", "List configured VPC endpoints for this organization.", (yargs) => yargs.demandOption("region-id"), async (args) => {
 			await listOrg(args);
 		}).command({
 			command: "assign <id>",
@@ -40,13 +39,13 @@ const builder = (argv) => {
 			builder: (yargs) => yargs.options({ label: {
 				describe: "An optional descriptive label for the VPC endpoint",
 				type: "string"
-			} }),
+			} }).demandOption("region-id"),
 			handler: async (args) => {
 				await assignOrg(args);
 			}
-		}).command("remove <id>", "Remove a VPC endpoint from this organization.", (yargs) => yargs, async (args) => {
+		}).command("remove <id>", "Remove a VPC endpoint from this organization.", (yargs) => yargs.demandOption("region-id"), async (args) => {
 			await removeOrg(args);
-		}).command("status <id>", "Get the status of a VPC endpoint for this organization.", (yargs) => yargs, async (args) => {
+		}).command("status <id>", "Get the status of a VPC endpoint for this organization.", (yargs) => yargs.demandOption("region-id"), async (args) => {
 			await statusOrg(args);
 		});
 	}).command("project", "Manage project-level VPC endpoint restrictions.\nBy default, connections are accepted from any VPC configured at the organization level.\nA project-level VPC endpoint restriction can be used to restrict connections to a specific VPC.", (yargs) => {

package/dist/help.js

@@ -232,19 +232,58 @@ const formatHelp = (help) => {
 	}
 	return [...result, ...lines];
 };
-const showHelp = async (argv) => {
-	const help = await argv.getHelp();
-	const text = `${formatHelp(help).join("\n")}\n`;
-	await new Promise((resolve, reject) => {
-		process.stdout.write(text, (err) => {
-			if (err) {
-				reject(err);
-				return;
-			}
-			resolve();
-		});
+const writeHelp = (help, stream) => new Promise((resolve, reject) => {
+	stream.write(`${formatHelp(help).join("\n")}\n`, (err) => {
+		if (err) {
+			reject(err);
+			return;
+		}
+		resolve();
 	});
+});
+const showHelp = async (argv) => {
+	await writeHelp(await argv.getHelp(), process.stdout);
 	process.exit(0);
 };
+/**
+* A yargs validation failure: a missing required option or positional, an unknown
+* subcommand, a value outside `choices`. Carries the failing command's help, captured
+* in `.fail` because yargs has restored the parent's context by the time the error
+* reaches the caller.
+*/
+var UsageError = class extends Error {
+	constructor(message, help) {
+		super(message);
+		this.help = help;
+	}
+};
+/** On stderr, so `-o json` stdout stays empty. */
+const showUsageErrorHelp = (err) => writeHelp(err.help, process.stderr);
+/**
+* The yargs `.fail` handler. yargs passes its usage instance as the third argument
+* (`@types/yargs` declares it as `Argv`). Errors thrown by a handler, a `coerce`, or the
+* parser arrive with their own `err` and are rethrown unchanged.
+*/
+const failOnUsageError = (msg, err, usage) => {
+	if (err) throw err;
+	if (typeof usage !== "object" || usage === null || !("help" in usage) || typeof usage.help !== "function") throw new Error("yargs no longer passes its usage instance to .fail(); update failOnUsageError for the installed yargs");
+	const help = usage.help();
+	if (typeof help !== "string") throw new Error("yargs usage.help() did not return a string");
+	throw new UsageError(msg ?? "Invalid usage", help);
+};
+function assertYargsInternals(argv) {
+	if (!("getInternalMethods" in argv) || typeof argv.getInternalMethods !== "function") throw new Error("yargs no longer exposes getInternalMethods(); update isBareParentCommand for the installed yargs");
+}
+/**
+* True when the command yargs is running groups subcommands and none was given, at any
+* depth: `neon config add`, `neon snapshots schedule`. `@types/yargs` doesn't declare the
+* running command's context, so this reads yargs 17's internals.
+*/
+const isBareParentCommand = (argv, positionals) => {
+	assertYargsInternals(argv);
+	const internals = argv.getInternalMethods();
+	const path = internals.getContext().commands;
+	return path.length > 0 && positionals.length === path.length && internals.getCommandInstance().getCommands().length > 0;
+};
 //#endregion
-export { showHelp };
+export { UsageError, failOnUsageError, isBareParentCommand, showHelp, showUsageErrorHelp };

package/dist/index.js

@@ -11,7 +11,7 @@ import { AuthRefreshError, defaultClientID } from "./auth.js";
 import { getCliName } from "./utils/cli_name.js";
 import { ensureAuth } from "./commands/auth.js";
 import { recoverFrom401 } from "./auth_recovery.js";
-import { showHelp } from "./help.js";
+import { UsageError, failOnUsageError, isBareParentCommand, showHelp, showUsageErrorHelp } from "./help.js";
 import { rewriteUnknownAgentArg } from "./init/plan.js";
 import commands_default from "./commands/index.js";
 import { recoverFromSSO } from "./sso_recovery.js";
@@ -125,13 +125,16 @@ builder = builder.scriptName(pkg_default.name).locale("en").usage("$0 <command>
 	type: "boolean",
 	default: false
 }).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);
+	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);
 async function handleError(msg, err, canRetry) {
 	if (process.argv.some((arg) => arg === "--help" || arg === "-h")) {
 		await showHelp(builder);
 		process.exit(0);
 	}
+	if (err instanceof UsageError) await showUsageErrorHelp(err);
 	if (err instanceof Error && err.stack) log.debug("Stack: %s", err.stack);
 	if (err instanceof Error) {
 		const rewritten = rewriteUnknownAgentArg({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "6.4.0",
+  "version": "7.0.1",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -64,9 +64,9 @@
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
     "yoctocolors": "^2.1.2",
-    "@neon/config-runtime": "1.7.2",
-    "@neon/sdk": "6.1.2",
-    "@neon/config": "1.8.2"
+    "@neon/config": "1.8.3",
+    "@neon/config-runtime": "1.7.3",
+    "@neon/sdk": "7.0.0"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0",
@@ -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.25",
+    "@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": {