neon 4.22.0 → 5.0.1

package/README.md

@@ -298,15 +298,15 @@ The Neon CLI supports autocompletion, which you can configure in a few easy step
 
 ## Linking a project
 
-`neon link` is a Vercel-style command that binds the current directory to a Neon project. It picks (or creates) an organization and a project and writes a `.neon` file (`{ "orgId", "projectId", "branch" }`) that subsequent commands run in this directory (or any sub-directory) pick up automatically.
+`neon link` is a Vercel-style command that binds the current directory to a Neon project. It picks (or creates) an organization and a project and writes a `.neon` file (`{ "orgId", "projectId", "branch" }`) that subsequent commands run in this directory (or any sub-directory) pick up automatically. Personal-account projects omit `orgId`.
 
-`link` resolves what it can and **verifies every identifier you pass** before writing, so a `.neon` is never left half-written or pointing at something that doesn't exist:
+`link` resolves what it can and **verifies every identifier you pass** before writing, so a successful `.neon` always has a project and a branch (and an organization when the project has one):
 
-- **org** is inferred from the project (so `--project-id` alone is enough); it's omitted only when the project has no organization (personal account).
-- **project** is taken from `--project-id` (or chosen interactively).
-- **branch** is taken from `--branch`, an existing pin for the same project, or the project's branch list: one branch is pinned automatically; several prompt in a TTY, pin the default with `-y`, or stay unpinned for [`neon checkout <branch>`](#checkout). A project with no branches is linked without a pin and says so.
+- **org** is inferred from the project (so `--project-id` alone is enough); it's omitted only when the project has no organization (personal account). `--org-id` that the project does not confirm is an error.
+- **project** is taken from `--project-id` (or chosen interactively). `--org-id` without a project opens the project picker in a TTY. Without a TTY it needs `-y` (select the only project, or print IDs) or `--project-id`.
+- **branch** is taken from `--branch`, a still-valid pin for the same project, or the project's branch list: one branch is pinned automatically; several prompt in a TTY, or `-y` pins the default. Zero branches, a stale pin, or several branches with no TTY and no `-y` fail without writing.
 
-When a branch ends up pinned, `link` also runs [`env pull`](#env-pull) so the branch's Neon env vars (`DATABASE_URL`, …) land in a local `.env`. With no branch pinned there is nothing to pull, so `link` instead nudges you to run `neon checkout`. Pass `--no-env-pull` to skip the pull (for example when injecting env at runtime with `neon-env run` or `neon dev`).
+When a branch is pinned, `link` also runs [`env pull`](#env-pull) so the branch's Neon env vars (`DATABASE_URL`, …) land in a local `.env`. Pass `--no-env-pull` to skip the pull (for example when injecting env at runtime with `neon-env run` or `neon dev`).
 
 > **Migrating from `set-context`?** `set-context` is **deprecated** in favor of `link` (see [below](#set-context-is-deprecated)). It still works exactly as before for now (a raw write), it just prints a deprecation warning. The `.neon` `branchId` field is also superseded by `branch` (which stores the branch **name** when known); old `branchId` files are still read and are upgraded to `branch` the next time `link`/`checkout` writes the context.
 
@@ -339,19 +339,24 @@ $ neon link
 ```
 
 `link --project-id …` skips org and project. One branch is pinned with no prompt. Several branches
-in a TTY show the branch prompt; `-y` pins the default; no TTY leaves the pin empty for
-`neon checkout`:
+in a TTY show the branch prompt; `-y` pins the default; no TTY without `-y` or `--branch` exits 1:
 
 ```bash
 $ neon link --project-id polished-snowflake-12345678
 ? Which branch would you like to link? › [default] main (br-main-branch-87654321)
 ```
 
-**Non-interactive (flags or `--params` JSON)** — for scripts and CI:
+**Non-interactive (`-y`, flags, or `--params` JSON)** — for scripts, CI, and agents:
 
 ```bash
+# One organization and one project: link them. Several: print IDs and exit 1.
+neon link -y
+
+# After choosing an organization from that list, discover its project the same way
+neon link -y --org-id org-abc123
+
 # Link to an existing project (org is inferred). Pins the only branch;
-# several branches prompt in a TTY, or stay unpinned without one.
+# several branches prompt in a TTY, or -y pins the default.
 neon link --project-id polished-snowflake-12345678
 
 # Same, pin the project's default branch when several exist
@@ -369,21 +374,21 @@ neon link --org-id org-abc123 --project-name my-app --region-id aws-us-east-2
 # Same payload, one JSON blob
 neon link --params '{"orgId":"org-abc123","projectName":"my-app","regionId":"aws-us-east-2"}'
 
-# Record just the default org (preserves any existing project/branch)
-neon link --org-id org-abc123
-
 # Forget the current context
 neon link --clear
 
 # Offline write — no API calls, no verification (see --no-checks below)
-neon link --no-checks --org-id org-abc123 --project-id polished-snowflake-12345678
+neon link --no-checks --org-id org-abc123 --project-id polished-snowflake-12345678 --branch main
 ```
 
 Every supplied identifier is checked before anything is written, with actionable errors — e.g. `Project '…' not found`, `You don't have access to project '…'`, `Organization '…' not found, or your API key doesn't have access to it`, `Project '…' belongs to organization 'A', not 'B'`, or `Branch '…' not found in project '…'. Available branches: …`.
 
-**Agents and scripts (no TTY):** List, then link. `neon link --help` prints the same recipe.
+**Agents and scripts:** `neon link -y` selects the only organization and project. If several exist, it prints their IDs (human table, or `--output json` / `--output yaml`) and names the flag to pass. `--org-id` alone, without `-y` and without a TTY, is not a completed link — pass `--project-id` or `-y`. `neon link --help` prints the explicit-flag recipe.
 
 ```bash
+neon link -y
+neon link -y --org-id <org-id>
+neon link -y --project-id <project-id>
 neon orgs list --output json
 neon projects list --org-id <org-id> --output json
 neon link --project-id <project-id> [--branch <name> | -y]
@@ -397,7 +402,7 @@ Organization-scoped API keys cannot list user organizations (`orgs list`) or cal
 - If no projects exist yet, interactive `link` errors pointing at `--org-id`.
 - When the regions endpoint is not allowed, interactive create falls back to a built-in static region list. Non-interactive create already requires `--region-id`.
 
-**Offline writes (`--no-checks`)** — write the `.neon` with no API calls at all: no org inference, no existence/access verification, no env pull. Because nothing can be resolved offline, it requires both `--org-id` and `--project-id` (`--branch` optional, stored verbatim). Handy for scripted/CI setups or re-creating a `.neon` from values you already trust:
+**Offline writes (`--no-checks`)** — write the `.neon` with no API calls at all: no org inference, no existence/access verification, no env pull. Because nothing can be resolved offline, it requires `--org-id`, `--project-id`, and `--branch` (stored verbatim). Handy for scripted/CI setups or re-creating a `.neon` from values you already trust:
 
 ```bash
 neon link --no-checks --org-id org-abc123 --project-id polished-snowflake-12345678 --branch main
@@ -411,13 +416,13 @@ How today's `set-context` uses map onto `link`:
 
 | `set-context` (deprecated)              | Recommended `link` equivalent                                                 |
 | --------------------------------------- | ----------------------------------------------------------------------------- |
-| `neon set-context --project-id <id>` | `neon link --project-id <id>` (infers org + verifies; pins the only branch) |
-| `neon set-context --org-id <id>`     | `neon link --org-id <id>`                                                  |
-| `neon set-context --branch-id <id>`  | `neon link --branch <name\|id>`                                            |
+| `neon set-context --project-id <id>` | `neon link --project-id <id>` (infers org + verifies; pins the only branch, or `-y` for the default) |
+| `neon set-context --org-id <id>`     | Not a completed link. Pass `--project-id` / `-y`, or an `--org-id` flag on the org-scoped command |
+| `neon set-context --branch-id <id>`  | `neon link --branch <name\|id>` or [`neon checkout <branch>`](#checkout)   |
 | `neon set-context` (clear)           | `neon link --clear`                                                        |
-| a raw local write (no network)          | `neon link --no-checks --org-id <id> --project-id <id>`                    |
+| a raw local write (no network)          | `neon link --no-checks --org-id <id> --project-id <id> --branch <name>`    |
 
-The key difference: `link` resolves and **verifies** before writing (so you never get a half-written or stale `.neon`), whereas `set-context` writes whatever you give it verbatim. The closest like-for-like replacement for the old raw write is `link --no-checks`.
+The key difference: `link` resolves and **verifies** before writing a complete context, whereas `set-context` writes whatever you give it verbatim. The closest like-for-like replacement for the old raw write is `link --no-checks` with org, project, and branch.
 
 ### open
 
@@ -434,7 +439,7 @@ A branch pinned in `.neon` does not change the destination. `.neon` stores the b
 
 ### checkout
 
-`checkout [id|name]` pins a branch in the local context so subsequent commands target it — it's the focused companion to `link` for the common "switch the branch I'm working on" case (`link` resolves org + project; `checkout` pins the branch). It resolves the branch (by name or id) against the project, then **heals** the `.neon` file: it always (re)writes `projectId`, `branch`, and `orgId` (when the project has one), so a `.neon` that was missing fields or drifted ends up complete and consistent. The branch is stored as its **name** when known (matching `link`). When `orgId` isn't already known (from `--org-id` or the existing `.neon`), it's looked up from the project itself.
+`checkout [id|name]` switches the pinned branch in a linked folder. It resolves the branch (by name or id) against the project, then **heals** the `.neon` file: it always (re)writes `projectId`, `branch`, and `orgId` (when the project has one), so a `.neon` that was missing fields or drifted ends up complete and consistent. The branch is stored as its **name** when known (matching `link`). When `orgId` isn't already known (from `--org-id` or the existing `.neon`), it's looked up from the project itself.
 
 The branch argument is **optional**: run `neon checkout` with no branch in an interactive terminal to fetch the project's branches and pick one from a list. In a non-interactive context (CI or no TTY), a branch must be passed explicitly.
 
@@ -749,7 +754,7 @@ When a package cannot be bundled — a native addon with no esbuild loader, or a
 
 `neon bootstrap` copies a Neon starter template into a new (or current) directory — conceptually like `degit`, but it only pulls from a small set of templates we maintain in the public [`neondatabase/examples`](https://github.com/neondatabase/examples) repo. The template copy needs no Neon login: it downloads files from GitHub.
 
-After scaffolding, an interactive terminal asks about dependency install and git, then finishes agent setup before asking whether to link a Neon project. Dependency install is last, except when the template has a `neon.ts` and you chose to link — then install runs first so the link flow can pull env. `--default` / `-y` skips the template, install, git, and agent pickers, then installs agent tooling for project folders, else the host CLI agent. If none are found, it exits: pass `--agent <name>`, run from a supported agent, or omit `--default` / `-y` in a terminal to pick. `--agent` / `-a` names coding agents, skips agent selection, and is forwarded to `plugins`, or to `skills` and `mcp`, not both. Project selection may still be required. `--no-agent-setup` and `--no-link` skip those steps. Non-interactive without `--default` prints next steps and does not install, set up agents, or link.
+After scaffolding, an interactive terminal asks about dependency install and git, then finishes agent setup before asking whether to link a Neon project. Dependency install is last, except when the template has a `neon.ts` and you chose to link — then install runs first so the link flow can pull env. `--default` / `-y` skips the template, install, git, and agent pickers, then installs agent tooling for project folders, else the host CLI agent. If none are found, it exits: pass `--agent <name>`, run from a supported agent, or omit `--default` / `-y` in a terminal to pick. `--agent` / `-a` names coding agents, skips agent selection, and is forwarded to `plugins`, or to `skills` and `mcp`, not both. Linking uses `neon link -y`: the only organization and project are selected, or their IDs are printed and the command exits. `--no-agent-setup` and `--no-link` skip those steps. Non-interactive without `--default` prints next steps and does not install, set up agents, or link.
 
 Pass a target directory (or `.` for the current one). In an interactive terminal you pick the template from a list; in CI / non-interactive contexts pass `--template <id>`.
 
@@ -802,7 +807,7 @@ Without a TTY, pass `-y`. `--agent` skips agent selection but does not replace `
 
 `--config`, `--no-config`, and `--services` apply on the existing-app and `--skip-template` path. A template's own `neon.ts` is left as the template shipped it. Passing those flags while scaffolding prints a warning and still copies the template as shipped. After a new `neon.ts` on a pinned branch, init runs `env pull`.
 
-`-y` forwards `-y` to `plugins` or `skills`/`mcp`, uses default choices in the built-in link flow, passes `--default` to nested bootstrap, and forwards `--services none` to `config init`. `--agent` is forwarded to agent setup. `mcp -y` is the global install. Default linking skips the "already linked" confirmation; it can still require project selection.
+`-y` forwards `-y` to `plugins` or `skills`/`mcp`, uses `link -y` (auto-select or print IDs and exit), passes `--default` to nested bootstrap, and forwards `--services none` to `config init`. `--agent` is forwarded to agent setup. `mcp -y` is the global install. Default linking skips the "already linked" confirmation.
 
 A failed step stops the rest. `--profile` and `--config-dir` are forwarded to each child. `--output json` and `--output yaml` are refused; the commands init runs print their own output.
 
@@ -1015,7 +1020,7 @@ neon inspect db stalled-queries --output json
 
 ## Logs (`logs`)
 
-`neon logs` reads the log records the services on a branch emit — Neon Functions, object storage, and Postgres computes. **Logs require Neon Platform Beta and are currently available only for projects in `aws-us-east-2`, `aws-us-east-1`, `aws-eu-central-1`, and `aws-ap-southeast-1`.**
+`neon logs` reads the log records the services on a branch emit — Neon Functions, object storage, and Postgres computes. **Logs are currently available only for projects in `aws-us-east-2`, `aws-us-east-1`, `aws-eu-central-1`, and `aws-ap-southeast-1`.**
 
 Every sub-command resolves the project through the standard chain (`--project-id`, then the `.neon` context file, then a single-project auto-detect), and takes `--branch <id|name>`, defaulting to the project's default branch. `logs query` searches the previous hour by default; `logs field-values` searches the previous six hours. The maximum time window is seven days.
 

package/dist/commands/auth.js

@@ -14,6 +14,8 @@ import { ClaimableClient, ClaimableServiceError } from "../claimable/api.js";
 import { assertionHasExpired, claimableCredentialsExist, claimableCredentialsPath, readLinkedClaimableCredentials, shouldUseClaimableCredentials } from "../claimable/state.js";
 import { withExclusiveLock } from "../refresh_lock.js";
 import { readOutgoingCredential, retirePreviousCredential } from "../retire_credential.js";
+import { getCliName } from "../utils/cli_name.js";
+import { helpEpilogue, helpWidth, wrapHelpText } from "../utils/help_text.js";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { createHash } from "node:crypto";
@@ -45,11 +47,16 @@ const locationForAuth = (configDir, name, keyring, options = {}) => {
 };
 const command = "auth";
 const aliases = ["login"];
-const describe = "Authenticate";
+const describe = "Sign in with a browser. See --help for API keys and profiles";
+const wrapAuthHelp = (text) => wrapHelpText(text, helpWidth());
+const authHelpEpilogue = () => {
+	const cli = getCliName();
+	return helpEpilogue(wrapAuthHelp("Non-interactive (CI, scripts, agents):"), wrapAuthHelp("Use an existing API key or an API-key profile."), `  ${cli} projects list --profile agent`, wrapAuthHelp(`${cli} profile create <name> --mint needs a browser during setup, then stores an API key and drops the session. It cannot run in CI. Default key is account-wide; --org-id or --project-id (not both) restricts it.`), wrapAuthHelp(`A profile holds a browser session or an API key. Select it with --profile <name> or NEON_PROFILE. List profiles with ${cli} profile list.`), wrapAuthHelp("On commands that use a credential, --api-key or --profile overrides NEON_API_KEY and NEON_PROFILE. Pass either --api-key or --profile, not both. When neither flag is passed and both NEON_API_KEY and NEON_PROFILE are set, the key wins and stderr names the ignored profile. When no flag or environment variable selects a credential, DEFAULT is used."), wrapAuthHelp(`${cli} profile create <name> replaces an existing profile of that name and tries to revoke the credential it held. An imported key with no recorded id stays live. Pick a new name to keep the old profile.`), wrapAuthHelp(`See ${cli} profile --help and ${cli} profile create --help.`));
+};
 const builder = (yargs) => yargs.option("context-file", { hidden: true }).option("keyring", {
 	describe: "Store the credential in the OS keyring. Per profile; later auth without the flag stays there. See `neon profile list`.",
 	type: "boolean"
-});
+}).example("$0 auth", "Sign in with a browser").example("$0 auth --profile work", "Save a browser session in profile work").example("$0 projects list --api-key \"$KEY\"", "Use an existing API key for this command").example("NEON_API_KEY=\"$KEY\" $0 projects list", "Use an existing API key from the environment").example("$0 profile create agent --api-key \"$KEY\"", "Store an existing API key").example("echo \"$KEY\" | $0 profile create agent --api-key -", "Store a key read from stdin").example("$0 profile create ci --mint", "Sign in once in a browser and store a new API key").epilogue(authHelpEpilogue());
 const handler = async (args) => {
 	await authFlow(args);
 };

package/dist/commands/bootstrap.js

@@ -49,7 +49,7 @@ const builder = (argv) => argv.usage("$0 bootstrap [directory] [options]").posit
 	},
 	default: {
 		alias: "y",
-		describe: "Quick start: scaffold the default template (or --template), then install, git, agent tooling (project folders, else the host CLI agent; if none, pass --agent or omit --default in a terminal), and link with defaults. Project selection may still be required",
+		describe: "Quick start: scaffold the default template (or --template), then install, git, agent tooling (project folders, else the host CLI agent; if none, pass --agent or omit --default in a terminal), and link with defaults. If several organizations or projects exist, link prints IDs and exits",
 		type: "boolean",
 		default: false
 	},
@@ -80,7 +80,7 @@ const builder = (argv) => argv.usage("$0 bootstrap [directory] [options]").posit
 		describe: "Coding agent to install into (repeatable). Forwarded to plugins, or to skills and mcp. Skips agent selection. Values listed below",
 		coerce: coerceAgentFlag
 	}
-}).example("$0 bootstrap my-app", "Create ./my-app from an interactively chosen template").example("$0 bootstrap . --template hono", "Scaffold the Hono template into the current directory").example("$0 bootstrap my-app --default", "Skip the pickers; project selection may still be required").example("$0 bootstrap --list-templates --output json", "Print the template catalog as JSON").example("$0 bootstrap my-app --agent cursor --agent claude-code", "Skip agent selection; install the plugin for those agents").epilogue(helpEpilogue("--agent / -a is forwarded to plugins, or to skills and mcp, not both. It skips agent selection, including with --default.", helpCsv("Plugin agents", initPluginAgents()), helpCsv("Skills and MCP agents", initSkillsMcpAgents()))).strict();
+}).example("$0 bootstrap my-app", "Create ./my-app from an interactively chosen template").example("$0 bootstrap . --template hono", "Scaffold the Hono template into the current directory").example("$0 bootstrap my-app --default", "Skip the pickers; if several orgs or projects exist, link prints IDs and exits").example("$0 bootstrap --list-templates --output json", "Print the template catalog as JSON").example("$0 bootstrap my-app --agent cursor --agent claude-code", "Skip agent selection; install the plugin for those agents").epilogue(helpEpilogue("--agent / -a is forwarded to plugins, or to skills and mcp, not both. It skips agent selection, including with --default.", helpCsv("Plugin agents", initPluginAgents()), helpCsv("Skills and MCP agents", initSkillsMcpAgents()))).strict();
 const handler = async (props) => {
 	if (props.listTemplates) {
 		const templates = await fetchTemplates();
@@ -244,7 +244,7 @@ const runPostScaffoldSteps = async (props, targetDir, interactive, template, nam
 };
 const installPrompt = (inferred) => inferred ? `Install dependencies with ${inferred}?` : "Install dependencies?";
 const runDefaultSteps = async (props, targetDir, pm, neonConfig, template, named) => {
-	log.info("Quick start (--default): skipping the template, install, git, and agent pickers. Project selection may still be required.");
+	log.info("Quick start (--default): skipping the template, install, git, and agent pickers. If several organizations or projects exist, link prints IDs and exits.");
 	const wantGit = props.git && !isGitRepo(targetDir);
 	const agentSetup = props.agentSetup === false ? "skip" : named.length > 0 ? chooseYesAgentTooling(named).setup : "skills-mcp";
 	const outcome = await executePostScaffold(props, targetDir, {

package/dist/commands/checkout.js

@@ -6,7 +6,7 @@ import { applyContext, contextBranch, readContextFile } from "../context.js";
 import { getCliName } from "../utils/cli_name.js";
 import { createBranch, pickBranchInteractively } from "../utils/branch_picker.js";
 import { looksLikeBranchId } from "../utils/formats.js";
-import { fillSingleProject } from "../utils/enrichers.js";
+import { fillSingleProject, listAllProjectBranches } from "../utils/enrichers.js";
 import { autoPullEnvAfterPin } from "./env.js";
 import { applyPolicyOnCreate, createBranchFromPolicyOnCheckout, envFlag } from "./config.js";
 import { handler as handler$1 } from "./link.js";
@@ -110,7 +110,7 @@ const applyPolicyOrDescribeFailure = async (props) => {
 	}
 };
 const resolveBranchId = async (props, projectId) => {
-	const branches = (await props.apiClient.listProjectBranches({ projectId })).data.branches;
+	const branches = await listAllProjectBranches(props.apiClient, projectId);
 	if (!props.id) {
 		const picked = await pickBranchInteractively(branches, {
 			message: "Which branch would you like to check out?",

package/dist/commands/config.js

@@ -10,10 +10,10 @@ import { deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOpt
 import { CONFIG_INIT_NONE_MEANS, CONFIG_INIT_SERVICES, CONFIG_INIT_UNAVAILABLE, FUNCTION_FILENAME, FUNCTION_SLUG, FUNCTION_TEMPLATE, REQUIRED_PACKAGES, renderNeonConfig, renderNeonConfigFromView } from "../config_template.js";
 import { loadEnvFileIntoProcess } from "../env_file.js";
 import { writer } from "../writer.js";
+import { 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 { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
 import { formatInstallCommand, installArgs, resolvePackageManager, runCommand } from "../utils/package_manager.js";
 import { bundleEntry } from "../utils/esbuild.js";
 import { pickServicesInteractively } from "../utils/service_picker.js";
@@ -21,8 +21,8 @@ import { zipBundle } from "../utils/zip.js";
 import { autoPullEnvAfterPin } from "./env.js";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { packagesToStage, previewGaWarningForConfig, resolveConfig } from "@neon/config";
 import chalk from "chalk";
+import { packagesToStage, previewGaWarningForConfig, resolveConfig } from "@neon/config";
 import { PushConflictError, apply, assertZipWithinLimits, bundleAsIs, createBranch, describeNativeFinding, enforceLimits, findUndeclaredNativePackages, inspect, isPartialBranchCreateError, loadConfigFromFile as loadConfigFromFile$1, plan, resolveEsbuildEntry, traceNativePackages, zipFunctionBundle } from "@neon/config-runtime";
 //#region src/commands/config.ts
 var config_exports = /* @__PURE__ */ __exportAll({

package/dist/commands/diff.js

@@ -3,7 +3,7 @@ import { log } from "../log.js";
 import { isNeonApiError } from "../api.js";
 import { writer } from "../writer.js";
 import { looksLikeBranchId } from "../utils/formats.js";
-import { fillSingleProject } from "../utils/enrichers.js";
+import { fillSingleProject, listAllProjectBranches } from "../utils/enrichers.js";
 import { renderDatabaseSchemaDiff, renderSchemaDiffReport } from "../utils/git_diff.js";
 import chalk from "chalk";
 //#region src/commands/diff.ts
@@ -43,7 +43,7 @@ const builder = (argv) => argv.usage("$0 diff [compare-branch] [options]").posit
 	["$0 diff main --db neondb", "Diff only the neondb database against main"]
 ]);
 const handler = async (props) => {
-	const branches = (await props.apiClient.listProjectBranches({ projectId: props.projectId })).data.branches;
+	const branches = await listAllProjectBranches(props.apiClient, props.projectId);
 	const after = resolveAfterBranch(branches, props.branch);
 	const before = resolveBeforeBranch(branches, after, props.compareBranch);
 	if (before.branchId === after.branchId) throw new Error(`Nothing to compare: both sides resolve to branch ${after.branchName} (${after.branchId}).`);

package/dist/commands/env.js

@@ -6,9 +6,9 @@ import { getCliName } from "../utils/cli_name.js";
 import { deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOption } from "../neon_services.js";
 import { mergeEnvFile, readEnvFile, resolveEnvFilePath } from "../env_file.js";
 import { a as envKeysForSelection, b as isFunctionBaseUrlKey, c as ownedEnvServiceKeys, f as NEON_ENV_VAR_KEYS, i as ENV_PULL_SERVICES, l as parseEnvPullKeys, o as envPullFlagValue, r as ENV_PULL_KEY_HELP } from "../_chunks/env_services-DlXECBPi.js";
+import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
 import { warnAiGateway } from "../utils/ai_gateway_notice.js";
 import { announceTargetBranch } from "../utils/branch_notice.js";
-import { fillSingleProject, resolveBranchRef } from "../utils/enrichers.js";
 import { i as dropClaimableUnsupported, o as resolveNeonEnvVars } from "../_chunks/env-DRpFX-_d.js";
 import { existsSync } from "node:fs";
 import chalk from "chalk";

package/dist/commands/init.js

@@ -4,9 +4,9 @@ import { contextBranch, readContextFile } from "../context.js";
 import { recordCommandSuccessExtras } 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 { deprecatedServiceMessage, parseServices, servicesFlagValue, servicesOption } from "../neon_services.js";
 import { CONFIG_INIT_NONE_MEANS, CONFIG_INIT_SERVICES, CONFIG_INIT_UNAVAILABLE } from "../config_template.js";
-import { helpCsv, helpEpilogue } from "../utils/help_text.js";
 import { fetchTemplates } from "../init/bootstrap.js";
 import { initChildEnv, spawnCliChild } from "../init/child.js";
 import { agentSetupLabel, configSummaryLabel, formatInitDone, printInitBanner, printInitDone, shouldPrintInitBanner } from "../init/chrome.js";
@@ -36,7 +36,7 @@ const builder = (yargs) => yargs.usage("$0 init [options]").option("context-file
 	alias: "y",
 	type: "boolean",
 	default: false,
-	describe: "Empty dir: scaffold the default template. --skip-template: plugin, or skills and MCP, for project folders, else the host CLI agent. Exits if none. Then link with defaults and create the bare neon.ts policy. Project selection may still be required"
+	describe: "Empty dir: scaffold the default template. --skip-template: plugin, or skills and MCP, for project folders, else the host CLI agent. Exits if none. Then link with defaults and create the bare neon.ts policy. If several organizations or projects exist, link prints IDs and exits"
 }).option("skip-template", {
 	type: "boolean",
 	default: false,
@@ -86,7 +86,7 @@ const builder = (yargs) => yargs.usage("$0 init [options]").option("context-file
 	alias: "o",
 	hidden: true,
 	describe: "Not supported; the commands init runs print their own output"
-}).example("$0 init", "Set up this directory (template picker if empty)").example("$0 init --skip-template", "Empty dir: agents, link, and neon.ts — no template files").example("$0 init -y", "Default template, or existing-app defaults").example("$0 init --agent cursor --agent claude-code", "Skip agent selection; install the plugin for those agents").epilogue(helpEpilogue("Empty directory: pick a starter template, or skip scaffolding and only set up agents, a Neon project, and neon.ts. That skip is not on `neon bootstrap`.", "Interactive agent setup: plugin (recommended), skills and MCP separately, or skip agent setup. Never both plugin and skills+MCP.", "neon.ts is optional when you skip the template or set up an existing app. Saying no skips the services picker and does not write the file. Scaffolding a template keeps that template's neon.ts.", "-y installs the plugin when Cursor, Claude Code, or Codex is in project folders, else the host CLI agent. Otherwise skills and MCP. If none are found, it exits: pass --agent <name>, run from a supported agent, or omit -y in a terminal to pick. Then link unless already linked. Project selection may still be required.", "--agent / -a is forwarded to plugins, or to skills and mcp, not both. It skips agent selection, including with -y.", helpCsv("Plugin agents", initPluginAgents()), helpCsv("Skills and MCP agents", initSkillsMcpAgents()))).check((argv) => {
+}).example("$0 init", "Set up this directory (template picker if empty)").example("$0 init --skip-template", "Empty dir: agents, link, and neon.ts — no template files").example("$0 init -y", "Default template, or existing-app defaults").example("$0 init --agent cursor --agent claude-code", "Skip agent selection; install the plugin for those agents").epilogue(helpEpilogue("Empty directory: pick a starter template, or skip scaffolding and only set up agents, a Neon project, and neon.ts. That skip is not on `neon bootstrap`.", "Interactive agent setup: plugin (recommended), skills and MCP separately, or skip agent setup. Never both plugin and skills+MCP.", "neon.ts is optional when you skip the template or set up an existing app. Saying no skips the services picker and does not write the file. Scaffolding a template keeps that template's neon.ts.", "-y installs the plugin when Cursor, Claude Code, or Codex is in project folders, else the host CLI agent. Otherwise skills and MCP. If none are found, it exits: pass --agent <name>, run from a supported agent, or omit -y in a terminal to pick. Then link unless already linked. If several organizations or projects exist, link prints IDs and exits.", "--agent / -a is forwarded to plugins, or to skills and mcp, not both. It skips agent selection, including with -y.", helpCsv("Plugin agents", initPluginAgents()), helpCsv("Skills and MCP agents", initSkillsMcpAgents()))).check((argv) => {
 	if (argv.data !== void 0) throw new Error(removedProtocol());
 	if (argv.help !== true && (argv.output === "json" || argv.output === "yaml")) throw new Error(`\`${getCliName()} init\` does not support --output. The commands it runs print their own output.`);
 	return true;

package/dist/commands/link.js

@@ -2,10 +2,15 @@ import { t as __exportAll } from "../_chunks/rolldown-runtime-8H4AJuhK.js";
 import { isCi } from "../env.js";
 import { log } from "../log.js";
 import { isNeonApiError, messageFromBody } from "../api.js";
+import { r as defaultDir } from "../_chunks/paths-DMq0Lt7a.js";
+import "../config.js";
 import { applyContext, contextBranch, readContextFile, setContext, updateContextFile } from "../context.js";
 import { getCliName } from "../utils/cli_name.js";
 import { helpEpilogue } from "../utils/help_text.js";
+import { writer } from "../writer.js";
 import { createBranch, pickBranchInteractively } from "../utils/branch_picker.js";
+import { looksLikeBranchId } from "../utils/formats.js";
+import { listAllProjectBranches } from "../utils/enrichers.js";
 import { autoPullEnvAfterPin } from "./env.js";
 import { hasNeonConfigFile, initCmd } from "./config.js";
 import { REGIONS } from "./projects.js";
@@ -25,6 +30,7 @@ const canPromptInteractively = () => !isCi() && Boolean(process.stdin.isTTY) &&
 const nonInteractiveLinkCommands = () => {
 	const cli = getCliName();
 	return [
+		`${cli} link -y`,
 		`${cli} orgs list --output json`,
 		`${cli} projects list --org-id <org-id> --output json`,
 		`${cli} link --project-id <project-id> [--branch <name> | -y]`,
@@ -63,7 +69,7 @@ const builder = (argv) => argv.usage("$0 link [options]").options({
 	},
 	yes: {
 		alias: "y",
-		describe: "Skip the \"already linked\" confirmation, and pin the project's default branch when linking a project that has more than one.",
+		describe: "Skip prompts. Select the only organization and project, or print IDs and the flag to pass. Pin the default branch when several exist. Does not create a project unless --project-name and --region-id are set.",
 		type: "boolean",
 		default: false
 	},
@@ -73,7 +79,7 @@ const builder = (argv) => argv.usage("$0 link [options]").options({
 		default: false
 	},
 	checks: {
-		describe: "Verify the org/project/branch exist (and resolve the org from the project) before writing. On by default; use --no-checks to write the context offline with no API calls — it then requires --org-id and --project-id (--branch optional) and skips env pull.",
+		describe: "Verify the org/project/branch exist (and resolve the org from the project) before writing. On by default; use --no-checks to write the context offline with no API calls — it then requires --org-id, --project-id, and --branch, and skips env pull.",
 		type: "boolean",
 		default: true
 	},
@@ -88,11 +94,12 @@ const builder = (argv) => argv.usage("$0 link [options]").options({
 		default: true
 	}
 }).example([
-	["$0 link --project-id polished-snowflake-12345678", "Link an existing project (org is inferred). Pins the only branch; several prompt in a TTY"],
+	["$0 link -y", "Select the only organization and project, or print the --org-id / --project-id to pass"],
+	["$0 link --project-id polished-snowflake-12345678", "Link an existing project (org is inferred). Pins the only branch; several prompt in a TTY, or -y pins the default"],
 	["$0 link --project-id polished-snowflake-12345678 -y", "Same, pinning the project's default branch when several exist"],
 	["$0 link --org-id org-… --project-name my-app --region-id aws-us-east-2", "Create a new project and link it"],
 	["$0 link --branch-id br-…", "Pin a branch in the already-linked project"],
-	["$0 link --no-checks --org-id org-… --project-id polished-snowflake-12345678", "Write the context offline (no API calls, no verification)"],
+	["$0 link --no-checks --org-id org-… --project-id polished-snowflake-12345678 --branch main", "Write the context offline (no API calls, no verification)"],
 	["$0 link --clear", "Forget the current org/project/branch context"]
 ]).epilogue(helpEpilogue("Non-interactive (CI, scripts, agents):", ...nonInteractiveLinkCommands().map((command) => `  ${command}`), orgScopedKeyHint)).strict();
 const runLink = async (props) => {
@@ -107,17 +114,26 @@ const runLink = async (props) => {
 	const inputs = parseInputs(props);
 	validateInputs(inputs);
 	const existing = readContextFile(props.contextFile);
+	if (props.yes && hasIncompleteCreationInputs(inputs)) throw incompleteCreationError(props, inputs);
 	if (canResolveNonInteractively(inputs, existing)) {
 		await runNonInteractive(props, inputs, existing);
 		return;
 	}
-	if (!canPromptInteractively()) throw new LinkInputError([
-		"Missing inputs and no interactive terminal for prompts.",
-		"",
-		"Use:",
-		nonInteractiveLinkHelp(),
-		orgScopedKeyHint
-	].join("\n"));
+	if (props.yes) {
+		const resolved = await resolveYesInputs(props, inputs);
+		await runNonInteractive(props, resolved, existing);
+		return;
+	}
+	if (!canPromptInteractively()) {
+		if (missingProjectForOrg(inputs)) throw orgNeedsProjectError(props, inputs);
+		throw new LinkInputError([
+			"Missing inputs and no interactive terminal for prompts.",
+			"",
+			"Use:",
+			nonInteractiveLinkHelp(),
+			orgScopedKeyHint
+		].join("\n"));
+	}
 	await runInteractive(props, inputs);
 };
 const handler = runLink;
@@ -162,6 +178,39 @@ const validateInputs = (inputs) => {
 	if (inputs.projectId && (inputs.projectName || inputs.regionId)) throw new Error("Conflicting inputs: --project-id selects an existing project; --project-name and --region-id describe a new one. Pass only one set.");
 	if (inputs.projectName && inputs.branch) throw new Error(`Conflicting inputs: --branch pins a branch of an existing project, but --project-name creates a new one. Create the project first, then \`${getCliName()} checkout <branch>\`.`);
 };
+const hasIncompleteCreationInputs = (inputs) => Boolean(inputs.projectName) !== Boolean(inputs.regionId);
+const missingProjectForOrg = (inputs) => Boolean(inputs.orgId) && !inputs.projectId && !inputs.projectName;
+const orgNeedsProjectError = (props, inputs) => {
+	const orgId = inputs.orgId ?? "<org-id>";
+	const branchFlag = inputs.branch ? ` --branch ${quoteFlagValue(inputs.branch)}` : "";
+	const session = sessionRetryFlags(props);
+	return new LinkInputError([
+		"No project selected. Pass --project-id, or use -y to select the only project:",
+		`  ${getCliName()} link -y --org-id ${quoteFlagValue(orgId)}${branchFlag}${session}`,
+		`  ${getCliName()} link --org-id ${quoteFlagValue(orgId)} --project-id <project-id>${inputs.branch ? ` --branch ${quoteFlagValue(inputs.branch)}` : " --branch <name-or-id>"}${session}`
+	].join("\n"));
+};
+const quoteFlagValue = (value) => {
+	if (/^[A-Za-z0-9_./:@-]+$/.test(value)) return value;
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+};
+const sessionRetryFlags = (props) => {
+	const flags = [];
+	if (props.contextFile) flags.push(`--context-file ${quoteFlagValue(props.contextFile)}`);
+	if (props.configDir && props.configDir !== defaultDir) flags.push(`--config-dir ${quoteFlagValue(props.configDir)}`);
+	if (props.output !== "table") flags.push(`--output ${props.output}`);
+	if (!props.envPull) flags.push("--no-env-pull");
+	if (props.profile) flags.push(`--profile ${quoteFlagValue(props.profile)}`);
+	return flags.length > 0 ? ` ${flags.join(" ")}` : "";
+};
+const incompleteCreationError = (props, inputs) => {
+	const orgFlag = inputs.orgId ? `--org-id ${quoteFlagValue(inputs.orgId)}` : "--org-id <org-id>";
+	const nameFlag = inputs.projectName ? `--project-name ${quoteFlagValue(inputs.projectName)}` : "--project-name <name>";
+	const regionFlag = inputs.regionId ? `--region-id ${quoteFlagValue(inputs.regionId)}` : "--region-id aws-us-east-2";
+	const example = `${getCliName()} link -y ${orgFlag} ${nameFlag} ${regionFlag}${sessionRetryFlags(props)}`;
+	if (inputs.projectName) return new LinkInputError(`--project-name requires --region-id. Example:\n  ${example}`);
+	return new LinkInputError(`--region-id requires --project-name. Example:\n  ${example}`);
+};
 /**
 * Branch selection may still prompt after org and project resolve without the
 * org/project wizard.
@@ -170,7 +219,6 @@ const canResolveNonInteractively = (inputs, existing) => {
 	if (inputs.projectId) return true;
 	if (inputs.orgId && inputs.projectName && inputs.regionId) return true;
 	if (inputs.branch && existing.projectId) return true;
-	if (inputs.orgId && !inputs.projectName && !inputs.branch) return true;
 	return false;
 };
 const clearContext = (contextFile) => {
@@ -180,16 +228,15 @@ const clearContext = (contextFile) => {
 /**
 * `--no-checks`: write the context offline. Makes no API calls — so no org
 * inference, no existence/access verification, and no env pull — which means
-* the caller must supply both `--org-id` and `--project-id` (the org can't be
-* inferred without the network). `--branch` stays optional. This is the CLI
-* surface over {@link setContext}, useful for scripted/offline setups and for
-* re-creating a `.neon` from values you already trust.
+* the caller must supply `--org-id`, `--project-id`, and `--branch`. This is
+* the CLI surface over {@link setContext}, useful for scripted/offline setups
+* and for re-creating a `.neon` from values you already trust.
 */
 const runWithoutChecks = (props) => {
 	const inputs = parseInputs(props);
 	validateInputs(inputs);
 	if (inputs.projectName) throw new Error("--no-checks can't create a project (that needs API access). Pass --org-id and --project-id for an existing project, or drop --no-checks.");
-	if (!inputs.orgId || !inputs.projectId) throw new Error("--no-checks writes the context with no API calls, so it needs both --org-id and --project-id (--branch is optional).");
+	if (!inputs.orgId || !inputs.projectId || !inputs.branch) throw new Error("--no-checks requires --org-id, --project-id, and --branch because identifiers cannot be resolved offline.");
 	setContext(props.contextFile, {
 		orgId: inputs.orgId,
 		projectId: inputs.projectId,
@@ -242,107 +289,105 @@ const verifyOrgAccess = async (props, orgId) => {
 		throw err;
 	}
 };
+const failWithBranchCandidates = (props, projectId, branches, reason) => {
+	writer(props).end(branches.map((b) => ({
+		id: b.id,
+		name: b.name ?? b.id
+	})), {
+		fields: ["id", "name"],
+		title: "Branches"
+	});
+	const orgFlag = props.orgId ? ` --org-id ${quoteFlagValue(props.orgId)}` : "";
+	throw new LinkInputError(`${reason}\n  ${getCliName()} link -y${orgFlag} --project-id ${quoteFlagValue(projectId)} --branch <name-or-id>${sessionRetryFlags(props)}`);
+};
+const listAllBranches = async (props, projectId) => listAllProjectBranches(props.apiClient, projectId);
 /**
 * Resolve a branch reference (name *or* id) to the matching branch, while
 * confirming it actually exists in the project. Unlike the shared
 * `branchIdResolve`, this also verifies references that already look like ids
-* (so a typo'd `br-…` doesn't silently get written), and surfaces the available
-* branches when nothing matches so the user can correct it (or run `checkout`).
+* (so a typo'd `br-…` doesn't silently get written).
 */
 const resolveBranchRef = async (props, projectId, branchRef) => {
-	const { data } = await props.apiClient.listProjectBranches({ projectId });
-	const match = data.branches.find((b) => b.id === branchRef) ?? data.branches.find((b) => b.name === branchRef);
+	const branches = await listAllBranches(props, projectId);
+	const match = branches.find((b) => b.id === branchRef) ?? branches.find((b) => b.name === branchRef);
 	if (match) return match;
-	throw new LinkInputError(`Branch '${branchRef}' not found in project '${projectId}'. Available branches: ${data.branches.length > 0 ? data.branches.map((b) => `${b.id}${b.name ? ` (${b.name})` : ""}`).join(", ") : "(none)"}. Pin one with \`${getCliName()} checkout <branch>\`.`);
+	return failWithBranchCandidates(props, projectId, branches, `Branch '${branchRef}' not found in project '${projectId}'. Pass --branch with a name or ID from the list:`);
 };
 /**
-* The value to persist for a branch: prefer its human-readable **name** (nicer
-* to read in `.neon`, and still resolvable by every command), falling back to
-* the id when the branch has no name.
+* Persist the name when later commands will look it up as a name. A name that
+* already looks like a branch id is trusted as an id without listing, so keep
+* the real id in that case.
 */
-const branchPersistValue = (branch) => branch.name ?? branch.id;
+const branchPersistValue = (branch) => {
+	if (branch.name && !looksLikeBranchId(branch.name)) return branch.name;
+	return branch.id;
+};
 /**
 * Verify the project (and the org, when supplied) and resolve the org id to
 * persist.
 *
 * The project is always fetched, which both validates it and yields its
 * `org_id`. When `--org-id` is passed too: if the project reports an org it must
-* match (else a clear mismatch error); if it reports none, the supplied org is
-* verified on its own. Without `--org-id` the project's own org is used, falling
-* back to the org already recorded for the *same* project in `.neon`. Projects
-* on a personal account have no org, so `undefined` is a valid result — the
-* field is simply omitted.
+* match (else a clear mismatch error); if it reports none, fail rather than
+* attaching an unrelated org. Without `--org-id` the project's own org is used.
+* Projects on a personal account have no org, so `undefined` is a valid result —
+* the field is simply omitted.
 */
-const resolveOrgForProject = async (props, inputs, existing, projectId) => {
+const resolveOrgForProject = async (props, inputs, projectId) => {
 	const projectOrg = (await fetchProjectOrThrow(props, projectId)).org_id ?? void 0;
 	if (inputs.orgId) {
 		if (projectOrg && projectOrg !== inputs.orgId) throw new LinkInputError(`Project '${projectId}' belongs to organization '${projectOrg}', not '${inputs.orgId}'. Omit --org-id to use the project's own org, or pass the matching ID.`);
-		if (!projectOrg) await verifyOrgAccess(props, inputs.orgId);
+		if (!projectOrg) throw new LinkInputError(`Project '${projectId}' does not report an organization matching --org-id ${inputs.orgId}. Omit --org-id to link using the project's own context.`);
 		return inputs.orgId;
 	}
 	if (projectOrg) return projectOrg;
-	if (projectId === existing.projectId && existing.orgId) return existing.orgId;
 };
 /**
-* Keep an existing pin when re-linking the same project so `-y` does not reset
-* a checkout.
+* Keep a same-project pin only after it still resolves on the project.
 */
 const resolvePinnedBranch = async (props, inputs, existing, projectId) => {
 	if (inputs.branch) {
 		const branch = await resolveBranchRef(props, projectId, inputs.branch);
-		return {
-			branch: branchPersistValue(branch),
-			empty: false
-		};
+		return { branch: branchPersistValue(branch) };
 	}
 	if (projectId === existing.projectId) {
 		const pinned = contextBranch(existing);
-		if (pinned) return {
-			branch: pinned,
-			empty: false
-		};
+		if (pinned) {
+			const branch = await resolveBranchRef(props, projectId, pinned);
+			return { branch: branchPersistValue(branch) };
+		}
 	}
 	return resolveBranchFromList(props, projectId);
 };
 const resolveBranchFromList = async (props, projectId) => {
-	const { data } = await props.apiClient.listProjectBranches({ projectId });
-	const branches = data.branches;
-	if (branches.length === 0) return { empty: true };
+	const branches = await listAllBranches(props, projectId);
+	if (branches.length === 0) throw new LinkInputError(`Project '${projectId}' has no branches to link. Create or restore a branch before retrying, or select another project with --project-id.`);
 	if (branches.length === 1) {
 		const [only] = branches;
-		if (!only) return { empty: true };
-		return {
-			branch: branchPersistValue(only),
-			empty: false
-		};
+		if (!only) throw new LinkInputError(`Project '${projectId}' has no branches to link. Create or restore a branch before retrying, or select another project with --project-id.`);
+		return { branch: branchPersistValue(only) };
 	}
 	if (props.yes) {
 		const def = branches.find((b) => b.default);
-		if (!def) throw new Error(`Project '${projectId}' has no default branch. Pass --branch <name> to pin one.`);
-		return {
-			branch: branchPersistValue(def),
-			empty: false
-		};
+		if (!def) return failWithBranchCandidates(props, projectId, branches, `Project '${projectId}' has no default branch. Pass --branch with a name or ID from the list:`);
+		return { branch: branchPersistValue(def) };
 	}
 	if (canPromptInteractively()) {
 		const picked = await pickBranchInteractively(branches, {
 			message: "Which branch would you like to link?",
-			nonInteractiveMessage: `No branch could be selected without an interactive terminal. Re-run \`${getCliName()} link\` interactively, or \`${getCliName()} checkout <branch>\` to pin one.`
+			nonInteractiveMessage: "No branch could be selected without an interactive terminal. Pass --branch <name-or-id>, or -y to pin the default branch."
 		});
 		if (picked.kind === "existing") {
 			const existing = branches.find((b) => b.id === picked.branchId);
-			return {
-				branch: existing ? branchPersistValue(existing) : picked.branchId,
-				empty: false
-			};
+			return { branch: existing ? branchPersistValue(existing) : picked.branchId };
 		}
-		await createBranch(props.apiClient, projectId, picked.name, branches);
-		return {
-			branch: picked.name,
-			empty: false
-		};
+		const created = await createBranch(props.apiClient, projectId, picked.name, branches);
+		return { branch: branchPersistValue({
+			id: created,
+			name: picked.name
+		}) };
 	}
-	return { empty: false };
+	return failWithBranchCandidates(props, projectId, branches, `Project '${projectId}' has multiple branches. Pass --branch <name-or-id>, or -y to pin its default branch.`);
 };
 const runNonInteractive = async (props, inputs, existing) => {
 	if (inputs.projectName) {
@@ -370,7 +415,7 @@ const runNonInteractive = async (props, inputs, existing) => {
 		return;
 	}
 	if (inputs.projectId) {
-		const orgId = await resolveOrgForProject(props, inputs, existing, inputs.projectId);
+		const orgId = await resolveOrgForProject(props, inputs, inputs.projectId);
 		const resolved = await resolvePinnedBranch(props, inputs, existing, inputs.projectId);
 		applyContext(props.contextFile, {
 			orgId,
@@ -382,14 +427,13 @@ const runNonInteractive = async (props, inputs, existing) => {
 			orgId,
 			projectId: inputs.projectId,
 			branch: resolved.branch,
-			created: false,
-			empty: resolved.empty
+			created: false
 		});
 		return;
 	}
 	if (inputs.branch && existing.projectId) {
 		const projectId = existing.projectId;
-		const orgId = await resolveOrgForProject(props, inputs, existing, projectId);
+		const orgId = await resolveOrgForProject(props, inputs, projectId);
 		const resolved = await resolvePinnedBranch(props, inputs, existing, projectId);
 		applyContext(props.contextFile, {
 			orgId,
@@ -401,31 +445,11 @@ const runNonInteractive = async (props, inputs, existing) => {
 			orgId,
 			projectId,
 			branch: resolved.branch,
-			created: false,
-			empty: resolved.empty
-		});
-		return;
-	}
-	if (inputs.orgId) {
-		const orgId = inputs.orgId;
-		await verifyOrgAccess(props, orgId);
-		const projectId = existing.projectId;
-		const branch = projectId ? contextBranch(existing) : void 0;
-		applyContext(props.contextFile, {
-			orgId,
-			projectId,
-			branch
-		});
-		printSummary(props, {
-			contextFile: props.contextFile,
-			orgId,
-			projectId,
-			branch,
-			created: false,
-			orgOnly: true
+			created: false
 		});
 		return;
 	}
+	throw orgNeedsProjectError(props, inputs);
 };
 const runInteractive = async (props, inputs) => {
 	if (!props.yes) {
@@ -439,6 +463,7 @@ const runInteractive = async (props, inputs) => {
 	} else if (orgResolution.orgKeyLimited) throw new Error("This API key is organization-scoped, so the CLI cannot list your organizations, and no existing project was found in this org to auto-detect the ID. Re-run with `--org-id <your_org_id>` (find it in the Neon Console under Settings).");
 	else orgId = await promptOrgFromList(orgResolution.orgs);
 	if (inputs.projectName && inputs.regionId) {
+		if (inputs.branch) throw new Error(`Conflicting inputs: --branch pins a branch of an existing project, but --project-name creates a new one. Create the project first, then \`${getCliName()} checkout <branch>\`.`);
 		const created = await createProject(props, {
 			orgId,
 			name: inputs.projectName,
@@ -461,9 +486,10 @@ const runInteractive = async (props, inputs) => {
 		return;
 	}
 	const projects = await listAllProjects(props, orgId);
-	const action = await promptProjectChoice(projects, inputs.projectName);
+	const action = await promptProjectChoice(projects, inputs.projectName, { allowCreate: !inputs.branch });
 	if (action.type === "existing") {
-		const resolved = await resolveBranchFromList(props, action.projectId);
+		const existing = readContextFile(props.contextFile);
+		const resolved = await resolvePinnedBranch(props, inputs, existing, action.projectId);
 		applyContext(props.contextFile, {
 			orgId,
 			projectId: action.projectId,
@@ -476,11 +502,11 @@ const runInteractive = async (props, inputs) => {
 			branch: resolved.branch,
 			created: false,
 			projectName: action.name,
-			regionId: action.regionId,
-			empty: resolved.empty
+			regionId: action.regionId
 		});
 		return;
 	}
+	if (inputs.branch) throw new Error(`Conflicting inputs: --branch pins a branch of an existing project, but creating a project starts from its default branch. Link an existing project, or omit --branch and create first.`);
 	const projectName = inputs.projectName ?? await promptProjectName(action.suggestedName);
 	const regionId = inputs.regionId ?? await promptRegion(props);
 	const created = await createProject(props, {
@@ -505,12 +531,12 @@ const runInteractive = async (props, inputs) => {
 };
 const confirmRelinkIfNeeded = async (props) => {
 	const existing = readContextFile(props.contextFile);
-	if (!existing.orgId || !existing.projectId) return true;
+	if (!existing.projectId) return true;
 	const { proceed } = await prompts({
 		onState: onPromptState,
 		type: "confirm",
 		name: "proceed",
-		message: `${props.contextFile} is already linked to project ${existing.projectId} (org ${existing.orgId}). Re-link?`,
+		message: existing.orgId ? `${props.contextFile} is already linked to project ${existing.projectId} (org ${existing.orgId}). Re-link?` : `${props.contextFile} is already linked to project ${existing.projectId}. Re-link?`,
 		initial: true
 	});
 	if (!proceed) {
@@ -539,21 +565,23 @@ const promptOrgFromList = async (orgs) => {
 	});
 	return orgId;
 };
-const promptProjectChoice = async (projects, suggestedName) => {
-	const choices = [{
+const promptProjectChoice = async (projects, suggestedName, opts) => {
+	const choices = [...opts.allowCreate ? [{
 		title: "＋ Create new project…",
 		value: CREATE_NEW_SENTINEL
-	}, ...projects.map((project) => ({
+	}] : [], ...projects.map((project) => ({
 		title: `${project.name} (${project.id})`,
 		value: project.id
 	}))];
+	if (choices.length === 0) throw new LinkInputError("No projects are available to link. Omit --branch to create a project, or pass --project-id for an existing one.");
+	const createOffset = opts.allowCreate ? 1 : 0;
 	const { selection } = await prompts({
 		onState: onPromptState,
 		type: "select",
 		name: "selection",
 		message: "Which project would you like to link?",
 		choices,
-		initial: projects.length > 0 ? 1 : 0
+		initial: projects.length > 0 ? createOffset : 0
 	});
 	if (selection === CREATE_NEW_SENTINEL) return {
 		type: "create",
@@ -666,6 +694,71 @@ const listAllProjects = async (props, orgId) => {
 	}
 	return result;
 };
+const CANDIDATE_FIELDS = ["id", "name"];
+const extraYesFlags = (props, inputs) => {
+	const flags = [];
+	if (inputs.projectName) flags.push(`--project-name ${quoteFlagValue(inputs.projectName)}`);
+	if (inputs.regionId) flags.push(`--region-id ${quoteFlagValue(inputs.regionId)}`);
+	if (inputs.branch) flags.push(`--branch ${quoteFlagValue(inputs.branch)}`);
+	return `${flags.length > 0 ? ` ${flags.join(" ")}` : ""}${sessionRetryFlags(props)}`;
+};
+const yesProjectIdCommand = (props, inputs, orgId = inputs.orgId) => {
+	const orgFlag = orgId ? ` --org-id ${quoteFlagValue(orgId)}` : "";
+	const branchFlag = inputs.branch ? ` --branch ${quoteFlagValue(inputs.branch)}` : "";
+	return `${getCliName()} link -y${orgFlag} --project-id <project-id>${branchFlag}${sessionRetryFlags(props)}`;
+};
+const printNamedCandidates = (props, title, items) => {
+	writer(props).end(items, {
+		fields: CANDIDATE_FIELDS,
+		title
+	});
+};
+const orgScopedKeyNeedsOrgId = () => new LinkInputError("This API key is organization-scoped, so the CLI cannot list your organizations, and no existing project was found in this org to auto-detect the ID. Re-run with `--org-id <your_org_id>` (find it in the Neon Console under Settings).");
+const resolveYesOrgId = async (props, inputs) => {
+	const orgResolution = await resolveOrg(props, inputs.orgId);
+	if (orgResolution.kind === "resolved") {
+		if (orgResolution.autoDetected) log.info(`Detected organization ${orgResolution.orgId} from your existing projects (organization-scoped API key).`);
+		return orgResolution.orgId;
+	}
+	if (orgResolution.orgKeyLimited) throw orgScopedKeyNeedsOrgId();
+	const orgs = orgResolution.orgs;
+	if (orgs.length === 0) throw new LinkInputError(["No organizations were returned for this account. Pass --project-id for a project you can access:", `  ${yesProjectIdCommand(props, inputs)}`].join("\n"));
+	if (orgs.length === 1) {
+		const [only] = orgs;
+		return only.id;
+	}
+	printNamedCandidates(props, "Organizations", orgs.map((org) => ({
+		id: org.id,
+		name: org.name
+	})));
+	throw new LinkInputError(["Multiple organizations are available. Pass --org-id with an ID from the list:", `  ${getCliName()} link -y --org-id <org-id>${extraYesFlags(props, inputs)}`].join("\n"));
+};
+const resolveYesInputs = async (props, inputs) => {
+	const orgId = await resolveYesOrgId(props, inputs);
+	if (inputs.projectName && inputs.regionId) return {
+		...inputs,
+		orgId
+	};
+	const projects = await listAllProjects(props, orgId);
+	if (projects.length === 0) throw new LinkInputError([
+		`No projects are available in organization '${orgId}'.`,
+		"To create and link a project, pass --project-name and --region-id:",
+		`  ${getCliName()} link -y --org-id ${quoteFlagValue(orgId)} --project-name <name> --region-id aws-us-east-2${sessionRetryFlags(props)}`
+	].join("\n"));
+	if (projects.length === 1) {
+		const [only] = projects;
+		return {
+			...inputs,
+			orgId,
+			projectId: only.id
+		};
+	}
+	printNamedCandidates(props, "Projects", projects.map((project) => ({
+		id: project.id,
+		name: project.name
+	})));
+	throw new LinkInputError([`Multiple projects are available in organization '${orgId}'. Pass --project-id with an ID from the list:`, `  ${yesProjectIdCommand(props, inputs, orgId)}`].join("\n"));
+};
 const fetchRegions = async (props) => {
 	try {
 		const { data } = await props.apiClient.getActiveRegions();
@@ -708,30 +801,26 @@ const createProject = async (props, args) => {
 const printSummary = (_props, summary) => {
 	const lines = [];
 	if (summary.created) lines.push(`Created project ${summary.projectId}${summary.projectName ? ` ("${summary.projectName}")` : ""}${summary.regionId ? ` in ${summary.regionId}` : ""}.`);
-	lines.push(`${summary.orgOnly ? "Updated" : "Linked"} ${summary.contextFile}:`);
+	lines.push(`Linked ${summary.contextFile}:`);
 	if (summary.orgId) lines.push(`  orgId:     ${summary.orgId}`);
-	if (summary.projectId) lines.push(`  projectId: ${summary.projectId}`);
-	if (summary.branch) lines.push(`  branch:    ${summary.branch}`);
+	lines.push(`  projectId: ${summary.projectId}`);
+	lines.push(`  branch:    ${summary.branch}`);
 	if (summary.noChecks) {
 		lines.push("");
 		lines.push("Written offline (--no-checks): nothing was verified.");
-	} else if (summary.projectId && !summary.branch && !summary.orgOnly) {
-		lines.push("");
-		if (summary.empty) lines.push(`This project has no branches, so none was pinned. Create a branch, then run \`${getCliName()} checkout <branch>\` to pin it and pull its env vars.`);
-		else lines.push(`No branch pinned. Run \`${getCliName()} checkout <branch>\` to pin a branch and pull its env vars.`);
 	}
 	lines.push("");
 	process.stdout.write(`${lines.join("\n")}\n`);
 };
 /**
-* Print the link summary, then run the bundled `env pull` so a human `link` that pinned a
-* branch ends with the branch's connection string already on disk. When no branch was pinned
-* there is nothing to pull, so env pull is skipped and the summary nudges `checkout` instead.
-* `--no-env-pull` opts out (env pull's own status / skip hint is logged to stderr).
+* Print the link summary, then run the bundled `env pull` so a completed `link` ends with
+* the pinned branch's connection string on disk. `--no-checks` skips the pull because
+* nothing was verified. `--no-env-pull` opts out (env pull's own status / skip hint is
+* logged to stderr).
 */
 const finalizeLink = async (props, summary) => {
 	printSummary(props, summary);
-	if (!summary.branch || !summary.projectId) return;
+	if (!summary.branch || !summary.projectId || summary.noChecks) return;
 	const { config: _offerConfig, ...rest } = props;
 	await autoPullEnvAfterPin({
 		...rest,

package/dist/commands/logs.js

@@ -16,7 +16,7 @@ var logs_exports = /* @__PURE__ */ __exportAll({
 	handler: () => handler
 });
 const LOGS_EPILOG = `
-Logs require Neon Platform Beta and are currently available only for projects in aws-us-east-2, aws-us-east-1, aws-eu-central-1, and aws-ap-southeast-1.
+Logs are currently available only for projects in aws-us-east-2, aws-us-east-1, aws-eu-central-1, and aws-ap-southeast-1.
 
 For more information, visit https://neon.com/docs/reference/neon-cli`;
 const LOG_SOURCES = [

package/dist/commands/schema_diff.js

@@ -2,7 +2,7 @@ import { log } from "../log.js";
 import { isNeonApiError, messageFromBody } from "../api.js";
 import { sendError } from "../analytics.js";
 import { writer } from "../writer.js";
-import { branchIdFromProps } from "../utils/enrichers.js";
+import { branchIdFromProps, listAllProjectBranches } from "../utils/enrichers.js";
 import { parsePointInTime } from "../utils/point_in_time.js";
 import chalk from "chalk";
 import { createPatch } from "diff";
@@ -92,13 +92,11 @@ const parseSchemaDiffParams = async (props) => {
 			props.compareSource = props.baseBranch;
 			props.baseBranch = props.branch;
 		} else if (props.branch) {
-			const { data } = await props.apiClient.listProjectBranches({ projectId: props.projectId });
-			if (data.branches.find((b) => b.id === props.branch || b.name === props.branch)?.parent_id == void 0) throw new Error(`No branch specified. Your context branch (${props.branch}) has no parent, so no comparison is possible.`);
+			if ((await listAllProjectBranches(props.apiClient, props.projectId)).find((b) => b.id === props.branch || b.name === props.branch)?.parent_id == void 0) throw new Error(`No branch specified. Your context branch (${props.branch}) has no parent, so no comparison is possible.`);
 			log.info(`No branches specified. Comparing your context branch '${props.branch}' with its parent`);
 			props.compareSource = "^parent";
 		} else {
-			const { data } = await props.apiClient.listProjectBranches({ projectId: props.projectId });
-			if (data.branches.find((b) => b.default)?.parent_id == void 0) throw new Error("No branch specified. Include a base branch or add a set-context branch to continue. Your default branch has no parent, so no comparison is possible.");
+			if ((await listAllProjectBranches(props.apiClient, props.projectId)).find((b) => b.default)?.parent_id == void 0) throw new Error("No branch specified. Include a base branch or add a set-context branch to continue. Your default branch has no parent, so no comparison is possible.");
 			log.info(`No branches specified. Comparing default branch with its parent`);
 			props.compareSource = "^parent";
 		}

package/dist/commands/set_context.js

@@ -26,7 +26,7 @@ const builder = (argv) => argv.usage("$0 set-context [options]").options({
 	}
 });
 const handler = (props) => {
-	log.warning(`\`${getCliName()} set-context\` is deprecated and will be removed in a future release. Use \`${getCliName()} link\` instead — it verifies inputs and infers the org for you (or \`${getCliName()} link --no-checks\` for the same write-without-checks behavior).`);
+	log.warning(`\`${getCliName()} set-context\` is deprecated and will be removed in a future release. Use \`${getCliName()} link\` instead — it verifies inputs and writes a complete context (or \`${getCliName()} link --no-checks --org-id … --project-id … --branch …\` for an offline write).`);
 	const context = {
 		projectId: props.projectId,
 		orgId: props.orgId,

package/dist/index.js

@@ -8,9 +8,9 @@ import { currentContextFile, enrichFromContext } from "./context.js";
 import { analyticsMiddleware, closeAnalytics, commandSuccessProperties, initAnalyticsClientMiddleware, sendError, takeCommandSuccessExtras, trackEvent } from "./analytics.js";
 import { NETWORK_ERROR_MESSAGE, isNetworkError, matchErrorCode } from "./errors.js";
 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 { getCliName } from "./utils/cli_name.js";
 import { showHelp } from "./help.js";
 import { rewriteUnknownAgentArg } from "./init/plan.js";
 import commands_default from "./commands/index.js";

package/dist/utils/enrichers.js

@@ -2,12 +2,32 @@ import { isNeonApiError, messageFromBody } from "../api.js";
 import { isConfigInit, isCurrentBranchProbe } from "../context.js";
 import { looksLikeBranchId } from "./formats.js";
 //#region src/utils/enrichers.ts
+const BRANCHES_LIST_LIMIT = 100;
+/**
+* Branch list pages cap at 100. A name stored in `.neon` can live on a later
+* page, so resolution has to walk `pagination.next` before treating it as missing.
+*/
+const listAllProjectBranches = async (apiClient, projectId) => {
+	const result = [];
+	let cursor;
+	while (true) {
+		const { data } = await apiClient.listProjectBranches({
+			projectId,
+			limit: BRANCHES_LIST_LIMIT,
+			cursor
+		});
+		result.push(...data.branches);
+		cursor = data.pagination?.next;
+		if (!cursor || data.branches.length === 0) break;
+	}
+	return result;
+};
 const branchIdResolve = async ({ branch, apiClient, projectId }) => {
 	branch = branch.toString();
 	if (looksLikeBranchId(branch)) return branch;
-	const { data } = await apiClient.listProjectBranches({ projectId });
-	const branchData = data.branches.find((b) => b.name === branch);
-	if (!branchData) throw new Error(`Branch ${branch} not found.\nAvailable branches: ${data.branches.map((b) => b.name).join(", ")}`);
+	const branches = await listAllProjectBranches(apiClient, projectId);
+	const branchData = branches.find((b) => b.name === branch);
+	if (!branchData) throw new Error(`Branch ${branch} not found.\nAvailable branches: ${branches.map((b) => b.name).join(", ")}`);
 	return branchData.id;
 };
 const getBranchIdFromProps = async (props) => {
@@ -17,8 +37,7 @@ const getBranchIdFromProps = async (props) => {
 		apiClient: props.apiClient,
 		projectId: props.projectId
 	});
-	const { data } = await props.apiClient.listProjectBranches({ projectId: props.projectId });
-	const defaultBranch = data.branches.find((b) => b.default);
+	const defaultBranch = (await listAllProjectBranches(props.apiClient, props.projectId)).find((b) => b.default);
 	if (defaultBranch) return defaultBranch.id;
 	throw new Error("No default branch found");
 };
@@ -28,8 +47,7 @@ const branchIdFromProps = async (props) => {
 };
 const resolveBranchRef = async (props) => {
 	const branch = typeof props.branch === "string" ? props.branch : props.id;
-	const { data } = await props.apiClient.listProjectBranches({ projectId: props.projectId });
-	const branches = data.branches;
+	const branches = await listAllProjectBranches(props.apiClient, props.projectId);
 	const listingFields = (listed) => ({
 		isDefault: listed.default === true,
 		isProtected: listed.protected === true,
@@ -111,4 +129,4 @@ const fillSingleOrg = async (props) => {
 	};
 };
 //#endregion
-export { branchIdFromProps, branchIdResolve, fillSingleOrg, fillSingleProject, resolveBranchRef, resolveSingleDatabase };
+export { branchIdFromProps, branchIdResolve, fillSingleOrg, fillSingleProject, listAllProjectBranches, resolveBranchRef, resolveSingleDatabase };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "4.22.0",
+  "version": "5.0.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.7.1",
-    "@neon/config-runtime": "1.6.1",
-    "@neon/sdk": "6.0.0"
+    "@neon/config": "1.7.2",
+    "@neon/sdk": "6.0.0",
+    "@neon/config-runtime": "1.6.2"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0",
@@ -98,7 +98,7 @@
     "typescript": "^5.9.0",
     "vitest": "^3.0.9",
     "@neon-internals/cli-core": "0.0.0",
-    "@neon-internals/env-core": "0.0.20",
+    "@neon-internals/env-core": "0.0.21",
     "@neon/e2e-harness": "0.0.0",
     "@neon/functions": "0.11.0"
   },