Skip to main content
See what's recently landed on the Neon backend: Object Storage, Functions, AI Gateway, and more
/APIs & SDKs/Configuration commands/config

Neon CLI command: config

Manage a branch with a neon.ts policy: init, add, status, plan, and apply

View as Markdown

The config command manages a branch declaratively with a neon.ts policy file: scaffold a starter config, inspect the branch's live state, preview what an apply would change, and apply the policy. For the neon.ts file format, see the neon.ts reference.

Subcommands: add, apply, init, plan, status

The top-level neon deploy command is an alias for config apply, and neon status is an alias for config status.

neon config init

Scaffolds a starter neon.ts policy file in the current project and installs the @neon/config and @neon/env packages, so you can start managing a branch declaratively. The generated file uses the standard named defineConfig import from @neon/config/v1 and exports the result as the module default, for example:

neon.ts
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  // Declare your Neon services here
  auth: false,
  // Branch policy: per-branch tuning
  branch: (branch) => {
    if (branch.isDefault) {
      // Default branch: no overrides, uses project defaults
      return {};
    }
    if (!branch.exists) {
      // New non-default branches: auto-expire
      // Run `neon checkout <name>` to create a new branch with these settings
      return { ttl: "7d" };
    }
    // Existing branch: no changes
    return {};
  },
});

If a neon.ts, neon.mts, neon.js, or neon.mjs file already exists, config init is idempotent: it leaves that file untouched instead of overwriting hand-written policy.

By default, config init runs locally and does not call the Neon API. With --from-branch, it reads the branch's live state through the Neon API, so it needs your Neon credentials and a project. It picks your package manager (npm, pnpm, yarn, or bun) from the project's lockfile, or from how the command was invoked if there's no lockfile. Before installing, it makes sure node_modules/ is listed in your .gitignore, appending it if it's missing. Pass --no-install to skip installation and just print the command to run.

neon config init [options]
OptionDescriptionTypeDefaultRequired
--from-branchSeed neon.ts from a branch's live Neon state instead of asking. Uses the branch pinned in .neon, or --branch <name|id>, or the project's default branch. Needs credentials and a project.boolean—No
--installInstall @neon/config and @neon/env if they're missing. On by default; use --no-install to just print the command.booleantrueNo
--services, -s, --serviceServices the scaffolded neon.ts declares: postgres, auth, data-api, functions, object-storage, ai-gateway, realtime. Repeat the flag or comma-separate. postgres alone writes the starter policy; every branch has Postgres. Omitted: pick interactively on a terminal, starter policy in CI or without a TTY.array—No
--branchBranch ID or namestring—No
--project-idProject IDstring—No
neon config init

Pass --services to declare services in the file it scaffolds, for example neon config init --services auth,functions,realtime. This applies only when creating a new neon.ts; to add services to a file that already exists, use config add.

In a linked project, declaring the Data API makes config init check the branch's Data API and pick dataApi: true or the external form, as init does. If the check fails, it declares dataApi: true with auth: true and prints a warning.

For non-interactive setup, run it with package installation disabled, then install the printed dependencies yourself (or add them to your lockfile in a separate step):

neon config init --no-install
npm install @neon/config @neon/env

Use config init when you want a trusted starter artifact and package list. Hand-write neon.ts instead when you need a different filename/module format or want to avoid modifying files in the current directory.

tip

After running an interactive neon link, the CLI prompts you to run config init as its final step, unless the project already has a neon.ts file.

neon config add

Declares a service, function, or bucket in your neon.ts, creating the file if there isn't one. Where config init scaffolds a starter policy and leaves an existing file alone, config add edits an existing policy for you, including creating and registering a handler for a function. To declare services while first scaffolding the file, use config init --services instead.

neon config add <sub-command> [options]

Subcommands: ai-gateway, auth, bucket, data-api, function, realtime

config add runs entirely locally: it edits files, and never authenticates or resolves a project. Provisioning stays a separate neon config apply step.

It looks for your config in the project directory: the directory holding the nearest .neon file (found by searching up from the current directory), or the current directory when there's no .neon. A neon.ts in a parent directory no longer applies. When it finds none, it creates neon.ts there and installs the @neon/config and @neon/env packages; pass --no-install to print the install command instead. Editing an existing file never installs packages. Pass --config <path> to target a specific file; a path that doesn't exist is an error.

It edits the file in place, keeping your comments and formatting. It refuses edits it can't make safely, such as a graduated service still declared under the preview block, where it's a deprecated alias, and prints the lines to add by hand instead. Re-adding an already-enabled service exits 0 with "nothing to change"; a duplicate function slug or bucket name exits 1; a bare neon config add exits 1 and lists what you can add.

neon config add auth

Enables Managed Better Auth by setting auth: true.

neon config add auth [options]
OptionDescriptionTypeDefaultRequired
--configPath to the neon.ts to edit (defaults to the neon.ts next to .neon, or in cwd without one; created there when missing)string—No
--installInstall @neon/config and @neon/env when creating neon.ts. On by default; use --no-install to just print the command.booleantrueNo
--branchBranch ID or namestring—No
--project-idProject IDstring—No
neon config add auth

neon config add data-api

Enables the Data API by setting dataApi: true, and enables Managed Better Auth, which the default provider requires (it flips auth: false to true). An existing external auth provider is left unchanged.

neon config add data-api [options]
OptionDescriptionTypeDefaultRequired
--configPath to the neon.ts to edit (defaults to the neon.ts next to .neon, or in cwd without one; created there when missing)string—No
--installInstall @neon/config and @neon/env when creating neon.ts. On by default; use --no-install to just print the command.booleantrueNo
--branchBranch ID or namestring—No
--project-idProject IDstring—No
neon config add data-api

neon config add ai-gateway

Enables the AI Gateway by setting aiGateway: true.

neon config add ai-gateway [options]
OptionDescriptionTypeDefaultRequired
--configPath to the neon.ts to edit (defaults to the neon.ts next to .neon, or in cwd without one; created there when missing)string—No
--installInstall @neon/config and @neon/env when creating neon.ts. On by default; use --no-install to just print the command.booleantrueNo
--branchBranch ID or namestring—No
--project-idProject IDstring—No
neon config add ai-gateway

neon config add realtime

Enables Neon Realtime by setting preview.realtime: true. Pass --allowed-origin (repeatable) to set the browser origins allowed to connect instead, which writes preview.realtime: { allowedOrigins: [...] }. Each origin must be * or an http or https origin with no path, query, or fragment, and the command checks them before editing the file. See neon realtime enable for the full rules.

neon config add realtime [options]
OptionDescriptionTypeDefaultRequired
--allowed-originAllowed browser origin (repeatable). "*" allows every originarray—No
--branchBranch ID or namestring—No
--project-idProject IDstring—No

With an existing neon.ts, setting an allowed origin updates it in place:

neon config add realtime --allowed-origin https://app.example.com
Updated neon.ts: set preview.realtime to { allowedOrigins: ["https://app.example.com"] }.
Next: `neon config plan` to preview, `neon config apply` to provision.

neon config add function

Declares a Neon Function and creates its handler file. The handler defaults to functions/<slug>.ts (.js for a JavaScript config). A slug is 1 to 20 lowercase letters and digits, with no hyphens. Pass --name to set a display name (it defaults to the slug), or --source to register an existing handler relative to neon.ts without overwriting it. To start from a Function Registry template instead of the starter handler, use neon functions new.

neon config add function <slug> [options]
OptionDescriptionTypeDefaultRequired
--nameDisplay name. Defaults to the slugstring—No
--sourceHandler file, relative to neon.ts. Defaults to functions/<slug>.ts. Created when missing, left alone when it existsstring—No
--branchBranch ID or namestring—No
--project-idProject IDstring—No

Adding a function to a directory with no neon.ts creates both the config and the handler:

neon config add function sendemail
Created functions/sendemail.ts.
Created neon.ts: added functions.sendemail.
Created package.json.
Installing @neon/config, @neon/env with npm…
Next: `neon dev` to run it locally, `neon config apply` to deploy.

neon config add bucket

Declares a Neon Object Storage bucket. Pass --access public_read to allow anonymous reads; the default is private.

neon config add bucket <name> [options]
OptionDescriptionTypeDefaultRequired
--accessAnonymous access: private requires credentials, public_read allows anonymous reads Possible values: private, public_readstringprivateNo
--branchBranch ID or namestring—No
--project-idProject IDstring—No
neon config add bucket assets --access public_read

neon config status

Shows the branch's live Neon state.

neon config status [options]
OptionDescriptionTypeDefaultRequired
--config-jsonPrint only the branch's live config as neon.ts-shaped JSON (services + branch tuning + preview), to stdout. Useful for scripting or copying into a neon.ts.booleanfalseNo
--current-branchPrint only the linked branch name from the local .neon file (no network). Exits non-zero when no branch is pinned.booleanfalseNo
--branchBranch ID or namestring—No
--project-idProject IDstring—No
neon config status

The top-level neon status command is an alias for config status and accepts the same options.

Print the current branch offline

Pass --current-branch to print only the branch pinned in the local .neon file. This variant makes no network request and requires no login or analytics, so it is cheap enough to drive a shell prompt.

It prints the branch name to stdout and exits 0. When no branch is pinned, it prints nothing to stdout, writes a neon checkout <branch> hint to stderr, and exits with a non-zero status, so a prompt can guard on the command directly.

neon status --current-branch

For example, add your current Neon branch to a starship prompt. Append this [custom.neon] module to ~/.config/starship.toml. The command prints the pinned branch, and when hides the segment (exits non-zero) whenever you are not in a Neon project:

# ~/.config/starship.toml
[custom.neon]
description = "Current Neon branch"
command = "neon status --current-branch"   # prints the branch pinned in .neon (no network)
when = "neon status --current-branch"       # exits non-zero when no branch -> segment is hidden
symbol = "🌿 "
style = "bold green"
format = "[$symbol$output]($style) "

Faster outside Neon projects

The when above runs the CLI on every prompt everywhere. To skip it unless a .neon file exists somewhere up the tree, replace when with a pure-shell walk-up and add shell = ["sh"] so it runs under sh even if your interactive shell is fish or PowerShell:

shell = ["sh"]
when = '''
d="$PWD"
while [ "$d" != "$HOME" ] && [ "$d" != / ]; do
  if [ -e "$d/.neon" ]; then
    neon status --current-branch >/dev/null 2>&1
    exit $?
  fi
  d=$(dirname "$d")
done
exit 1
'''

For a full copy-paste (and agent-ready) walkthrough, including prerequisites and troubleshooting, see this Starship + Neon branch setup gist.

neon config plan

Shows what config apply would change, as a dry run. Nothing is modified.

neon config plan [options]
OptionDescriptionTypeDefaultRequired
--configPath to a neon.ts policy (defaults to the neon.ts next to .neon, or in cwd without one)string—No
--envPath to a .env file to load into the environment before evaluating neon.ts so Function env values resolve from it. Existing env vars are not overridden. Required Function env (declared required: true, or required: "default-branch" when deploying the default branch) and values that read process.env must be set in this file or the environment.string—No
--branchBranch ID or namestring—No
--project-idProject IDstring—No
neon config plan --config ./neon.ts --env .env.local

neon config apply

Applies a neon.ts policy to the branch.

neon config apply [options]
OptionDescriptionTypeDefaultRequired
--allow-protectedApply to a branch marked protected on Neon without askingbooleanfalseNo
--configPath to a neon.ts policy (defaults to the neon.ts next to .neon, or in cwd without one)string—No
--envPath to a .env file to load into the environment before evaluating neon.ts so Function env values resolve from it. Existing env vars are not overridden. Required Function env (declared required: true, or required: "default-branch" when deploying the default branch) and values that read process.env must be set in this file or the environment.string—No
--env-pullPull the branch's Neon env vars (DATABASE_URL, …) into a local .env after a successful apply. On by default; use --no-env-pull to skip (e.g. when injecting env at runtime with neon-env run / neon dev).booleantrueNo
--update-existingOverride branch settings that differ from neon.ts without askingbooleanfalseNo
--yes, -yAnswer yes to every confirmation: --update-existing and --allow-protectedbooleanfalseNo
--branchBranch ID or namestring—No
--project-idProject IDstring—No

In a terminal, apply asks before it overrides branch settings that differ from neon.ts or applies to a branch marked protected on Neon. Declining applies nothing.

Without a terminal, there's no prompt. This covers CI, runs with no TTY, and -o json or -o yaml output. In those cases, apply stops before changing anything and names the flag to re-run with. For scripts, CI, and agents, pass --update-existing to allow the overrides, --allow-protected to allow a protected branch, or -y for both:

neon config apply --branch feature/auth -y

Last updated on

Was this page helpful?
Edit on GitHub