neon 6.0.0 → 6.1.0

package/README.md

@@ -936,12 +936,15 @@ 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 or name** as their positional argument (an id wins; 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, 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.
 
 ```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
@@ -949,6 +952,7 @@ 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/bootstrap.js

@@ -2,12 +2,10 @@ import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { isCi } from "../env.js";
 import { log } from "../log.js";
 import { recordCommandSuccessExtras, recordScaffoldedTemplate } from "../analytics.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";
@@ -271,7 +269,9 @@ const runDefaultSteps = async (props, targetDir, pm, neonConfig, template, named
 };
 const executePostScaffold = async (props, targetDir, choices) => {
 	const kids = {
-		...bootstrapChildren(props, targetDir),
+		output: "table",
+		auth: bootstrapAuth(props, targetDir),
+		operations: props.operations,
 		...props.narrate ? { narrate: props.narrate } : {}
 	};
 	let installed = false;
@@ -370,20 +370,22 @@ const hasNeonConfig = (dir) => NEON_CONFIG_FILENAMES.some((name) => existsSync(j
 const logSkippedLink = (pm) => {
 	log.info(`Skipping the Neon link step: \`${getCliName()} link\` reads this project's neon.ts to pull env vars, which needs its dependencies. Run \`${formatInstallCommand(pm)}\`, then \`${getCliName()} link\`.`);
 };
-const bootstrapChildren = (props, targetDir) => {
-	const explicitKey = props.profile ? "" : credentialInputs().apiKeyFlag;
-	return {
-		run: props.run ?? spawnCliChild,
-		forward: {
-			...props.configDir ? { configDir: props.configDir } : {},
-			...props.profile ? { profile: props.profile } : {},
-			apiHost: props.apiHost,
-			contextFile: projectContextFile(targetDir, props.contextFile),
-			...props.analytics === false ? { analytics: false } : {}
-		},
-		...explicitKey ? { authEnv: { NEON_API_KEY: explicitKey } } : {}
-	};
-};
+/**
+* plugins/skills need no Neon auth at all; mcp resolves it itself, in-process, exactly as
+* the standalone `neon mcp` does (see `init/auth.ts`) — this is that shared context.
+*/
+const bootstrapAuth = (props, targetDir) => ({
+	apiClient: props.apiClient,
+	apiKey: props.apiKey,
+	apiHost: props.apiHost,
+	contextFile: projectContextFile(targetDir, props.contextFile),
+	...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 } : {}
+});
 /**
 * Initialize a git repository in the scaffolded directory. Just `git init` — we
 * deliberately don't auto-commit, both to avoid failing on a machine with no

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 { spawn, spawnSync } from "node:child_process";
 import { bundleAsIs, describeNativeFinding, findUndeclaredNativePackages, resolveEsbuildEntry } from "@neon/config-runtime";
+import { spawn, spawnSync } from "node:child_process";
 import { once } from "node:events";
 import { createServer } from "node:net";
 //#region src/commands/dev.ts

package/dist/commands/index.js

@@ -6,6 +6,9 @@ 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 mcp_exports } from "./mcp.js";
+import { t as plugins_exports } from "./plugins.js";
+import { t as skills_exports } from "./skills.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";
@@ -23,17 +26,14 @@ import { t as init_exports } from "./init.js";
 import { t as inspect_exports } from "./inspect.js";
 import { t as ip_allow_exports } from "./ip_allow.js";
 import { t as logs_exports } from "./logs.js";
-import { t as mcp_exports } from "./mcp.js";
 import { t as neon_auth_exports } from "./neon_auth.js";
 import { t as open_exports } from "./open.js";
 import { t as operations_exports } from "./operations.js";
 import { t as orgs_exports } from "./orgs.js";
-import { t as plugins_exports } from "./plugins.js";
 import { t as profile_exports } from "./profile.js";
 import { t as psql_exports } from "./psql.js";
 import { t as roles_exports } from "./roles.js";
 import { t as set_context_exports } from "./set_context.js";
-import { t as skills_exports } from "./skills.js";
 import { t as snapshots_exports } from "./snapshots.js";
 import { t as status_exports } from "./status.js";
 import { t as triggers_exports } from "./triggers.js";

package/dist/commands/init.js

@@ -3,7 +3,6 @@ import { getCliName } from "../utils/cli_name.js";
 import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { servicesOption } from "../neon_services.js";
 import { CONFIG_INIT_NONE_MEANS, CONFIG_INIT_SERVICES } from "../config_template.js";
-import { initChildEnv } from "../init/child.js";
 import { coerceAgentFlag } from "../utils/agent_flag.js";
 import { initPluginAgents, initSkillsMcpAgents } from "../init/plan.js";
 import { listSkillIds } from "../skills/catalog.js";
@@ -13,8 +12,7 @@ var init_exports = /* @__PURE__ */ __exportAll({
 	builder: () => builder,
 	command: () => command,
 	describe: () => describe,
-	handler: () => handler,
-	initChildEnv: () => initChildEnv
+	handler: () => handler
 });
 const command = "init";
 const describe = "Set up coding agents and this directory for Neon. -y is Recommended. -y with Custom flags applies those answers without prompts.";
@@ -108,4 +106,4 @@ const handler = async (props) => {
 	await runInit(props);
 };
 //#endregion
-export { builder, command, describe, handler, initChildEnv, init_exports as t };
+export { builder, command, describe, handler, init_exports as t };

package/dist/commands/mcp.js

@@ -8,15 +8,18 @@ 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 { mintMcpApiKey, mintedKeyRevokeCommand, withdrawMintedKey } from "../mcp/mint.js";
+import { canPickAgentsInteractively } from "../utils/agent_picker.js";
 import { resolveMcpPlan } from "../mcp/plan.js";
 //#region src/commands/mcp.ts
 var mcp_exports = /* @__PURE__ */ __exportAll({
 	builder: () => builder,
 	command: () => "mcp",
 	describe: () => describe,
-	handler: () => handler
+	handler: () => handler,
+	mcpInstallError: () => mcpInstallError,
+	reportMcpInstall: () => reportMcpInstall,
+	setupNeonMcp: () => setupNeonMcp
 });
 const command = "mcp";
 const describe = "Install the Neon MCP server into coding agents";
@@ -87,20 +90,29 @@ const builder = (argv) => argv.usage("$0 mcp [options]").options({
 		}
 	}
 }).example("$0 mcp", "Interactive: config location, agents, then auth").example("$0 mcp -y", "Global config, installed apps else the host CLI agent, reuse or mint an API key").example("$0 mcp --oauth", "Install with OAuth; the agent signs in on first use").example("$0 mcp --agent cursor --agent claude-code", "Install into specific agents").example("$0 mcp --project", "Write project-level config").example("$0 mcp --read-only", "Hide write tools via ?readonly=true").example("$0 mcp --project-id <id>", "Pin tools to one project via ?projectId=").example("$0 mcp --category querying --category schema", "Limit tools to those categories").epilogue(helpEpilogue(`Installs ${NEON_MCP_URL}`, helpCsv("Supported agents at global scope", mcpGlobalAgents), helpCsv("--project does not support", mcpProjectDroppedAgents), helpCsv("Supported categories", NEON_MCP_CATEGORIES), "neon mcp -y:", "  global config", "  globally installed apps, else the host CLI agent", "  reuse an existing Neon MCP API key, else mint an account-wide key", "  write tools on, all categories", "  no project pin (including from .neon)")).strict().check(noPassthrough("mcp"));
-const handler = async (props) => {
-	const cwd = process.cwd();
-	const interactive = canPickAgentsInteractively() && props.yes !== true;
-	const linkedProjectId = readContextFile(props.contextFile).projectId;
+/**
+* Resolves auth, mints or reuses an API key, and writes the Neon MCP server into every
+* resolved agent. No CLI-only concerns here (no `writer` table, no
+* `recordCommandSuccessExtras`): a caller that only wants the outcome — `neon init` /
+* `neon bootstrap` — gets it without rendering a table.
+*
+* Throws directly when zero agents succeed, since that path never reaches a results table
+* worth showing (same as the CLI handler always did).
+*/
+const setupNeonMcp = async (options) => {
+	const cwd = options.cwd ?? process.cwd();
+	const interactive = canPickAgentsInteractively() && options.yes !== true;
+	const linkedProjectId = readContextFile(options.contextFile).projectId;
 	const plan = await resolveMcpPlan({
-		project: props.project === true,
-		oauth: props.oauth === true,
-		agents: props.agent ?? [],
-		yes: props.yes === true,
+		project: options.project === true,
+		oauth: options.oauth === true,
+		agents: options.agent ?? [],
+		yes: options.yes === true,
 		cwd,
 		interactive,
-		readOnly: props.readOnly === true,
-		projectId: props.projectId,
-		categories: props.category ?? [],
+		readOnly: options.readOnly === true,
+		projectId: options.projectId,
+		categories: options.category ?? [],
 		linkedProjectId
 	});
 	const { install, skipped } = resolveInstallTargets({
@@ -125,8 +137,8 @@ const handler = async (props) => {
 		cwd
 	}) : void 0;
 	if (plan.auth === "api-key" && !existing) {
-		if (!props.apiClient || !props.apiKey) throw new Error(`Authentication required. Run \`${getCliName()} auth\`, pass --api-key or use --oauth to install without a Neon credential.`);
-		if (!canPickAgentsInteractively() && props.yes !== true && (props.agent ?? []).length === 0) throw new Error("No interactive terminal. Pass -y to mint into every detected agent, --agent <name> to name them or --oauth to install without minting.");
+		if (!options.apiClient || !options.apiKey) throw new Error(`Authentication required. Run \`${getCliName()} auth\`, pass --api-key or use --oauth to install without a Neon credential.`);
+		if (!canPickAgentsInteractively() && options.yes !== true && (options.agent ?? []).length === 0) throw new Error("No interactive terminal. Pass -y to mint into every detected agent, --agent <name> to name them or --oauth to install without minting.");
 	}
 	let auth;
 	let minted;
@@ -140,7 +152,7 @@ const handler = async (props) => {
 		if (plan.urlProjectId) log.warning("That key keeps its existing scope. Remove the Neon MCP entry to mint a project-scoped key, or pass --oauth to pin tools without a key.");
 	} else {
 		minted = await mintMcpApiKey({
-			apiClient: props.apiClient,
+			apiClient: options.apiClient,
 			projectId: plan.urlProjectId
 		});
 		auth = {
@@ -183,15 +195,28 @@ const handler = async (props) => {
 		error: row.error
 	});
 	if (successes === 0) {
-		if (minted && props.apiClient) {
-			const withdrawn = await withdrawMintedKey(props.apiClient, minted);
+		if (minted && options.apiClient) {
+			const withdrawn = await withdrawMintedKey(options.apiClient, minted);
 			throw new Error(withdrawn ? "Failed to write Neon MCP config to any agent. The minted API key has been revoked." : `Failed to write Neon MCP config to any agent. The minted API key could NOT be revoked. Remove it with \`${mintedKeyRevokeCommand(minted)}\`.`);
 		}
 		throw new Error("Failed to write Neon MCP config to any agent.");
 	}
-	log.info("URL: %s", url);
+	return {
+		scope: plan.scope,
+		rows,
+		failedAgents,
+		url,
+		auth: auth.kind,
+		...minted ? { minted } : {}
+	};
+};
+/** The exact error `neon mcp` throws when some (not all) agents failed, or `undefined` on full success. */
+const mcpInstallError = (outcome) => outcome.failedAgents.length > 0 ? /* @__PURE__ */ new Error(`Failed to write Neon MCP config for: ${outcome.failedAgents.join(", ")}.`) : void 0;
+/** Writes the results table plus the URL/minted-key/OAuth notices. Shared by `neon mcp` and any in-process caller that wants the same human output. */
+const reportMcpInstall = (props, outcome) => {
+	log.info("URL: %s", outcome.url);
 	const out = writer(props);
-	out.write(rows, {
+	out.write(outcome.rows, {
 		fields: [
 			"agent",
 			"status",
@@ -200,10 +225,27 @@ const handler = async (props) => {
 		title: "MCP"
 	});
 	out.end();
-	if (minted) log.info("Minted API key %s (id %d, %s). Revoke with: %s", minted.name, minted.id, minted.projectId ? "project" : "account", mintedKeyRevokeCommand(minted));
-	if (plan.auth === "oauth") log.info("The agent will prompt for Neon sign-in on first use.");
-	if (failedAgents.length > 0) throw new Error(`Failed to write Neon MCP config for: ${failedAgents.join(", ")}.`);
-	recordCommandSuccessExtras({ scope: plan.scope });
+	if (outcome.minted) log.info("Minted API key %s (id %d, %s). Revoke with: %s", outcome.minted.name, outcome.minted.id, outcome.minted.projectId ? "project" : "account", mintedKeyRevokeCommand(outcome.minted));
+	if (outcome.auth === "oauth") log.info("The agent will prompt for Neon sign-in on first use.");
+};
+const handler = async (props) => {
+	const outcome = await setupNeonMcp({
+		apiClient: props.apiClient,
+		apiKey: props.apiKey,
+		contextFile: props.contextFile,
+		cwd: props.cwd,
+		yes: props.yes,
+		oauth: props.oauth,
+		project: props.project,
+		agent: props.agent,
+		readOnly: props.readOnly,
+		projectId: props.projectId,
+		category: props.category
+	});
+	reportMcpInstall(props, outcome);
+	const error = mcpInstallError(outcome);
+	if (error) throw error;
+	recordCommandSuccessExtras({ scope: outcome.scope });
 };
 //#endregion
-export { builder, command, describe, handler, mcp_exports as t };
+export { builder, command, describe, handler, mcpInstallError, reportMcpInstall, setupNeonMcp, mcp_exports as t };

package/dist/commands/plugins.js

@@ -17,7 +17,10 @@ var plugins_exports = /* @__PURE__ */ __exportAll({
 	builder: () => builder,
 	command: () => command,
 	describe: () => describe,
-	handler: () => handler
+	handler: () => handler,
+	installPlugins: () => installPlugins,
+	pluginsInstallError: () => pluginsInstallError,
+	reportPluginsInstall: () => reportPluginsInstall
 });
 const coerceAgents = (value) => {
 	if (value === void 0) return [];
@@ -54,13 +57,18 @@ const builder = (argv) => argv.usage("$0 plugins [options]").options({
 		coerce: coerceAgents
 	}
 }).example("$0 plugins", "Interactive: pick agents, then install").example("$0 plugins -y", "Detected agents (project folders, else the host CLI agent), skip prompts").example("$0 plugins --agent cursor --agent claude-code", "Install into specific agents").example("$0 plugins --global", "Install user-level").epilogue(helpEpilogue(helpCsv("Supported agents at project scope", pluginProjectAgents), helpCsv("Also with --global", pluginGlobalOnlyAgents), `Currently one plugin: ${NEON_PLUGIN_NAME} from ${PLUGIN_SOURCE}.`, `It includes the Neon MCP server (${NEON_MCP_URL})`, helpCsv("and these skills", PLUGIN_SKILLS))).strict().check(noPassthrough("plugins"));
-const handler = async (props) => {
-	const cwd = process.cwd();
-	const yes = props.yes === true;
+/**
+* Plans and runs the plugin install for every resolved target. No CLI-only concerns here
+* (no `writer` table, no `recordCommandSuccessExtras`): a caller that only wants the
+* outcome — `neon init` / `neon bootstrap` — gets it without rendering a result table.
+*/
+const installPlugins = async (options) => {
+	const cwd = options.cwd ?? process.cwd();
+	const yes = options.yes === true;
 	const interactive = canPickAgentsInteractively() && !yes;
 	const plan = await resolvePluginsPlan({
-		global: props.global === true,
-		agents: props.agent ?? [],
+		global: options.global === true,
+		agents: options.agents ?? [],
 		yes,
 		cwd,
 		interactive
@@ -70,12 +78,14 @@ const handler = async (props) => {
 	const rows = [];
 	const failed = [];
 	const scope = scopeLabel(plan.scope);
-	for (const mapped of plan.targets) {
+	for (const [index, mapped] of plan.targets.entries()) {
 		const args = pluginsAddArgs({
 			target: mapped.target,
 			global: plan.scope === "global"
 		});
 		const agent = mapped.agents.join(", ");
+		const displayNames = mapped.agents.map((id) => getAgentDisplayName(id)).join(", ");
+		log.info("Installing the Neon plugin for %s (%d/%d)...", displayNames, index + 1, plan.targets.length);
 		try {
 			await runPluginsCli({
 				args,
@@ -102,8 +112,31 @@ const handler = async (props) => {
 			});
 		}
 	}
+	return {
+		scope: plan.scope,
+		rows,
+		failed
+	};
+};
+/** The exact error `neon plugins` throws for a failed outcome, or `undefined` on success. */
+const pluginsInstallError = (outcome) => {
+	const { failed, rows, scope } = outcome;
+	if (failed.length === 0) return;
+	const first = failed[0];
+	if (first === void 0) return /* @__PURE__ */ new Error("Failed to install the Neon plugin.");
+	const retry = neonPluginsRetryCommand({
+		agents: failed.flatMap((row) => row.agents),
+		global: scope === "global"
+	});
+	if (first.message.includes("needs npx (Node.js)")) return new Error(first.message);
+	const detail = failed.map((row) => row.message).join("\n");
+	if (failed.length === rows.length) return /* @__PURE__ */ new Error(`${detail}\nRetry with: ${retry}`);
+	return /* @__PURE__ */ new Error(`Failed to install the Neon plugin for: ${failed.flatMap((row) => row.agents).join(", ")}.\n${detail}\nRetry with: ${retry}`);
+};
+/** Writes the results table and, on success, the "Installed the Neon plugin" line. Shared by `neon plugins` and any in-process caller that wants the same human output. */
+const reportPluginsInstall = (props, outcome) => {
 	const out = writer(props);
-	out.write(rows, {
+	out.write(outcome.rows, {
 		fields: [
 			"scope",
 			"plugin",
@@ -114,21 +147,19 @@ const handler = async (props) => {
 		title: "Plugins"
 	});
 	out.end();
-	if (failed.length === 0) {
-		recordCommandSuccessExtras({ scope: plan.scope });
-		log.info(plan.scope === "project" ? "Installed the Neon plugin (project)." : "Installed the Neon plugin (user).");
-		return;
-	}
-	const first = failed[0];
-	if (first === void 0) throw new Error("Failed to install the Neon plugin.");
-	const retry = neonPluginsRetryCommand({
-		agents: failed.flatMap((row) => row.agents),
-		global: plan.scope === "global"
+	if (outcome.failed.length === 0) log.info(outcome.scope === "project" ? "Installed the Neon plugin (project)." : "Installed the Neon plugin (user).");
+};
+const handler = async (props) => {
+	const outcome = await installPlugins({
+		cwd: props.cwd,
+		yes: props.yes,
+		global: props.global,
+		agents: props.agent
 	});
-	if (first.message.includes("needs npx (Node.js)")) throw new Error(first.message);
-	const detail = failed.map((row) => row.message).join("\n");
-	if (failed.length === rows.length) throw new Error(`${detail}\nRetry with: ${retry}`);
-	throw new Error(`Failed to install the Neon plugin for: ${failed.flatMap((row) => row.agents).join(", ")}.\n${detail}\nRetry with: ${retry}`);
+	reportPluginsInstall(props, outcome);
+	const error = pluginsInstallError(outcome);
+	if (error) throw error;
+	recordCommandSuccessExtras({ scope: outcome.scope });
 };
 //#endregion
-export { aliases, builder, command, describe, handler, plugins_exports as t };
+export { aliases, builder, command, describe, handler, installPlugins, pluginsInstallError, reportPluginsInstall, plugins_exports as t };

package/dist/commands/skills.js

@@ -18,7 +18,10 @@ var skills_exports = /* @__PURE__ */ __exportAll({
 	builder: () => builder,
 	command: () => command,
 	describe: () => describe,
-	handler: () => handler
+	handler: () => handler,
+	installSkills: () => installSkills,
+	reportSkillsInstall: () => reportSkillsInstall,
+	skillsInstallError: () => skillsInstallError
 });
 const scopeLabel = (scope) => scope === "project" ? "this directory" : "user-level";
 const coerceAgents = (value) => {
@@ -83,15 +86,20 @@ const builder = (argv) => argv.usage("$0 skills [command] [options]").command("u
 		coerce: coerceSkills
 	}
 }).example("$0 skills", "Interactive: this directory, then agents, then skills").example("$0 skills -y", "This directory, detected agents (project folders, else the host CLI agent), the default skills").example("$0 skills -y -s neon -s neon-ai-gateway", "Named skills into detected agents").example("$0 skills -s neon -s neon-ai-gateway --agent cursor", "Named skills into a named agent").example("$0 skills --global", "Install user-level skills").epilogue(helpEpilogue(helpCsv("Supported agents", skillsInstallableAgents()), "Supported skills, by source repo:", skillsHelpValues(), skillsYesHelp())).strict().check(noPassthrough("skills"));
-const handler = async (props) => {
+/**
+* Plans and runs the skills install for every resolved source/invocation. No CLI-only
+* concerns here (no `writer` table, no `recordCommandSuccessExtras`): a caller that only
+* wants the outcome — `neon init` / `neon bootstrap` — gets it without rendering a table.
+*/
+const installSkills = async (options) => {
 	assertSkillsNode();
-	const cwd = process.cwd();
-	const yes = props.yes === true;
+	const cwd = options.cwd ?? process.cwd();
+	const yes = options.yes === true;
 	const interactive = canPickAgentsInteractively() && !yes;
 	const plan = await resolveSkillsPlan({
-		global: props.global === true,
-		agents: props.agent ?? [],
-		skills: props.skill ?? [],
+		global: options.global === true,
+		agents: options.agents ?? [],
+		skills: options.skills ?? [],
 		yes,
 		cwd,
 		interactive
@@ -138,8 +146,32 @@ const handler = async (props) => {
 			});
 		}
 	}
+	return {
+		scope: plan.scope,
+		agents: plan.agents,
+		rows,
+		failed
+	};
+};
+/** The exact error `neon skills` throws for a failed outcome, or `undefined` on success. */
+const skillsInstallError = (outcome) => {
+	const { failed, rows, scope, agents } = outcome;
+	if (failed.length === 0) return;
+	const first = failed[0];
+	if (first === void 0) return /* @__PURE__ */ new Error("Failed to install Neon agent skills.");
+	const retry = neonSkillsRetryCommand({
+		skills: failed.flatMap((row) => row.skills),
+		agents,
+		global: scope === "global"
+	});
+	if (first.message.includes("needs npx (Node.js)") || first.message.includes("needs Node.js")) return new Error(first.message);
+	if (failed.length === rows.length) return /* @__PURE__ */ new Error(`${first.message}\nRetry with: ${retry}`);
+	return /* @__PURE__ */ new Error(`Failed to install Neon agent skills for: ${failed.map((row) => row.label).join(", ")}.\n${first.message}\nRetry with: ${retry}`);
+};
+/** Writes the results table and, on success, the "Wrote ... skills" line. Shared by `neon skills` and any in-process caller that wants the same human output. */
+const reportSkillsInstall = (props, outcome) => {
 	const out = writer(props);
-	out.write(rows, {
+	out.write(outcome.rows, {
 		fields: [
 			"scope",
 			"skills",
@@ -150,21 +182,20 @@ const handler = async (props) => {
 		title: "Skills"
 	});
 	out.end();
-	if (failed.length === 0) {
-		recordCommandSuccessExtras({ scope: plan.scope });
-		log.info(plan.scope === "project" ? "Wrote skills in this directory." : "Wrote user-level skills.");
-		return;
-	}
-	const first = failed[0];
-	if (first === void 0) throw new Error("Failed to install Neon agent skills.");
-	const retry = neonSkillsRetryCommand({
-		skills: failed.flatMap((row) => row.skills),
-		agents: plan.agents,
-		global: plan.scope === "global"
+	if (outcome.failed.length === 0) log.info(outcome.scope === "project" ? "Wrote skills in this directory." : "Wrote user-level skills.");
+};
+const handler = async (props) => {
+	const outcome = await installSkills({
+		cwd: props.cwd,
+		yes: props.yes,
+		global: props.global,
+		agents: props.agent,
+		skills: props.skill
 	});
-	if (first.message.includes("needs npx (Node.js)") || first.message.includes("needs Node.js")) throw new Error(first.message);
-	if (failed.length === rows.length) throw new Error(`${first.message}\nRetry with: ${retry}`);
-	throw new Error(`Failed to install Neon agent skills for: ${failed.map((row) => row.label).join(", ")}.\n${first.message}\nRetry with: ${retry}`);
+	reportSkillsInstall(props, outcome);
+	const error = skillsInstallError(outcome);
+	if (error) throw error;
+	recordCommandSuccessExtras({ scope: outcome.scope });
 };
 const updateHandler = async (props) => {
 	assertSkillsNode();
@@ -219,4 +250,4 @@ const updateHandler = async (props) => {
 	if (failure !== void 0) throw new Error(failure.includes("needs npx (Node.js)") || failure.includes("needs Node.js") ? failure : `${failure}\nRetry with: ${neonSkillsUpdateRetryCommand(scope === "global")}`);
 };
 //#endregion
-export { aliases, builder, command, describe, handler, skills_exports as t };
+export { aliases, builder, command, describe, handler, installSkills, reportSkillsInstall, skillsInstallError, skills_exports as t };

package/dist/commands/snapshots.js

@@ -17,6 +17,7 @@ var snapshots_exports = /* @__PURE__ */ __exportAll({
 const SNAPSHOT_FIELDS = [
 	"id",
 	"name",
+	"slug",
 	"source_branch_id",
 	"expires_at",
 	"created_at"
@@ -38,6 +39,12 @@ 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.",
+	type: "string"
+};
 /** Narrow an arbitrary string to a supported {@link SnapshotFrequency}. */
 const isSnapshotFrequency = (value) => SNAPSHOT_FREQUENCIES.some((frequency) => frequency === value);
 const command = "snapshots";
@@ -46,7 +53,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 or name", (yargs) => yargs, (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, unique name, or slug", (yargs) => yargs.positional("id", SNAPSHOT_REF), (args) => get(args)).command("create", "Create a snapshot from a branch", (yargs) => yargs.options({
 	branch: {
 		alias: "b",
 		describe: "Branch id or name to snapshot. Defaults to the branch in your context, or the project's default branch.",
@@ -56,6 +63,10 @@ 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"
@@ -71,9 +82,10 @@ 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", (yargs) => yargs.options({
+]), (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({
 	name: {
 		describe: "Rename the snapshot",
 		type: "string"
@@ -86,7 +98,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 or name", (yargs) => yargs, (args) => deleteSnapshot(args)).command("restore <id>", "Restore a snapshot into a branch", (yargs) => yargs.options({
+}).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({
 	name: {
 		describe: "Name for the newly restored branch. Auto-generated when omitted.",
 		type: "string"
@@ -155,9 +167,8 @@ const toIso = (value, flag) => {
 	return new Date(ms).toISOString();
 };
 /**
-* 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.
+* Unique names precede slugs so existing name-based commands keep targeting
+* the named snapshot when another snapshot's slug matches that name.
 */
 const resolveSnapshot = async (props) => {
 	const { data: { snapshots } } = await props.apiClient.listSnapshots(props.projectId);
@@ -166,8 +177,11 @@ 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")}`);
-	throw new Error(`Snapshot "${props.id}" not found.\nAvailable snapshots: ${snapshots.map((s) => `${s.name} (${s.id})`).join(", ") || "none"}`);
+	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"}`);
 };
+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, {
@@ -187,12 +201,14 @@ 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