neonctl 2.22.0 → 2.23.0

package/README.md

@@ -58,25 +58,236 @@ neonctl projects list --api-key <neon_api_key>
 
 For information about obtaining an Neon API key, see [Authentication](https://api-docs.neon.tech/reference/authentication), in the _Neon API Reference_.
 
+## Connect with psql
+
+Several commands accept a `--psql` flag that opens a psql session against the resolved endpoint:
+
+```bash
+neonctl connection-string --psql --project-id <id>
+neonctl projects create --psql
+neonctl branches create --psql
+```
+
+Any arguments after `--` are forwarded to psql, for example:
+
+```bash
+neonctl cs --psql --project-id <id> -- -c "SELECT version()"
+neonctl cs --psql --project-id <id> -- -f script.sql --csv
+```
+
+### Embedded psql fallback
+
+If the system has `psql` installed on `$PATH`, `--psql` continues to spawn the native binary — there is no behavior change for existing users.
+
+If `psql` is not found on `$PATH`, neonctl now falls back to an embedded TypeScript implementation. There is nothing to install or configure; it ships with `neonctl`. This removes the "no psql binary" trap on machines (and CI runners) that don't have PostgreSQL client tools installed.
+
+Automatic fallback is the intended path — there is normally no flag to set. The embedded implementation can also be force-selected (primarily for tests and CI, e.g. to exercise it even when a native `psql` is present):
+
+- `--fallback` — force the embedded implementation on `connection-string`, `projects create`, and `branches create`. Intentionally hidden from `--help`: it's a test/CI knob, not a user-facing option (the automatic fallback above is the supported behavior).
+- `NEONCTL_PSQL_FALLBACK=1` — environment variable with the same effect as `--fallback`. Convenient for scripts and CI.
+
+The embedded implementation is verified against a conformance suite that
+diffs its behavior against real PostgreSQL (14–18) and the upstream psql
+regression + TAP tests.
+
+#### What works
+
+**REPL & scripting**
+
+- Interactive REPL with a hand-rolled VT100 line editor (no native bindings); vi and emacs edit modes (`VI_MODE` psql variable)
+- Persistent command history (`~/.psql_history`, libreadline format)
+- `~/.psqlrc` autoload (including `$PGSYSCONFDIR/psqlrc` and version-suffixed variants)
+- Scripted modes: `-c "SQL"`, `-f script.sql`, and stdin; `--single-transaction`, `ON_ERROR_STOP`, `ECHO`, `--echo-all`
+- `SINGLELINE` (`-S`), `\timing`, `\watch` (named flags `c=`/`i=`/`m=`, unbounded continuous mode)
+
+**Backslash commands**
+
+- All output formats: aligned, unaligned, wrapped, csv, json, html, asciidoc, latex, latex-longtable, troff-ms (`\a \H \t \x \pset \f \C` …)
+- All `\d*` describe commands with full upstream parity (columns, indexes, foreign keys, triggers, view definitions, sequences, RLS, replica identity, partitions, tablespaces, access methods, inheritance, FDW, stats objects, publications, subscriptions, per-column FDW options, TOAST owner)
+- `\copy` to/from file, `PROGRAM`, `STDIN`, `STDOUT` (incl. the `\.` EOF marker); `\g` / `\gx` / `\gset` / `\gdesc` / `\gexec` and `\g | program` pipes
+- Extended query + pipeline mode (`\bind`, `\bind_named`, `\startpipeline`, `\parse`, `\sendpipeline`)
+- `\crosstabview`, `\lo_*` large objects, `\e`/`\edit` (external editor), `\s` (history), `\?`/`\h` help, `\if`/`\elif`/`\else`/`\endif`, `\set`/`\unset`, `\connect`, `\encoding` (live `SET client_encoding`), `\!`, `\cd`, `\prompt` (incl. no-echo `-`), `\password`
+- Tab completion (~88 rules incl. live `pg_settings` GUC lookup, deep `ALTER` sub-actions, `JOIN` clauses, window `OVER`)
+
+**Connection & authentication**
+
+- libpq-equivalent lookup precedence: argv flags > URI > `PG*` env vars > `~/.pgpass` > `pg_service.conf` > libpq defaults
+- SCRAM-SHA-256 / SCRAM-SHA-256-PLUS with `tls-server-end-point` channel binding (`channel_binding`); MD5 and cleartext; `require_auth`
+- Multi-host failover & load balancing: `target_session_attrs` (any / read-write / read-only / primary / standby / prefer-standby), `load_balance_hosts`, DNS fan-out, `hostaddr`
+- Unix-domain sockets (host beginning with `/`); TCP keepalives (`keepalives`, `keepalives_idle`)
+
+**TLS**
+
+- `sslmode` disable → verify-full; client certs in **PEM or DER** via `sslcert` / `sslkey` (+ `sslpassword` for encrypted keys, with the libpq group/world-readable-key check)
+- Trust config: `sslrootcert` (incl. `=system` with `SSL_CERT_FILE` / `SSL_CERT_DIR`), default client-cert discovery (`~/.postgresql/postgresql.{crt,key}`), `sslcertmode`
+- CRL: `sslcrl` and `sslcrldir`; `ssl_min_protocol_version` / `ssl_max_protocol_version`; `sslsni`
+- Direct-SSL negotiation (`sslnegotiation=direct`, PostgreSQL 17+, via ALPN)
+
+#### What's not supported
+
+- **GSSAPI / SSPI** (`gssencmode`, Kerberos/SSPI auth, `requirepeer`). GSS transport encryption needs a native Kerberos binding, which the embedded psql deliberately avoids (pure TypeScript, zero native dependencies — the same reason the line editor is hand-rolled). `node-postgres` doesn't support it either, and Neon doesn't use it. `gssencmode=disable` / `prefer` are accepted; `gssencmode=require` is rejected with a clear error. `requirepeer` is parsed but a Unix-socket connection that sets it is refused (Node exposes no peer-credential API — it is not silently ignored).
+- **`keepalives_interval` / `keepalives_count`** — Node's socket API exposes only keepalive enable + initial delay, so these are accepted but not applied.
+
+### Known limitations
+
+- **TLS cipher is runtime-dependent.** The negotiated TLS 1.3 ciphersuite is chosen by the host runtime's TLS library from an offer byte-identical to libpq's. Under Node (OpenSSL) that is `TLS_AES_256_GCM_SHA384`, matching vanilla psql; under Bun (BoringSSL) it is `TLS_AES_128_GCM_SHA256`. Both are TLS 1.3 AEAD suites with no practical security difference, and neither runtime exposes a client-side knob to steer the selection.
+
 ## 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.
 
+## Linking a project
+
+`neonctl link` is a Vercel-style command that binds the current directory to a Neon project. It picks (or creates) an organization, picks (or creates) a project, resolves the project's default branch, and writes a `.neon` file with `{ "orgId", "projectId", "branchId" }`. Subsequent commands run in this directory (or any sub-directory) automatically pick up that context.
+
+There are three modes:
+
+**Interactive (default)** — guided prompts for humans:
+
+```bash
+$ neonctl link
+? Which organization would you like to link? › Personal Org (org-abc123)
+? Which project would you like to link? › + Create new project
+? Name for the new project: › my-app
+? Which region should the new project run in? › AWS US East (Ohio) (aws-us-east-2)
+Created project polished-snowflake-12345678 ("my-app") in aws-us-east-2.
+Linked .neon:
+  orgId:    org-abc123
+  projectId: polished-snowflake-12345678
+  branchId:  br-main-branch-87654321
+```
+
+**Non-interactive (flags or `--params` JSON)** — for scripts and CI:
+
+```bash
+# Link to an existing project
+neonctl link --org-id org-abc123 --project-id polished-snowflake-12345678
+
+# Create a new project and link
+neonctl link --org-id org-abc123 --project-name my-app --region-id aws-us-east-2
+
+# Same payload, one JSON blob
+neonctl link --params '{"orgId":"org-abc123","projectName":"my-app","regionId":"aws-us-east-2"}'
+```
+
+**Agent mode (`--agent`)** — a JSON state machine designed for AI coding assistants. Each invocation returns a single JSON object with a `status` discriminator describing the next step, the available options, and the exact follow-up command to run.
+
+```bash
+$ neonctl link --agent
+{
+  "status": "needs_org",
+  "instruction": "Ask the user which of these 2 organizations they want to link the current directory to. After they pick one, re-run the next_command_template with the chosen --org-id value.",
+  "options": [
+    { "id": "org-abc123", "name": "Personal Org" },
+    { "id": "org-team",   "name": "Team Org" }
+  ],
+  "next_command_template": "neonctl link --agent --org-id <org_id>"
+}
+
+$ neonctl link --agent --org-id org-abc123
+{
+  "status": "needs_project",
+  "instruction": "Ask the user whether to link to one of these 1 existing projects (use next_command_template with --project-id) or create a new project (use create_option.next_command_template).",
+  "options": [
+    { "id": "polished-snowflake-12345678", "name": "my-app" }
+  ],
+  "create_option": {
+    "instruction": "To create a new project, ask the user for a project name. The region can be omitted to receive a follow-up needs_project_details response that lists available regions.",
+    "next_command_template": "neonctl link --agent --org-id org-abc123 --project-name <name> --region-id <region_id>"
+  },
+  "next_command_template": "neonctl link --agent --org-id org-abc123 --project-id <project_id>"
+}
+
+$ neonctl link --agent --org-id org-abc123 --project-id polished-snowflake-12345678
+{
+  "status": "linked",
+  "context_file": "/path/to/cwd/.neon",
+  "context": {
+    "orgId": "org-abc123",
+    "projectId": "polished-snowflake-12345678",
+    "branchId": "br-main-branch-87654321"
+  },
+  "project": { "id": "polished-snowflake-12345678" },
+  "message": "Linked /path/to/cwd/.neon to project polished-snowflake-12345678 (org org-abc123) on branch br-main-branch-87654321."
+}
+```
+
+The agent flow also handles project creation. If the agent sends `--project-name` without `--region-id`, the next response is `needs_project_details` with the list of supported regions.
+
+**Organization-scoped API keys** (those created at the organization level rather than the user level) cannot list user organizations or call the regions endpoint. `link` handles this transparently:
+
+- If the API key is org-scoped and at least one project already exists in the org, the CLI auto-detects the `org_id` from the first project. In interactive mode it prints an informational message; in `--agent` mode it skips straight to `needs_project`.
+- If the API key is org-scoped and no projects exist yet, `--agent` returns a `needs_org` response with `options: []` and an instruction telling the user to find their org ID in the Neon Console. Interactive mode prints an error pointing to `--org-id`.
+- When the regions endpoint is not allowed, `link` falls back to a built-in static region list.
+
+**Agent error contract**: any unexpected failure in `--agent` mode is reported as JSON to stdout with exit code 1, so agents can always parse the response:
+
+```json
+{
+  "status": "error",
+  "code": "CLIENT_ERROR",
+  "message": "user has no access to projects"
+}
+```
+
+`link` is a thin wrapper around `set-context`: both write to the same `.neon` file via a shared `applyContext` helper, so anything `link` can write, `set-context` can write too (including the newly-supported `--branch-id` flag).
+
+### checkout
+
+`checkout [id|name]` pins a branch in the local context so subsequent commands target it — it's a focused helper over `set-context` for the common "switch the branch I'm working on" case. It resolves the branch (by name or id) against the project, then **heals** the `.neon` file: it always (re)writes `projectId`, `branchId`, and `orgId` (when the project has one), so a `.neon` that was missing fields or drifted ends up complete and consistent. 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 `neonctl 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.
+
+Branch **id vs name** is detected automatically (a `br-…` value is treated as an id):
+
+- **id** — matched strictly by id. A non-existent id is a hard "not found" error (ids are server-assigned, so checkout never creates one).
+- **name** — matched by name. If the name doesn't exist, in an interactive terminal `checkout` offers to **create** it (equivalent to `neonctl branch create --name <name>`: branched from the project's default branch with a read-write compute), then checks it out. In a non-interactive context a missing name is the usual "not found" error.
+
+The project is resolved through the standard neonctl chain, each entry winning over the next:
+
+1. `--project-id <id>` flag
+2. `projectId` from the closest `.neon` file (found by walking up from the current directory — see "Where `.neon` lives" below)
+3. If still unresolved and the API key maps to exactly one project, that project is auto-detected (same behaviour as `branches` and `connection-string`)
+
+If none of those resolve a project, `checkout` prints a telling error explaining the chain above. In an interactive terminal it then offers to run `neonctl link` in the current folder so you can pick (or create) a project on the spot; once linked, it continues and pins the requested branch. In non-interactive contexts (CI or no TTY) it exits with a non-zero code and the same guidance instead of prompting.
+
+The resolved branch id is then written to the same `.neon` file that `link` and `set-context` use:
+
+```bash
+$ neonctl checkout main --project-id polished-snowflake-12345678
+INFO: Checked out branch br-main-branch-87654321 on project polished-snowflake-12345678. Updated /path/to/cwd/.neon.
+
+$ cat .neon
+{
+  "orgId": "org-abc123",
+  "projectId": "polished-snowflake-12345678",
+  "branchId": "br-main-branch-87654321"
+}
+```
+
+**Where `.neon` lives**: `link` (and `set-context`) write `.neon` into the **current working directory** by default. If an existing `.neon` is found in any parent directory, that file is reused — so commands run from a sub-directory of a linked project still pick up the project's context. To pin the location explicitly, pass `--context-file <path>`.
+
+**`.gitignore` scaffolding**: when `.neon` is **created** for the first time, the CLI also makes sure a `.gitignore` sits alongside it listing `.neon`. If `.gitignore` doesn't exist it's created with a single `.neon` line; if it does exist, `.neon` is appended only when missing (no duplicates, your other entries are left alone). On subsequent updates to an existing `.neon`, `.gitignore` is left untouched — so if you deliberately un-ignore `.neon` (e.g. to commit shared context), the entry is not re-added on every command.
+
 ## Commands
 
-| Command                                                                    | Subcommands                                                                                 | Description                  |
-| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------- |
-| [auth](https://neon.com/docs/reference/cli-auth)                           |                                                                                             | Authenticate                 |
-| [projects](https://neon.com/docs/reference/cli-projects)                   | `list`, `create`, `update`, `delete`, `get`                                                 | Manage projects              |
-| [ip-allow](https://neon.com/docs/reference/cli-ip-allow)                   | `list`, `add`, `remove`, `reset`                                                            | Manage IP Allow              |
-| [me](https://neon.com/docs/reference/cli-me)                               |                                                                                             | Show current user            |
-| [branches](https://neon.com/docs/reference/cli-branches)                   | `list`, `create`, `rename`, `add-compute`, `set-default`, `set-expiration`, `delete`, `get` | Manage branches              |
-| [databases](https://neon.com/docs/reference/cli-databases)                 | `list`, `create`, `delete`                                                                  | Manage databases             |
-| [roles](https://neon.com/docs/reference/cli-roles)                         | `list`, `create`, `delete`                                                                  | Manage roles                 |
-| [operations](https://neon.com/docs/reference/cli-operations)               | `list`                                                                                      | Manage operations            |
-| [connection-string](https://neon.com/docs/reference/cli-connection-string) |                                                                                             | Get connection string        |
-| [set-context](https://neon.com/docs/reference/cli-set-context)             |                                                                                             | Set context for session      |
-| [completion](https://neon.com/docs/reference/cli-completion)               |                                                                                             | Generate a completion script |
+| Command                                                                    | Subcommands                                                                                 | Description                    |
+| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------ |
+| [auth](https://neon.com/docs/reference/cli-auth)                           |                                                                                             | Authenticate                   |
+| [projects](https://neon.com/docs/reference/cli-projects)                   | `list`, `create`, `update`, `delete`, `get`                                                 | Manage projects                |
+| [ip-allow](https://neon.com/docs/reference/cli-ip-allow)                   | `list`, `add`, `remove`, `reset`                                                            | Manage IP Allow                |
+| [me](https://neon.com/docs/reference/cli-me)                               |                                                                                             | Show current user              |
+| [branches](https://neon.com/docs/reference/cli-branches)                   | `list`, `create`, `rename`, `add-compute`, `set-default`, `set-expiration`, `delete`, `get` | Manage branches                |
+| [databases](https://neon.com/docs/reference/cli-databases)                 | `list`, `create`, `delete`                                                                  | Manage databases               |
+| functions                                                                  | `deploy`, `list`, `get`, `delete`                                                           | Manage Neon Functions          |
+| [roles](https://neon.com/docs/reference/cli-roles)                         | `list`, `create`, `delete`                                                                  | Manage roles                   |
+| [operations](https://neon.com/docs/reference/cli-operations)               | `list`                                                                                      | Manage operations              |
+| [connection-string](https://neon.com/docs/reference/cli-connection-string) |                                                                                             | Get connection string          |
+| psql                                                                       |                                                                                             | Connect to a database via psql |
+| [set-context](https://neon.com/docs/reference/cli-set-context)             |                                                                                             | Set context for session        |
+| checkout                                                                   |                                                                                             | Pin a branch in `.neon`        |
+| [link](https://neon.com/docs/reference/cli-link)                           |                                                                                             | Link a directory to a project  |
+| [completion](https://neon.com/docs/reference/cli-completion)               |                                                                                             | Generate a completion script   |
 
 ## Global options
 
@@ -142,17 +353,19 @@ Global options are supported with any Neon CLI command.
 
 ## Contribute
 
+This repo uses [pnpm](https://pnpm.io). The required version is pinned in `.tool-versions` and `package.json`'s `packageManager` field. The simplest way to get the right version is [mise](https://mise.jdx.dev): `mise install` reads `.tool-versions` and installs Node and pnpm. Alternatives: `npm install -g pnpm@9.15.9`, or [Corepack](https://nodejs.org/api/corepack.html) (`corepack enable pnpm`).
+
 To run the CLI locally, execute the build command after making changes:
 
 ```shell
-bun install
-bun run build
+pnpm install
+pnpm run build
 ```
 
 To develop continuously:
 
 ```shell
-bun run watch
+pnpm run watch
 ```
 
 To run commands from the local build, replace the `neonctl` command with `node dist`; for example:
@@ -160,3 +373,16 @@ To run commands from the local build, replace the `neonctl` command with `node d
 ```shell
 node dist branches --help
 ```
+
+### Embedded psql tests
+
+The embedded TypeScript psql implementation has its own conformance test suite that runs the same scripts against the embedded psql and a reference `psql` binary, then diffs the output.
+
+```shell
+bun run test:conformance         # run against $PSQL_BINARY (defaults to the system psql)
+bun run test:conformance:matrix  # run across PG 14/15/16/17/18 locally (requires Docker)
+```
+
+## Releasing
+
+Maintainers: see [`RELEASING.md`](./RELEASING.md) for the two-stage publish flow.

package/analytics.js

@@ -84,10 +84,13 @@ export const analyticsMiddleware = async (args) => {
         },
     });
 };
-export const closeAnalytics = async () => {
+export const closeAnalytics = async (opts) => {
     if (client) {
         log.debug('Flushing CLI analytics');
-        await client.closeAndFlush();
+        // `timeout` bounds how long we wait for in-flight events to flush so a
+        // slow / unreachable track.neon.tech can't hang a short-lived command
+        // (e.g. the psql launch path, which flushes here before process.exit).
+        await client.closeAndFlush(opts);
         log.debug('Flushed CLI analytics');
     }
 };

package/commands/branches.js

@@ -75,6 +75,12 @@ export const builder = (argv) => argv
         describe: 'Connect to a new branch via psql',
         default: false,
     },
+    fallback: {
+        type: 'boolean',
+        describe: 'Force the embedded TypeScript psql fallback (for testing)',
+        default: false,
+        hidden: true,
+    },
     annotation: {
         type: 'string',
         hidden: true,
@@ -325,7 +331,9 @@ const create = async (props) => {
         }
         const connection_uri = data.connection_uris[0].connection_uri;
         const psqlArgs = props['--'];
-        await psql(connection_uri, psqlArgs);
+        await psql(connection_uri, psqlArgs, {
+            mode: props.fallback ? 'ts' : 'auto',
+        });
     }
 };
 const rename = async (props) => {

package/commands/checkout.js

@@ -0,0 +1,249 @@
+import { EndpointType } from '@neondatabase/api-client';
+import { isAxiosError } from 'axios';
+import prompts from 'prompts';
+import { retryOnLock } from '../api.js';
+import { applyContext, readContextFile } from '../context.js';
+import { isCi } from '../env.js';
+import { log } from '../log.js';
+import { fillSingleProject } from '../utils/enrichers.js';
+import { looksLikeBranchId } from '../utils/formats.js';
+import { handler as linkHandler } from './link.js';
+// The positional is optional: omitting it in an interactive terminal opens a
+// branch picker. In non-interactive contexts a missing branch is an error.
+export const command = 'checkout [id|name]';
+export const describe = 'Pin a branch in the local context (.neon) so subsequent commands target it';
+export const builder = (argv) => argv
+    .usage('$0 checkout [id|name] [options]')
+    .positional('id', {
+    describe: 'Branch name or id to check out. Omit to pick interactively from the list of branches.',
+    type: 'string',
+})
+    .options({
+    'project-id': {
+        describe: 'Project ID',
+        type: 'string',
+    },
+})
+    .example([
+    [
+        '$0 checkout',
+        'Pick a branch interactively from the project in the closest .neon file',
+    ],
+    [
+        '$0 checkout main',
+        'Pin the branch named "main" in the closest .neon file',
+    ],
+    [
+        '$0 checkout br-cool-snow-12345678 --project-id project-id-123',
+        'Pin a branch by id for an explicit project',
+    ],
+]);
+export const handler = async (props) => {
+    // Branch listing is project-scoped, so `projectId` is the only thing
+    // `checkout` actually needs. Resolve it through the standard chain
+    // (--project-id flag > .neon file > single-project auto-detect); when
+    // nothing resolves, fall back to an interactive `neonctl link`.
+    const projectId = await resolveProjectId(props);
+    const branchId = await resolveBranchId(props, projectId);
+    const orgId = await resolveOrgId(props, projectId);
+    // `checkout` is a thin helper over `set-context`. It fully "heals" the
+    // context file: it always (re)writes `projectId`, `branchId`, and `orgId`
+    // (when the project has one) so a `.neon` that drifted or was missing fields
+    // ends up complete and consistent after checkout.
+    applyContext(props.contextFile, {
+        projectId,
+        ...(orgId ? { orgId } : {}),
+        branchId,
+    });
+    log.info('Checked out branch %s on project %s%s. Updated %s.', branchId, projectId, orgId ? ` (org ${orgId})` : '', props.contextFile);
+};
+/**
+ * Resolve the branch id to check out.
+ *
+ * - Branch **id** (`br-…`): looked up by id. A non-existent id is a hard "not
+ *   found" error — we never offer to create one, since ids are server-assigned.
+ * - Branch **name**: looked up by name. If it doesn't exist, in an interactive
+ *   terminal we offer to create it (like `neonctl branch create --name <name>`);
+ *   in a non-interactive context it's the usual "not found" error.
+ * - **Omitted**: open an interactive picker listing the project's branches (TTY
+ *   only); in a non-interactive context a missing branch is a hard error.
+ */
+const resolveBranchId = async (props, projectId) => {
+    const branches = (await props.apiClient.listProjectBranches({ projectId }))
+        .data.branches;
+    if (!props.id) {
+        return pickBranchInteractively(branches, projectId);
+    }
+    const ref = props.id;
+    // A `br-…` value is an id; match strictly by id and never offer to create.
+    if (looksLikeBranchId(ref)) {
+        const byId = branches.find((b) => b.id === ref);
+        if (byId) {
+            return byId.id;
+        }
+        throw new Error(notFoundMessage(ref, branches));
+    }
+    const byName = branches.find((b) => b.name === ref);
+    if (byName) {
+        return byName.id;
+    }
+    // Name not found: offer to create it interactively, mirroring `branch create`.
+    if (isCi() || !process.stdout.isTTY) {
+        throw new Error(notFoundMessage(ref, branches));
+    }
+    log.error(notFoundMessage(ref, branches));
+    const { create } = await prompts({
+        type: 'confirm',
+        name: 'create',
+        message: `Branch "${ref}" does not exist. Create it now?`,
+        initial: true,
+    });
+    if (!create) {
+        throw new Error(`Aborted: branch "${ref}" was not found and not created.`);
+    }
+    return createBranch(props, projectId, ref, branches);
+};
+const notFoundMessage = (ref, branches) => `Branch ${ref} not found.\nAvailable branches: ${branches
+    .map((b) => b.name)
+    .join(', ')}`;
+const pickBranchInteractively = async (branches, projectId) => {
+    if (isCi() || !process.stdout.isTTY) {
+        throw new Error('No branch specified. Pass a branch name or id (e.g. `neonctl checkout main`), ' +
+            'or run interactively to pick one from a list.');
+    }
+    if (branches.length === 0) {
+        throw new Error(`No branches found for project ${projectId}.`);
+    }
+    const defaultIndex = Math.max(0, branches.findIndex((b) => b.default));
+    const { branchId } = await prompts({
+        type: 'select',
+        name: 'branchId',
+        message: 'Which branch would you like to check out?',
+        choices: branches.map((b) => ({
+            title: `${b.default ? '✱ ' : ''}${b.name} (${b.id})`,
+            value: b.id,
+        })),
+        initial: defaultIndex,
+    });
+    if (!branchId) {
+        throw new Error('Aborted: no branch selected.');
+    }
+    return branchId;
+};
+/**
+ * Create a branch with the same defaults as `neonctl branch create --name <name>`:
+ * branched from the project's default branch with a read-write compute endpoint.
+ */
+const createBranch = async (props, projectId, name, branches) => {
+    const defaultBranch = branches.find((b) => b.default);
+    if (!defaultBranch) {
+        throw new Error('No default branch found');
+    }
+    const { data } = await retryOnLock(() => props.apiClient.createProjectBranch(projectId, {
+        branch: { name, parent_id: defaultBranch.id },
+        endpoints: [{ type: EndpointType.ReadWrite }],
+    }));
+    if (defaultBranch.protected) {
+        log.warning('The parent branch is protected; a unique role password has been generated for the new branch.');
+    }
+    log.info('Created branch %s (%s).', data.branch.name, data.branch.id);
+    return data.branch.id;
+};
+/**
+ * Resolve the org id to heal into the context file.
+ *
+ * Prefer an org id we already know (from `--org-id`, the `.neon` file, or a
+ * freshly-run `link`). Otherwise look it up from the project itself so the
+ * `.neon` file ends up with an accurate `orgId` even when it was previously
+ * missing. Projects on a personal account have no org; in that case (or if the
+ * lookup fails for a non-auth reason) we return `undefined` and simply omit the
+ * field rather than failing the checkout.
+ */
+const resolveOrgId = async (props, projectId) => {
+    if (props.orgId) {
+        return props.orgId;
+    }
+    try {
+        const { data } = await props.apiClient.getProject(projectId);
+        return data.project.org_id ?? undefined;
+    }
+    catch (err) {
+        if (isAxiosError(err) && err.response?.status === 401) {
+            throw err;
+        }
+        log.debug('checkout: could not resolve org id for project %s: %s', projectId, err instanceof Error ? err.message : String(err));
+        return undefined;
+    }
+};
+/**
+ * Resolve the project id `checkout` should target.
+ *
+ * `props.projectId` is already populated from the `--project-id` flag or the
+ * closest `.neon` file (via the global `enrichFromContext` middleware). When
+ * it's still missing we try to auto-detect a single project (same behaviour as
+ * `branches` / `connection-string`). If that fails we surface a telling error
+ * and, in an interactive terminal, offer to run `neonctl link` in the current
+ * folder so the user can pick a project/branch without having to re-run the
+ * command by hand.
+ */
+const resolveProjectId = async (props) => {
+    if (props.projectId) {
+        return props.projectId;
+    }
+    const autoDetected = await tryAutoDetectProject(props);
+    if (autoDetected) {
+        return autoDetected;
+    }
+    const missingProjectMessage = 'Could not determine which Neon project to check out a branch from. ' +
+        'Provide one via the --project-id flag ' +
+        'or a .neon file (created by `neonctl link` / `neonctl set-context`).';
+    if (isCi() || !process.stdout.isTTY) {
+        throw new Error(missingProjectMessage);
+    }
+    log.error(missingProjectMessage);
+    const { runLink } = await prompts({
+        type: 'confirm',
+        name: 'runLink',
+        message: 'Run `neonctl link` in the current folder to pick a project now?',
+        initial: true,
+    });
+    if (!runLink) {
+        throw new Error('Aborted: no project selected. Re-run with --project-id or link a project first.');
+    }
+    await linkHandler({
+        ...props,
+        agent: false,
+        yes: false,
+    });
+    const linked = readContextFile(props.contextFile);
+    if (!linked.projectId) {
+        throw new Error('Linking did not produce a project id. Re-run `neonctl checkout` once the directory is linked.');
+    }
+    // Carry the freshly-linked org id forward so the merge below keeps it.
+    if (linked.orgId) {
+        props.orgId = linked.orgId;
+    }
+    return linked.projectId;
+};
+/**
+ * Best-effort single-project auto-detection. Returns the project id when the
+ * API key maps to exactly one project, or `undefined` when the project can't be
+ * determined unambiguously (zero or multiple projects) so the caller can fall
+ * back to the interactive `link` flow.
+ */
+const tryAutoDetectProject = async (props) => {
+    try {
+        const filled = await fillSingleProject(props);
+        return filled.projectId;
+    }
+    catch (err) {
+        // `fillSingleProject` throws on "No projects found" / "Multiple projects
+        // found" — both mean we can't pick a project automatically. Network/auth
+        // errors are real and should surface to the user.
+        if (isAxiosError(err)) {
+            throw err;
+        }
+        log.debug('checkout: could not auto-detect a single project: %s', err instanceof Error ? err.message : String(err));
+        return undefined;
+    }
+};

package/commands/connection_string.js

@@ -3,7 +3,12 @@ import { branchIdFromProps, fillSingleProject } from '../utils/enrichers.js';
 import { writer } from '../writer.js';
 import { psql } from '../utils/psql.js';
 import { parsePITBranch } from '../utils/point_in_time.js';
-const SSL_MODES = ['require', 'verify-ca', 'verify-full', 'omit'];
+export const SSL_MODES = [
+    'require',
+    'verify-ca',
+    'verify-full',
+    'omit',
+];
 export const command = 'connection-string [branch]';
 export const aliases = ['cs'];
 export const describe = 'Get connection string';
@@ -54,6 +59,12 @@ export const builder = (argv) => {
             describe: 'Connect to a database via psql using connection string',
             default: false,
         },
+        fallback: {
+            type: 'boolean',
+            describe: 'Force the embedded TypeScript psql fallback (for testing)',
+            default: false,
+            hidden: true,
+        },
         ssl: {
             type: 'string',
             choices: SSL_MODES,
@@ -141,7 +152,9 @@ export const handler = async (props) => {
     }
     if (props.psql) {
         const psqlArgs = props['--'];
-        await psql(connectionString.toString(), psqlArgs);
+        await psql(connectionString.toString(), psqlArgs, {
+            mode: props.fallback ? 'ts' : 'auto',
+        });
     }
     else if (props.extended) {
         writer(props).end({