Improve neon init onboarding and preserve fields on .neon writes - #431
Draft
philip wants to merge 1 commit into
Draft
Improve neon init onboarding and preserve fields on .neon writes#431philip wants to merge 1 commit into
philip wants to merge 1 commit into
Conversation
neon init had drifted from the current CLI: it probed for the retired neonctl alias (so it failed to detect an installed neon CLI and tried to reinstall), hand-edited .neon instead of using neon link (and never recorded the branch), and linked to doc pages that had since moved. This reworks the standard flow to detect and install neon, delegate org/project selection and the .neon write to `neon link --agent` (which records org, project, and branch), point the doc references at current pages, and suggest `neon psql` as a quick connection check. The --preview path is unchanged. Separately, writing .neon through link, checkout, or set-context now preserves fields it does not own, so a neon link no longer clobbers init's in-progress state; neon link --clear still resets the file. Co-authored-by: Isaac
Contributor
Author
|
I created this before seeing #428 which changes things. Still, if 428 is merged, there are bits here worth merging (e.g., neonctl->neon and the link fixes). |
This was referenced Aug 14, 2026
philip
marked this pull request as draft
August 14, 2026 13:06
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Update
Split this up as requested. The three independent pieces are now their own PRs off main:
neonCLI, notneonctl. This is the isolated one to merge now..neonwrites. The non-destructive context write.Each is single-purpose and reviewable on its own. #432 and #433 have no dependencies; #434 is for doc URLs. Setting #431 to Draft.
What remains here is the fourth piece: rewiring getting-started to delegate to neon link (plus the neon psql connection check and installing deps before env pull). I stopped here as it depends on #433 for correctness and overlaps with the minimal-init redesign in #428.
Overview
neon inithad drifted from the current CLI. It probed for the retiredneonctlalias, so on machines with theneonCLI installed it failed todetect it and tried to reinstall; it hand-edited
.neon(missing the branch)rather than using
neon link; and it referenced doc pages that had since moved.This reworks the standard onboarding flow to detect and install
neon, delegateorg/project selection and the
.neonwrite toneon link --agent(which recordsorg, project, and branch), point the doc references at current pages, and suggest
neon psqlas a quick connection check alongside the driver-based verification.Dependencies are now installed before linking, so any env pull can safely import a
project
neon.ts. The--previewpath is left as is.Separately, and more broadly than init: writing
.neonthroughlink,checkout,or
set-contextnow preserves fields it does not own, so a singleneon linknolonger overwrites init's in-progress state.
neon link --clearstill resets the file.Verified end-to-end against a live backend: the rewritten init e2e test drives
neon linkthrough project creation, confirms.neongets org + project + branch,and that
env pullwrites a realDATABASE_URL.Follow-up (not in this PR)
Making init fully backend-friendly is deferred: dropping the
--previewgating sothe bootstrap path works for everyone once the platform features are GA, and adding
a plain-Postgres bootstrap template (today's starters all require Functions, Object
Storage, or the AI Gateway). That template also needs a matching example added to
neondatabase/examples. Relatedly, init could scaffold aneon.ts, and the servicesit declares under
defineConfig'spreviewfield should work without thatpreviewgrouping once GA.
The
dbandstatusinit phases look like leftovers: the orchestrator routesonboarding to
getting-startedand never to them, and nothing in the repo chains tostatus, yet they still carry the old hand-rolled project-creation pattern. Pendinga check that no external skill references the
dbstep, they are candidates forremoval.
This pull request and its description were written by Isaac.