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](/guides/apis-sdks-reference-neon-ts).

Subcommands: [add](#neon-config-add), [apply](#neon-config-apply), [init](#neon-config-init), [plan](#neon-config-plan), [status](#neon-config-status)

The top-level [`neon deploy`](/guides/apis-sdks-cli-deploy) command is an alias for `config apply`, and [`neon status`](/guides/apis-sdks-cli-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:

```typescript title="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.

`config init` runs entirely locally and does not call the Neon API. It detects your package manager (npm, pnpm, yarn, or bun) from how the command was invoked. 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.

```bash
neon config init [options]
```

| Option          | Description                                                                                                                                                                                                                                          | Type    | Default | Required |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | -------- |
| `--from-branch` | Seed 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. The only mode of `config init` that calls the Neon API.                                   | boolean | —       | No       |
| `--install`     | Install @neon/config and @neon/env if they're missing. On by default; use --no-install to just print the command.                                                                                                                                    | boolean | `true`  | No       |
| `--services`    | Services the scaffolded neon.ts declares: auth, functions, object-storage, ai-gateway. Pass "none" for the bare starter policy. Repeat the flag or comma-separate. Omitted: pick interactively on a terminal, starter policy in CI or without a TTY. | array   | —       | No       |
| `--branch`      | Branch ID or name                                                                                                                                                                                                                                    | string  | —       | No       |
| `--project-id`  | Project ID                                                                                                                                                                                                                                           | string  | —       | No       |

```bash
neon config init
```

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

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):

```bash
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.

:::callout{intent="tip"}
After running an interactive [`neon link`](/guides/apis-sdks-cli-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`](#neon-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`](#neon-config-init) instead.

```bash
neon config add <sub-command> [options]
```

Subcommands: [ai-gateway](#neon-config-add-ai-gateway), [auth](#neon-config-add-auth), [bucket](#neon-config-add-bucket), [data-api](#neon-config-add-data-api), [function](#neon-config-add-function)

`config add` runs entirely locally: it edits files, and never authenticates or resolves a project. Provisioning stays a separate [`neon config apply`](#neon-config-apply) step.

It finds your config by walking up from the current directory, stopping at a `.git` directory or your home directory. When it finds none, it creates `neon.ts` in the current directory 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 service declared under the deprecated `preview` block, 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 Neon Auth by setting `auth: true`.

```bash
neon config add auth [options]
```

| Option         | Description                                                                                                          | Type    | Default | Required |
| -------------- | -------------------------------------------------------------------------------------------------------------------- | ------- | ------- | -------- |
| `--config`     | Path to the neon.ts to edit (defaults to walking up from cwd; created in cwd when there is none)                     | string  | —       | No       |
| `--install`    | Install @neon/config and @neon/env when creating neon.ts. On by default; use --no-install to just print the command. | boolean | `true`  | No       |
| `--branch`     | Branch ID or name                                                                                                    | string  | —       | No       |
| `--project-id` | Project ID                                                                                                           | string  | —       | No       |

```bash
neon config add auth
```

### neon config add data-api

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

```bash
neon config add data-api [options]
```

| Option         | Description                                                                                                          | Type    | Default | Required |
| -------------- | -------------------------------------------------------------------------------------------------------------------- | ------- | ------- | -------- |
| `--config`     | Path to the neon.ts to edit (defaults to walking up from cwd; created in cwd when there is none)                     | string  | —       | No       |
| `--install`    | Install @neon/config and @neon/env when creating neon.ts. On by default; use --no-install to just print the command. | boolean | `true`  | No       |
| `--branch`     | Branch ID or name                                                                                                    | string  | —       | No       |
| `--project-id` | Project ID                                                                                                           | string  | —       | No       |

```bash
neon config add data-api
```

### neon config add ai-gateway

Enables the AI Gateway by setting `aiGateway: true`.

```bash
neon config add ai-gateway [options]
```

| Option         | Description                                                                                                          | Type    | Default | Required |
| -------------- | -------------------------------------------------------------------------------------------------------------------- | ------- | ------- | -------- |
| `--config`     | Path to the neon.ts to edit (defaults to walking up from cwd; created in cwd when there is none)                     | string  | —       | No       |
| `--install`    | Install @neon/config and @neon/env when creating neon.ts. On by default; use --no-install to just print the command. | boolean | `true`  | No       |
| `--branch`     | Branch ID or name                                                                                                    | string  | —       | No       |
| `--project-id` | Project ID                                                                                                           | string  | —       | No       |

```bash
neon config add ai-gateway
```

### neon config add function

Declares a [Neon Function](/guides/apis-sdks-cli-functions) 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.

```bash
neon config add function <slug> [options]
```

| Option         | Description                                                                                                          | Type   | Default | Required |
| -------------- | -------------------------------------------------------------------------------------------------------------------- | ------ | ------- | -------- |
| `--name`       | Display name. Defaults to the slug                                                                                   | string | —       | No       |
| `--source`     | Handler file, relative to neon.ts. Defaults to functions/\<slug>.ts. Created when missing, left alone when it exists | string | —       | No       |
| `--branch`     | Branch ID or name                                                                                                    | string | —       | No       |
| `--project-id` | Project ID                                                                                                           | string | —       | No       |

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

```bash
neon config add function sendemail
```

```
INFO: Created functions/sendemail.ts.
INFO: Created neon.ts: added functions.sendemail.
INFO: Install the Neon config packages to use neon.ts: npm install @neon/config @neon/env
INFO: Next: `neon dev` to run it locally, `neon config apply` to deploy.
```

### neon config add bucket

Declares a [Neon Object Storage](/guides/apis-sdks-cli-buckets) bucket. Pass `--access public_read` to allow anonymous reads; the default is `private`.

```bash
neon config add bucket <name> [options]
```

| Option         | Description                                                                                                                   | Type   | Default   | Required |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------ | --------- | -------- |
| `--access`     | Anonymous access: private requires credentials, public\_read allows anonymous reads Possible values: `private`, `public_read` | string | `private` | No       |
| `--branch`     | Branch ID or name                                                                                                             | string | —         | No       |
| `--project-id` | Project ID                                                                                                                    | string | —         | No       |

```bash
neon config add bucket assets --access public_read
```

## neon config status

Shows the branch's live Neon state.

```bash
neon config status [options]
```

| Option             | Description                                                                                                                                                 | Type    | Default | Required |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | -------- |
| `--config-json`    | Print 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. | boolean | `false` | No       |
| `--current-branch` | Print only the linked branch name from the local .neon file (no network). Exits non-zero when no branch is pinned.                                          | boolean | `false` | No       |
| `--branch`         | Branch ID or name                                                                                                                                           | string  | —       | No       |
| `--project-id`     | Project ID                                                                                                                                                  | string  | —       | No       |

```bash
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.

```bash
neon status --current-branch
```

For example, add your current Neon branch to a [starship](https://starship.rs/) 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:

```toml
# ~/.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) "
```

:::callout{intent="note" title="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:

```toml
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](https://gist.github.com/thisistonydang/0b6c03ec9aa9b619ffecd48f58fd40c7).

## neon config plan

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

```bash
neon config plan [options]
```

| Option         | Description                                                                                                                                                                                                                                     | Type   | Default | Required |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | -------- |
| `--config`     | Path to a neon.ts policy (defaults to walking up from cwd)                                                                                                                                                                                      | string | —       | No       |
| `--env`        | Path 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. Function env values that read process.env must be set in this file or the environment. | string | —       | No       |
| `--branch`     | Branch ID or name                                                                                                                                                                                                                               | string | —       | No       |
| `--project-id` | Project ID                                                                                                                                                                                                                                      | string | —       | No       |

```bash
neon config plan --config ./neon.ts --env .env.local
```

## neon config apply

Applies a `neon.ts` policy to the branch.

```bash
neon config apply [options]
```

| Option              | Description                                                                                                                                                                                                                                     | Type    | Default | Required |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------- | -------- |
| `--allow-protected` | Auto-confirm applying to a branch marked protected on Neon                                                                                                                                                                                      | boolean | `false` | No       |
| `--config`          | Path to a neon.ts policy (defaults to walking up from cwd)                                                                                                                                                                                      | string  | —       | No       |
| `--env`             | Path 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. Function env values that read process.env must be set in this file or the environment. | string  | —       | No       |
| `--env-pull`        | Pull 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`).                                  | boolean | `true`  | No       |
| `--update-existing` | Auto-confirm overriding existing remote settings on the branch                                                                                                                                                                                  | boolean | `false` | No       |
| `--branch`          | Branch ID or name                                                                                                                                                                                                                               | string  | —       | No       |
| `--project-id`      | Project ID                                                                                                                                                                                                                                      | string  | —       | No       |

For non-interactive use (scripts, CI, agents), pass `--update-existing` and `--allow-protected` to auto-confirm the corresponding prompts.

```bash
neon config apply --branch feature/auth --update-existing --allow-protected
```

## Related pages

- [Neon CLI command: deploy](./apis-sdks-cli-deploy.md)
- [Neon CLI command: status](./apis-sdks-cli-status.md)
- [Neon CLI command: dev](./apis-sdks-cli-dev.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.