Skip to content

Improve neon init onboarding and preserve fields on .neon writes - #431

Draft
philip wants to merge 1 commit into
mainfrom
neon-init-and-context
Draft

Improve neon init onboarding and preserve fields on .neon writes#431
philip wants to merge 1 commit into
mainfrom
neon-init-and-context

Conversation

@philip

@philip philip commented Aug 13, 2026

Copy link
Copy Markdown
Contributor

Update

Split this up as requested. The three independent pieces are now their own PRs off main:

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 init had drifted from the current CLI. It probed for the retired
neonctl alias, so on machines with the neon CLI installed it failed to
detect 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, 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 alongside the driver-based verification.
Dependencies are now installed before linking, so any env pull can safely import a
project neon.ts. The --preview path is left as is.

Separately, and more broadly than init: writing .neon through link, checkout,
or set-context now preserves fields it does not own, so a single neon link no
longer overwrites init's in-progress state. neon link --clear still resets the file.

Verified end-to-end against a live backend: the rewritten init e2e test drives
neon link through project creation, confirms .neon gets org + project + branch,
and that env pull writes a real DATABASE_URL.

Follow-up (not in this PR)

Making init fully backend-friendly is deferred: dropping the --preview gating so
the 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 a neon.ts, and the services
it declares under defineConfig's preview field should work without that preview
grouping once GA.

The db and status init phases look like leftovers: the orchestrator routes
onboarding to getting-started and never to them, and nothing in the repo chains to
status, yet they still carry the old hand-rolled project-creation pattern. Pending
a check that no external skill references the db step, they are candidates for
removal.

This pull request and its description were written by Isaac.

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
@philip

philip commented Aug 13, 2026

Copy link
Copy Markdown
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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant