---
schema_version: 1
route: /t/neonctl.md
tool: "neonctl"
---

# sincecutoff.com /t/neonctl — Neon CLI

- name: Neon CLI
- kind: cli
- children: none
- homepage: <https://github.com/neondatabase/neonctl>

Changes to the tools coding agents drive, since a model's training cutoff, each linked to its first-party source. Check installed versions and limitations before acting; a cutoff date does not establish what a model knows.
Original editorial content: [Apache 2.0](https://sincecutoff.com/v1/data-license.txt), by [0xPatrick](https://0xpatrick.dev). Preserve applicable license and [NOTICE](https://sincecutoff.com/notice.txt) attribution when redistributing. Third-party source text and examples retain their own rights. [License scope and attribution](https://sincecutoff.com/v1/license.json).
To stay current, read the changes feed: [`/v1/changes.md?tool=neonctl`](https://sincecutoff.com/v1/changes.md?tool=neonctl) (or `.json`), adding `since=YYYY-MM-DD` for your training cutoff. Entries for registered children are included; the registry itself is `/v1/tools.json`. How to page and save your place: [llms.txt](https://sincecutoff.com/llms.txt).

### neonctl bootstrap scaffolds from Neon templates (2026-06-12)
- slug: neonctl-bootstrap-scaffolds-from-neon-templates-4e84900bd68e
- score: 0.98

How to use it:

When scaffolding a repository from a Neon template, run `neonctl bootstrap <target> --template <id>`; use `.` for the current directory. The target must be empty unless you pass `--force`.

Examples:

```
neonctl bootstrap <target> --template <id>
```

- why_it_matters: Scaffold a repository from a Neon template.
- sources: <https://github.com/neondatabase/neonctl/releases/tag/v2.25.0>, <https://github.com/neondatabase/neonctl/blob/v2.25.0/README.md>
- gotchas: "Version: v2.25.0"; "<target> (required): Destination directory, or `.` for the current directory."; "--template <id> (required): Selects a template; required for non-interactive use. Interactive terminals can instead choose from a list."; "--force: Allows scaffolding when the target directory is not empty; a lone `.git` is ignored."; "Prerequisite: Install `neonctl`; the README documents npm install and requires Node.js 18.0 or higher for that installation method."; "Prerequisite: No Neon login is required; bootstrap downloads template files from GitHub."

### neonctl bucket object put uploads a file through a presigned URL (2026-06-12)
- slug: neonctl-bucket-object-put-uploads-a-file-through-a-presigned-url-f73c9f7cde76
- score: 0.97

How to use it:

When the artifact is at most 104857600 bytes, upload it to an existing bucket with `neonctl bucket object put <bucket>/<key> --file <path> [--content-type <ct>]`; the CLI obtains a presigned PUT URL and streams the file. The v2.25.0 release notes document the upload feature and 100 MB cap.

Examples:

```
neonctl bucket object put <bucket>/<key> --file <path> [--content-type <ct>]
```

- why_it_matters: Upload a repository artifact to a Neon object storage bucket while working with an existing neonctl coding workflow.
- sources: <https://github.com/neondatabase/neonctl/releases/tag/v2.25.0>, <https://github.com/neondatabase/neonctl/pull/530>
- gotchas: "Version: v2.25.0"; "<bucket>/<key> (required): Target bucket and object key; release notes say it is split on the first `/` and an empty key is rejected."; "--file <path> (required): Path to the file to upload. Files above 104857600 bytes are rejected client-side."; "--content-type <ct>: Optional content type sent with the upload request."; "Files above 104857600 bytes are rejected client-side with exit 1 and no HTTP request."; "Multipart upload is out of scope."; "The bucket target uses `<bucket>/<key>`, split on the first `/`; an empty key is rejected client-side."; "The presigned download operation is API-only; `object get` continues to stream through the console."

### neonctl link and checkout select a branch and pull its environment (2026-06-10)
- slug: neonctl-link-and-checkout-select-a-branch-and-pull-its-environment-6263c05d5965
- score: 0.97

How to use it:

When linking an existing project with multiple branches, run `neonctl link` and select a branch; single-branch projects are pinned automatically. After `link` or `checkout` pins a branch, it pulls Neon environment variables by default; pass `--no-env-pull` to skip the pull, or run `neonctl env pull` to refresh them.

Examples:

```
neonctl link
```

```
neonctl checkout <branch> --project-id <project_id>
```

```
neonctl env pull --branch <id|name> --file <path>
```

- why_it_matters: Link a project or switch its branch and prepare its Neon environment for local development.
- before: After linking or checking out a branch, run `env pull` separately to write the branch’s Neon environment variables to a local dotenv file.
- sources: <https://github.com/neondatabase/neonctl/releases/tag/v2.24.1>, <https://github.com/neondatabase/neonctl/pull/524>, <https://github.com/neondatabase/neonctl/blob/v2.24.1/README.md>
- gotchas: "Version: v2.24.1"; "--no-env-pull: Skip the automatic environment pull after `link` or `checkout`."; "<branch>: For `checkout`, the branch name or ID to pin. Omit in an interactive terminal to choose from a list; required in non-interactive contexts."; "--project-id <id>: Select the project for `checkout`; otherwise context or project auto-detection may resolve it."; "--branch <id|name>: For `env pull`, target a branch other than the one in the closest `.neon` context file."; "--file <path>: Choose the dotenv file for `env pull`; default is existing `.env`, otherwise `.env.local`."; "Prerequisite: Authenticate with `neonctl auth`, or provide an API key with `--api-key`; unauthenticated CLI commands launch browser authentication automatically."; "Prerequisite: `neonctl link` requires the CLI to resolve or be given an organization and project; `checkout` requires a resolvable project."; "The selector is for linking an existing project with more than one branch; a single-branch project is pinned automatically."; "New projects pin their default branch."; "Non-interactive/flag mode and the `--agent` state machine are unchanged."; "Only Neon-managed keys are written; any other lines in the dotenv file are preserved."; "An existing `.env` is used when present, otherwise `.env.local`; `--file <path>` overrides the target file."; "The branch comes from the closest `.neon` file unless `--branch <id|name>` targets another branch."; "A pull failure does not undo the checkout; it is surfaced as a warning."

### neon config status, plan, apply, and deploy reconcile neon.ts policies (2026-06-09)
- slug: neon-config-status-plan-apply-and-deploy-reconcile-neon-ts-policies-467b448bbc6a
- score: 0.97

How to use it:

When reconciling a branch from a repository policy, define the policy in `neon.ts`; run `neon config status` to inspect it, `neon config plan` to preview changes, and `neon config apply` (or `neon deploy`) to apply them.

Examples:

```
neon config status [--project-id <id>] [--branch <id|name>] [--config <path>]
```

```
neon config plan [--project-id <id>] [--branch <id|name>] [--config <path>]
```

```
neon config apply [--project-id <id>] [--branch <id|name>] [--config <path>] [--update-existing] [--allow-protected]
```

- why_it_matters: Inspect or reconcile a Neon branch's desired state from a repository policy.
- sources: <https://github.com/neondatabase/neonctl/releases/tag/v2.24.0>, <https://github.com/neondatabase/neonctl/pull/518>, <https://github.com/neondatabase/neonctl/blob/v2.24.0/README.md>
- gotchas: "Version: v2.24.0"; "--project-id <id>: Selects the project; otherwise the closest `.neon` file’s `projectId` is used, then a sole project accessible to the API key is auto-detected."; "projectId: Project ID in the closest `.neon` file; used after `--project-id`."; "--branch <id|name>: Selects a branch; defaults to the project’s default branch."; "--config <path>: Selects the policy file; otherwise neonctl walks up from the current directory for `neon.ts`."; "--update-existing: For apply/deploy, auto-confirms overriding existing remote settings; without it, drift in compute, TTL, or `protected` is a conflict and apply makes no changes."; "--allow-protected: For apply/deploy, auto-confirms applying to a branch Neon marks protected."; "--env <path>: Not documented in the v2.24.0 README; details not found."; "Prerequisite: Install neonctl; the README lists Node.js 18.0 or higher for npm installation."; "Prerequisite: Authenticate with `neonctl auth` or provide an API key with `--api-key`."; "Without `--update-existing`, drift on settings already present remotely (compute, TTL, `protected`) is reported as a conflict and apply makes no changes until resolved or the flag is passed."; "If the API key maps to exactly one project, that project is auto-detected when project resolution remains unresolved."; "The branch defaults to the project's default branch when `--branch` is omitted."; "The policy can include Preview features such as Functions and buckets."

### neon dev hot-adds and reconciles functions when neon.ts changes (2026-06-09)
- slug: neon-dev-hot-adds-and-reconciles-functions-when-neon-ts-changes-0127f88ca795
- score: 0.94

How to use it:

When adding, removing, or changing functions while `neon dev` runs in config mode, edit `neon.ts`; the CLI reconciles functions by slug, hot-adding and removing servers and restarting only functions whose configuration changed. This applies only when running from `neon.ts`, not in single-`--source` mode.

Examples:

```
neon dev
```

- why_it_matters: Add, remove, or change a function in a repository's neon.ts while its local dev servers are running.
- before: Before this change, adding a function required fully restarting `neon dev`.
- sources: <https://github.com/neondatabase/neonctl/releases/tag/v2.24.0>, <https://github.com/neondatabase/neonctl/pull/520>, <https://github.com/neondatabase/neonctl/blob/v2.24.0/src/commands/dev.ts>, <https://github.com/neondatabase/neonctl/blob/v2.24.0/README.md>
- gotchas: "Version: v2.24.0"; "`--source <path>`: Selects single-function mode; omit it to serve functions declared in `neon.ts`. Config reconciliation does not apply in single-source mode."; "`preview.functions` (required): Functions declared here are served in config mode; `neon.ts` with no functions to serve produces an error."; "function `slug` (required): Functions are keyed by slug when reconciling changes."; "function `source` (required): Function source path; a change restarts that function."; "function `dev.port`: Explicit port; a change restarts that function. Without it, a free port is selected unless `dev.portless` is used."; "function `dev.portless`: Enables portless mode; a change restarts that function. When enabled, the `portless` command must be on `PATH`."; "function `env`: Function-specific environment values layer over the shared branch environment; a change restarts that function."; "Prerequisite: Install the Neon CLI; the v2.24.0 README says npm installation requires Node.js 18.0 or higher."; "Prerequisite: Config mode requires a `neon.ts` declaring at least one function under `preview.functions`."; "Prerequisite: If any function uses `dev.portless: true`, install the `portless` command and make it available on `PATH`."; "This behavior applies only in `neon.ts` config mode; single `--source` mode is unaffected."

### neon env pull writes branch environment variables to .env (2026-06-09)
- slug: neon-env-pull-writes-branch-environment-variables-to-env-5c5c44422132
- score: 0.92

How to use it:

When you need a local dotenv file populated with a Neon branch’s variables, run `neonctl env pull` from a directory with Neon context. It writes to `.env` if present, otherwise `.env.local`, and preserves other lines.

Examples:

```
neonctl env pull
```

- why_it_matters: Populate a repository's local environment file with variables from a Neon branch.
- sources: <https://github.com/neondatabase/neonctl/releases/tag/v2.24.0>, <https://github.com/neondatabase/neonctl/pull/518>, <https://github.com/neondatabase/neonctl/blob/v2.24.0/README.md>
- gotchas: "Version: v2.24.0"; "--file <path>: Write to the specified dotenv file instead of the default selection."; "--branch <id|name>: Target another branch instead of the branch in the closest `.neon` file."; "Prerequisite: Authenticate with `neonctl auth` or supply an API key with `--api-key <neon_api_key>`; unauthenticated CLI commands launch browser authentication automatically."; "Prerequisite: A linked Neon project context is needed to resolve the branch; the branch comes from the closest `.neon` file unless `--branch` is supplied."; "The operation writes a branch's variables and preserves other lines in the file."

### neonctl neon-auth enable, status, and disable commands (2026-06-08)
- slug: neonctl-neon-auth-enable-status-and-disable-commands-902db5a6c8a5
- score: 0.95

How to use it:

To manage Managed Better Auth on a branch, run `neon neon-auth enable`, `status`, or `disable`. The CLI resolves project and branch context when the corresponding flags are omitted, selecting a sole match or prompting when multiple options exist.

Examples:

```
neon neon-auth enable
```

```
neon neon-auth status
```

```
neon neon-auth disable
```

- why_it_matters: Manage Neon Auth for a project branch from the CLI.
- sources: <https://github.com/neondatabase/neonctl/releases/tag/v2.23.0>, <https://github.com/neondatabase/neonctl/pull/458>, <https://github.com/neondatabase/website/blob/main/content/docs/cli/neon-auth.md>, <https://github.com/neondatabase/neonctl>
- gotchas: "Version: v2.23.0"; "--project-id: Identifies the project; if omitted, CLI uses context, auto-selects when only one option exists, or asks for the flag."; "--branch: Identifies the branch; if omitted, CLI uses context, auto-selects when only one option exists, or asks for the flag."; "--delete-data: For `disable`, permanently deletes Managed Better Auth data and schema. The docs do not state whether this flag has an explicit value."; "Prerequisite: Authenticate with the Neon CLI; an unauthenticated command launches browser authentication. Alternatively, pass an API key with `--api-key`."; "Prerequisite: The documented CLI installation requires Node.js 18.0 or higher when installing with npm."; "All operations are branch-scoped."

### neonctl checkout pins a branch in .neon (2026-06-04)
- slug: neonctl-checkout-pins-a-branch-in-neon-28add5af46b4
- score: 0.95

How to use it:

When switching a repository’s Neon context to a branch, run `neonctl checkout <id|name>`; it resolves the branch for the active project and updates `.neon` so subsequent commands use it. In CI or without a TTY, pass the branch explicitly.

Examples:

```
neonctl checkout <id|name>
```

```
neonctl checkout <branch> --project-id <project_id>
```

- why_it_matters: Switch a repository’s Neon CLI context to the branch being worked on.
- before: Use `neonctl set-context` to write `.neon` context directly; checkout is documented as a focused helper over `set-context` for switching branches.
- sources: <https://github.com/neondatabase/neonctl/releases/tag/v2.22.2>, <https://github.com/neondatabase/neonctl/pull/497>, <https://github.com/neondatabase/neonctl/blob/v2.22.2/README.md>
- gotchas: "Version: v2.22.2"; "[id|name]: Branch ID or name. Omit only in an interactive terminal to choose from a branch list; `br-…` is treated as an ID. A missing name may be offered for creation interactively."; "--project-id <id>: Select the project; takes precedence over the closest `.neon` project ID and single-project API-key auto-detection."; "--org-id <id>: Organization ID; used to identify the organization when supplied. Otherwise checkout can use the existing `.neon` value or look it up from the project."; "--api-key <neon_api_key>: Authenticates the command with a Neon API key instead of `neonctl auth`."; "Prerequisite: Install the Neon CLI; the README documents `npm i -g neonctl` and requires Node.js 18.0 or higher for npm installation."; "Prerequisite: Authenticate with `neonctl auth` or pass `--api-key`."; "Prerequisite: In CI or without a TTY, pass the branch explicitly."; "An omitted branch is supported only in an interactive terminal; in CI or without a TTY, pass a branch explicitly."; "A `br-…` value is treated as an id and matched strictly; a nonexistent id produces a not-found error and is not created."; "A missing name can be created only through the interactive-terminal offer; in a non-interactive context a missing name produces a not-found error."; "Project resolution order is `--project-id`, the closest `.neon`, then auto-detection when the API key maps to exactly one project."; "When a project has an organization, checkout writes `orgId` as well as `projectId` and `branchId`; when `orgId` is unknown it is looked up from the project."

### neonctl link binds a directory to a Neon project (2026-06-04)
- slug: neonctl-link-binds-a-directory-to-a-neon-project-329a57f36bfb
- score: 0.98

How to use it:

When you need subsequent `neonctl` commands in a directory or its subdirectories to use a Neon project context, run `neonctl link` there. Use interactive prompts, the documented flags or `--params` for scripts, or `--agent` for the JSON follow-up flow; the command writes `.neon` with organization, project, and default branch context.

Examples:

```
neonctl link
```

```
neonctl link --org-id <org-id> --project-id <project-id>
```

```
neonctl link --params '{"orgId":"<org-id>","projectName":"<project-name>","regionId":"<region-id>"}'
```

- why_it_matters: Link a repository directory to a Neon project so subsequent CLI commands can use that directory’s project context.
- before: Use the lower-level `neonctl set-context` command to write project context manually; `link` is documented as a wrapper around that primitive.
- sources: <https://github.com/neondatabase/neonctl/releases/tag/v2.22.2>, <https://github.com/neondatabase/neonctl/pull/473>, <https://github.com/neondatabase/neonctl/blob/v2.22.2/README.md>
- gotchas: "Version: v2.22.2"; "--org-id: Organization ID; used to choose the organization for linking or project creation."; "--project-id: Existing project ID to link."; "--project-name: Name for a project to create and link."; "--region-id: Region ID for the project being created; the agent flow can omit it to receive available regions."; "--params: JSON payload form of the linking parameters; documented keys are `orgId`, `projectName`, and `regionId`."; "--agent: Returns a JSON state-machine response with status, available options, and a follow-up command template."; "Prerequisite: Install neonctl; the v2.22.2 README specifies Node.js 18.0 or higher for the npm installation."; "Prerequisite: Authenticate with `neonctl auth` or provide a Neon API key with `--api-key` when running a CLI command."; "Interactive mode is the default."; "Non-interactive linking uses flags or `--params` JSON."; "Agent mode returns a JSON object with a status discriminator, available options, and a follow-up command."