neon 4.12.0 → 4.13.1

package/README.md

@@ -1,6 +1,6 @@
 # Neon CLI
 
-The `neon` package is a command-line interface that lets you manage [Neon](https://neon.tech/) — Lakebase Postgres, Object Storage, Functions, Managed Better Auth, and the AI Gateway — directly from the terminal. For the complete documentation, see [Neon CLI](https://neon.tech/docs/reference/neon-cli).
+The `neon` package is a command-line interface that lets you manage [Neon](https://neon.com/) — Lakebase Postgres, Object Storage, Functions, Managed Better Auth, and the AI Gateway — directly from the terminal. For the complete documentation, see [Neon CLI](https://neon.com/docs/cli).
 
 The legacy `neonctl` package is a lightweight compatibility package that depends
 on this package and invokes the same CLI entry point. The implementation and
@@ -54,7 +54,7 @@ Run the following command to authenticate a connection to Neon:
 neon auth
 ```
 
-The `auth` command launches a browser window where you can authorize the Neon CLI to access your Neon account. Running a Neon CLI command without authenticating with [neon auth](https://neon.tech/docs/reference/cli-auth) automatically launches the browser authentication process.
+The `auth` command launches a browser window where you can authorize the Neon CLI to access your Neon account. Running a Neon CLI command without authenticating with [neon auth](https://neon.com/docs/cli/auth) automatically launches the browser authentication process.
 
 Alternatively, you can authenticate a connection with a Neon API key using the `--api-key` option when running a Neon CLI command. For example, an API key is used with the following `neon projects list` command:
 
@@ -165,7 +165,7 @@ neon projects update <project-id> --enable-logical-replication --yes
 
 ### The `psql` command
 
-`neon psql [branch]` opens a psql session against a branch. It builds the connection string for the branch and launches psql — a shortcut for `neon connection-string --psql`. See [Neon CLI commands — psql](https://neon.com/docs/reference/cli-psql) for the full reference.
+`neon psql [branch]` opens a psql session against a branch. It builds the connection string for the branch and launches psql — a shortcut for `neon connection-string --psql`. See [Neon CLI commands — psql](https://neon.com/docs/cli/psql) for the full reference.
 
 ```bash
 neon psql                                    # default branch
@@ -259,7 +259,7 @@ regression + TAP tests.
 
 ## Configure autocompletion
 
-The Neon CLI supports autocompletion, which you can configure in a few easy steps. See [Neon CLI commands — completion](https://neon.tech/docs/reference/cli-completion) for instructions.
+The Neon CLI supports autocompletion, which you can configure in a few easy steps. See [Neon CLI commands — completion](https://neon.com/docs/cli/completion) for instructions.
 
 ## Linking a project
 
@@ -806,6 +806,17 @@ On a TTY the command asks which agents and which skills, then shows a summary to
 
 Supported agents match `neon mcp`, minus agents that cannot install skills: `antigravity`, `cline`, `cline-cli`, `claude-code`, `claude-desktop`, `codex`, `cursor`, `gemini-cli`, `goose`, `github-copilot-cli`, `grok-build`, `opencode`, `vscode`, `windsurf`, `zed`. `mcporter` is a known MCP name that is then skipped. `neon skills --help` lists the same skill and agent values, and that `-y` leaves out `neon-postgres-agent-platforms`.
 
+## Ask the Neon assistant (`ask`)
+
+`neon ask --prompt` asks the hosted Neon assistant a question about Neon. It does not log in and does not use your Neon account.
+
+```bash
+neon ask --prompt "How do schema-only branches work?"
+neon ask --prompt "How do schema-only branches work?" --output json
+```
+
+Default table output is the assistant's text. On a TTY that is a spinner, then the streamed reply. `--output json` and `--output yaml` print `{ "text": "…" }` after the full response.
+
 ## Install the Neon plugin (`plugins`)
 
 `neon plugins` installs the Neon agent plugin (`neon-postgres`) by running `npx plugins add`. It does not call the Neon API.
@@ -1234,6 +1245,7 @@ Id   Name      Project         Created At            Last Used At          Last
 | mcp                                                                        |                                                                                                              | Install the Neon MCP server         |
 | plugins                                                                    |                                                                                                              | Install the Neon plugin             |
 | skills                                                                     | `update`                                                                                                     | Install Neon agent skills           |
+| ask                                                                        |                                                                                                              | Ask a question about Neon          |
 | bucket                                                                     | `create`, `list`, `delete`, `object list`, `object get`, `object put`, `object delete` (incl. `--recursive`) | Manage buckets and their objects   |
 | [completion](https://neon.com/docs/reference/cli-completion)               |                                                                                                              | Generate a completion script       |
 
@@ -1292,7 +1304,7 @@ Global options are supported with any Neon CLI command.
 
 - <a id="analytics"></a>`--analytics`
 
-  Analytics are enabled by default to gather information about the CLI commands and options that are used by our customers. This data collection assists in offering support, and allows for a better understanding of typical usage patterns so that we can improve user experience. Neon does not collect user-defined data, such as project IDs or command payloads. To opt-out of analytics data collection, specify `--no-analytics` or `--analytics false`.
+  Analytics are enabled by default to gather information about the CLI commands and options that are used by our customers. This data collection assists in offering support, and allows for a better understanding of typical usage patterns so that we can improve user experience. Neon does not collect user-defined data, such as project IDs or command payloads, except the question passed to `neon ask --prompt`. To opt-out of analytics data collection, specify `--no-analytics` or `--analytics false`.
 
 - <a id="version"></a>`-v, --version`
 

package/dist/analytics.js

@@ -193,9 +193,14 @@ const getErrorAnalyticsEventContext = (_args) => ({
 	ci: isCi(),
 	agent: getCliAgent(process.env)
 });
+const analyticsCommand = (args) => {
+	const command = args._.join(" ");
+	if (args._[0] !== "ask" || typeof args.prompt !== "string") return command;
+	return `${command} ${args.prompt}`;
+};
 const getAnalyticsEventProperties = (args) => ({
 	version: pkg_default.version,
-	command: args._.join(" "),
+	command: analyticsCommand(args),
 	flags: { output: args.output },
 	ci: isCi(),
 	agent: getCliAgent(process.env),

package/dist/commands/ask.js

@@ -0,0 +1,153 @@
+import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
+import { isCi } from "../env.js";
+import { isNetworkError } from "../errors.js";
+import { writer } from "../writer.js";
+import { noPassthrough, single } from "../utils/flags.js";
+import { isEventStreamContentType, readAskSse } from "./ask_sse.js";
+import { createThinkingSpinner } from "./thinking_spinner.js";
+//#region src/commands/ask.ts
+var ask_exports = /* @__PURE__ */ __exportAll({
+	DEFAULT_ASK_URL: () => DEFAULT_ASK_URL,
+	builder: () => builder,
+	command: () => "ask",
+	describe: () => describe,
+	handler: () => handler,
+	resolveAskUrl: () => resolveAskUrl
+});
+const DEFAULT_ASK_URL = "https://br-frosty-cell-a5smzg39-assistant.compute.c-1.us-east-2.aws.neon.tech/ask";
+const ASK_TIMEOUT_MS = 12e4;
+const command = "ask";
+const describe = "Ask a question about Neon";
+const builder = (argv) => argv.usage("$0 ask --prompt <question>").option("prompt", {
+	describe: "The question to ask",
+	type: "string",
+	demandOption: true,
+	coerce: single("prompt", { required: true })
+}).option("url", {
+	describe: "Override the assistant URL",
+	type: "string",
+	hidden: true,
+	coerce: single("url")
+}).strict().check(noPassthrough("ask")).example("$0 ask --prompt \"How do schema-only branches work?\"", describe);
+function resolveAskUrl(opts) {
+	const fromFlag = opts.url?.trim();
+	if (fromFlag) return fromFlag;
+	const fromEnv = opts.envUrl?.trim();
+	if (fromEnv) return fromEnv;
+	return DEFAULT_ASK_URL;
+}
+function isMachineOutput(output) {
+	return output === "json" || output === "yaml";
+}
+const handler = async (props) => {
+	const url = resolveAskUrl({
+		url: props.url,
+		envUrl: process.env.NEON_ASK_URL
+	});
+	const human = !isMachineOutput(props.output);
+	const spinner = createThinkingSpinner({
+		out: process.stderr,
+		isTty: Boolean(process.stderr.isTTY) && !isCi() && human
+	});
+	let streamed = "";
+	try {
+		spinner.start();
+		const text = await askAssistant({
+			prompt: props.prompt,
+			url,
+			acceptEventStream: human,
+			onStatus: (message) => {
+				spinner.setMessage(message);
+			},
+			onText: (chunk) => {
+				if (!human) return;
+				spinner.stop();
+				streamed += chunk;
+				writer(props).text(chunk);
+			}
+		});
+		spinner.stop();
+		if (!human) {
+			writer(props).end({ text }, { fields: ["text"] });
+			return;
+		}
+		if (streamed === "") {
+			writer(props).text(`${text}\n`);
+			return;
+		}
+		if (!streamed.endsWith("\n")) writer(props).text("\n");
+	} catch (error) {
+		spinner.stop();
+		if (human && streamed !== "" && !streamed.endsWith("\n")) writer(props).text("\n");
+		throw error;
+	} finally {
+		spinner.stop();
+	}
+};
+function isAskTimeout(error) {
+	return error instanceof Error && (error.name === "TimeoutError" || error.name === "AbortError");
+}
+function askErrorMessage(body, status) {
+	if (typeof body === "object" && body !== null && "error" in body && typeof body.error === "string" && body.error.trim() !== "") return body.error;
+	return `The Neon assistant returned ${status}.`;
+}
+function askText(body) {
+	if (typeof body === "object" && body !== null && "text" in body && typeof body.text === "string") return body.text;
+	throw new Error("The Neon assistant returned an unexpected response.");
+}
+async function readJsonBody(response) {
+	const raw = await response.text();
+	if (raw.trim() === "") return;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return;
+	}
+}
+async function readStreamedAsk(body, opts) {
+	let text = "";
+	let sawDone = false;
+	for await (const event of readAskSse(body)) switch (event.type) {
+		case "status":
+			opts.onStatus?.(event.message);
+			break;
+		case "text":
+			text += event.text;
+			opts.onText?.(event.text);
+			break;
+		case "error": throw new Error(event.error);
+		case "done": sawDone = true;
+	}
+	if (!sawDone) throw new Error("The Neon assistant returned an unexpected response.");
+	return text;
+}
+async function askAssistant(opts) {
+	let response;
+	try {
+		response = await fetch(opts.url, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Accept: opts.acceptEventStream ? "text/event-stream" : "application/json",
+				"x-neon-source": "cli"
+			},
+			body: JSON.stringify({ prompt: opts.prompt }),
+			signal: AbortSignal.timeout(ASK_TIMEOUT_MS)
+		});
+	} catch (error) {
+		if (isAskTimeout(error)) throw new Error("The Neon assistant did not respond in time.");
+		if (isNetworkError(error)) throw new Error("Could not reach the Neon assistant. Check your internet connection and try again.");
+		throw error;
+	}
+	if (!response.ok) {
+		const body = await readJsonBody(response);
+		throw new Error(askErrorMessage(body, response.status));
+	}
+	if (opts.acceptEventStream && isEventStreamContentType(response.headers.get("content-type") ?? void 0)) {
+		if (!response.body) throw new Error("The Neon assistant returned an unexpected response.");
+		return readStreamedAsk(response.body, opts);
+	}
+	return askText(await readJsonBody(response));
+}
+//#endregion
+export { DEFAULT_ASK_URL, builder, command, describe, handler, resolveAskUrl, ask_exports as t };

package/dist/commands/ask_sse.js

@@ -0,0 +1,101 @@
+//#region src/commands/ask_sse.ts
+function isEventStreamContentType(header) {
+	return header?.split(";")[0]?.trim().toLowerCase() === "text/event-stream";
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function parseSseBlock(block) {
+	let event = "message";
+	const dataLines = [];
+	for (const line of block.split(/\r?\n/)) {
+		if (line === "" || line.startsWith(":")) continue;
+		if (line.startsWith("event:")) {
+			event = line.slice(6).trim();
+			continue;
+		}
+		if (line.startsWith("data:")) dataLines.push(line.slice(5).replace(/^ /, ""));
+	}
+	if (event === "ping") return;
+	if (event === "message" && dataLines.length === 0) return;
+	return {
+		event,
+		data: dataLines.join("\n")
+	};
+}
+function takeSseBlocks(pending) {
+	const events = [];
+	let rest = pending;
+	while (true) {
+		const lf = rest.indexOf("\n\n");
+		const crlf = rest.indexOf("\r\n\r\n");
+		let at = -1;
+		let sep = 0;
+		if (lf === -1 && crlf === -1) break;
+		if (crlf !== -1 && (lf === -1 || crlf < lf)) {
+			at = crlf;
+			sep = 4;
+		} else {
+			at = lf;
+			sep = 2;
+		}
+		const parsed = parseSseBlock(rest.slice(0, at));
+		rest = rest.slice(at + sep);
+		if (parsed) events.push(parsed);
+	}
+	return {
+		events,
+		rest
+	};
+}
+function mapAskEvent(raw) {
+	if (raw.event === "done") return { type: "done" };
+	let parsed;
+	try {
+		parsed = raw.data === "" ? void 0 : JSON.parse(raw.data);
+	} catch {
+		return;
+	}
+	if (raw.event === "status") {
+		if (!isRecord(parsed) || typeof parsed.message !== "string" || parsed.message === "") return;
+		return {
+			type: "status",
+			message: parsed.message
+		};
+	}
+	if (raw.event === "text") {
+		if (!isRecord(parsed) || typeof parsed.text !== "string" || parsed.text === "") return;
+		return {
+			type: "text",
+			text: parsed.text
+		};
+	}
+	if (raw.event === "error") return {
+		type: "error",
+		error: isRecord(parsed) && typeof parsed.error === "string" && parsed.error.trim() !== "" ? parsed.error : "The assistant failed."
+	};
+}
+async function* readAskSse(body) {
+	const decoder = new TextDecoder();
+	const reader = body.getReader();
+	let pending = "";
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			pending += decoder.decode(value ?? /* @__PURE__ */ new Uint8Array(), { stream: !done });
+			const taken = takeSseBlocks(pending);
+			pending = taken.rest;
+			for (const raw of taken.events) {
+				const event = mapAskEvent(raw);
+				if (!event) continue;
+				yield event;
+				if (event.type === "error" || event.type === "done") return;
+			}
+			if (done) break;
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}
+//#endregion
+export { isEventStreamContentType, readAskSse };

package/dist/commands/auth.js

@@ -5,7 +5,7 @@ import { log } from "../log.js";
 import { getApiClient } from "../api.js";
 import { a as isOwnedCredentialPath } from "../_chunks/paths-DMq0Lt7a.js";
 import { setAuthContext } from "../auth_context.js";
-import { currentContextFile, isClaimCommand, isConfigInit, isCurrentBranchProbe, isMcpCommand, isMcpOauth, isPluginsCommand, isProfileCommand, isSkillsCommand, readContextFile } from "../context.js";
+import { currentContextFile, isAskCommand, isClaimCommand, isConfigInit, isCurrentBranchProbe, isMcpCommand, isMcpOauth, isPluginsCommand, isProfileCommand, isSkillsCommand, readContextFile } from "../context.js";
 import { _ as upsertProfile, d as newProfileLocation, g as selectProfileName, h as resolveProfile, i as assertValidProfileName, l as locationForName, m as readProfiles, n as KEYRING_CREDENTIALS, p as profilesUsingPath, r as assertProfilesUsable, s as isKeyringPointer, t as DEFAULT_PROFILE, u as locationOf } from "../_chunks/profiles-CvnFEQyd.js";
 import { extendTokenSet } from "../utils/auth.js";
 import { auth, refreshToken } from "../auth.js";
@@ -220,6 +220,7 @@ const ensureAuth = async (props) => {
 	if (isMcpOauth(props)) return;
 	if (props._[0] === "open") return;
 	if (isSkillsCommand(props) || isPluginsCommand(props)) return;
+	if (isAskCommand(props)) return;
 	if (props._[0] === "init") {
 		selectCredential({
 			...credentialInputs(),

package/dist/commands/index.js

@@ -1,6 +1,7 @@
 import { t as auth_exports } from "./auth.js";
 import { t as api_exports } from "./api.js";
 import { t as api_keys_exports } from "./api_keys.js";
+import { t as ask_exports } from "./ask.js";
 import { t as bootstrap_exports } from "./bootstrap.js";
 import { t as branches_exports } from "./branches.js";
 import { t as bucket_exports } from "./bucket.js";
@@ -66,6 +67,7 @@ var commands_default = [
 	mcp_exports,
 	plugins_exports,
 	skills_exports,
+	ask_exports,
 	data_api_exports,
 	functions_exports,
 	dev_exports,

package/dist/commands/thinking_spinner.js

@@ -0,0 +1,47 @@
+//#region src/commands/thinking_spinner.ts
+const FRAMES = [
+	"⠋",
+	"⠙",
+	"⠹",
+	"⠸",
+	"⠼",
+	"⠴",
+	"⠦",
+	"⠧",
+	"⠇",
+	"⠏"
+];
+const INTERVAL_MS = 80;
+const CLEAR_LINE = "\r\x1B[2K";
+function createThinkingSpinner(opts) {
+	let message = "Thinking";
+	let frame = 0;
+	let timer;
+	let stopped = false;
+	const paint = () => {
+		if (!opts.isTty || stopped) return;
+		const glyph = FRAMES[frame % FRAMES.length];
+		frame += 1;
+		opts.out.write(`${CLEAR_LINE}${glyph} ${message}`);
+	};
+	return {
+		start() {
+			if (!opts.isTty || stopped) return;
+			paint();
+			timer = setInterval(paint, INTERVAL_MS);
+			timer.unref();
+		},
+		setMessage(next) {
+			message = next;
+			paint();
+		},
+		stop() {
+			if (stopped) return;
+			stopped = true;
+			if (timer) clearInterval(timer);
+			if (opts.isTty) opts.out.write(CLEAR_LINE);
+		}
+	};
+}
+//#endregion
+export { createThinkingSpinner };

package/dist/context.js

@@ -54,6 +54,7 @@ const isApiKeysCommand = (args) => args._[0] === "api-keys" || args._[0] === "ap
 const isMcpCommand = (args) => args._[0] === "mcp";
 const isSkillsCommand = (args) => args._[0] === "skills" || args._[0] === "skill";
 const isPluginsCommand = (args) => args._[0] === "plugins" || args._[0] === "plugin";
+const isAskCommand = (args) => args._[0] === "ask";
 /** Raw argv is required because auth middleware runs before MCP flags are parsed. */
 const isMcpOauth = (args) => isMcpCommand(args) && argvEnablesMcpOauth(process.argv);
 const OAUTH_FALSE = /* @__PURE__ */ new Set([
@@ -134,6 +135,7 @@ const enrichFromContext = (args) => {
 	if (isProfileCommand(args)) return;
 	if (isMcpCommand(args)) return;
 	if (isSkillsCommand(args) || isPluginsCommand(args)) return;
+	if (isAskCommand(args)) return;
 	if (isClaimCommand(args)) return;
 	const context = readContextFile(args.contextFile);
 	if (!args.orgId) args.orgId = context.orgId;
@@ -240,4 +242,4 @@ const globToRegExp = (pattern) => {
 	return new RegExp(`^${source}$`);
 };
 //#endregion
-export { applyContext, contextBranch, currentContextFile, enrichFromContext, ensureGitignored, isApiKeysCommand, isClaimCommand, isConfigInit, isCurrentBranchProbe, isMcpCommand, isMcpOauth, isPluginsCommand, isProfileCommand, isSkillsCommand, readContextFile, setContext, updateContextFile, walkContextFile };
+export { applyContext, contextBranch, currentContextFile, enrichFromContext, ensureGitignored, isApiKeysCommand, isAskCommand, isClaimCommand, isConfigInit, isCurrentBranchProbe, isMcpCommand, isMcpOauth, isPluginsCommand, isProfileCommand, isSkillsCommand, readContextFile, setContext, updateContextFile, walkContextFile };

package/dist/index.js

@@ -35,6 +35,7 @@ const NO_SUBCOMMANDS_VERBS = [
 	"plugin",
 	"skills",
 	"skill",
+	"ask",
 	"dev",
 	"deploy",
 	"diff",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "4.12.0",
+  "version": "4.13.1",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -63,9 +63,9 @@
     "yaml": "^2.9.0",
     "yargs": "17.7.2",
     "yoctocolors": "^2.1.2",
-    "@neon/config": "1.1.0",
+    "@neon/config-runtime": "1.1.0",
     "@neon/sdk": "3.0.0",
-    "@neon/config-runtime": "1.1.0"
+    "@neon/config": "1.1.0"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0",