neon

Files (11)

• SKILL.md
• evals.json · evals/
• trigger_queries.json · evals/
• data-api-and-auth.md · references/
• databases-roles-connections.md · references/
• migration-from-neonctl.md · references/
• neon-ts-config.md · references/
• platform-surfaces.md · references/
• projects-branches.md · references/
• security-operations.md · references/
• neon-preflight.sh · scripts/

SKILL.md (first lines)

# Neon CLI (`neon`)

One CLI for every Neon surface: Postgres branches, Functions, object storage, the Data API, and Managed Better Auth.

**The CLI was renamed from `neonctl` to `neon`.** If the user mentions `neonctl` at all — a broken script, a stale install, a CI job, "is it deprecated" — read [references/migration-from-neonctl.md](references/migration-from-neonctl.md) first. It covers the package split, the bin-symlink trap when uninstalling, and what changed at the command level.

## Orientation: check the install before anything else

Version drift is the single most common source of confusion here, because the old and new CLIs coexist happily and give no warning.

```bash
bash scripts/neon-preflight.sh     # version, auth, context, staleness — one shot
```

Or manually:

```bash
neon --version        # want 4.x — if this prints 2.x you are on the old CLI under a new name
neon me               # confirms authentication
```

If `neon` is missing or on 2.x, install the current CLI:

```bash
npm i -g neon@latest              # requires Node 20.19.0+
```

The command surface below assumes 4.x. On 2.x, roughly half of it (snapshots, functions, buckets, data-api, inspect, logs, env, link, checkout, profile) simply does not exist — which reads as "unknown command" rather than "please upgrade", so check the version before concluding a command is wrong.

## Authentication

Credentials resolve in this order, first match wins:

1. `--api-key <key>` on the command
2. `NEON_API_KEY` environment variable
3. `credentials.json` in the config directory, written by `neon login`
4. Interactive browser login (fallback)

```bash
neon login                                   # browser auth (alias: neon auth)
export NEON_API_KEY=<key>                    # preferred in CI — no browser available
neon projects list --api-key <key>           # one-off override
```

For several accounts or org-scoped keys, use named profiles instead of juggling env vars:

```bash
neon profile create work --api-key <key>     # or --mint to have Neon issue one
neon profile list
neon --profile work projects list            # or: export NEON_PROFILE=work
```

**Config directory gotcha:** `neon --help` advertises `~/.config/neon`, but the 4.x CLI actually reads and refreshes `~/.config/neonctl/credentials.json` — the legacy path. The practical consequence is good news: upgrading from `neonctl` keeps you logged in. Don't "fix" this by moving the directory; override it with `--config-dir` only if you have a real reason.

## Context: stop repeating `--project-id`

`neon link` binds the current directory to a project by writing a `.neon` file (`orgId`, `projectId`, and `branch` when pinned). Every command run from that directory or below picks it up.

```bash
neon link                                          # interactive: pick/create org + project
neon link --project-id <id> --org-id <org-id>      # non-interactive (CI, agents)
neon link --org-id <org> --project-name my-app --region-id aws-us-east-2   # create + link
neon link --params '{"orgId":"...","projectId":"..."}'   # same payload as one JSON blob
neon checkout dev --create                         # pin a branch (creating it if absent)
neon link --clear                                  # unbind
```

`--no-checks` writes the context offline with no API calls — it then requires `--org-id` and `--project-id`
and skips the env pull. Flags take precedence over fields in `--params`.

Two behaviors worth knowing before they surprise someone: linking **pulls the branch's env vars into a local `.env`/`.env.local` by default** (`--no-env-pull` to skip), and after an interactive link the CLI **offers to scaffold a `neon.ts` config** (`--no-config` to skip). On first creation the CLI adds `.neon` to `.gitignore`; the file holds no secrets, so remove that entry if the team wants shared context.

`set-context` still works (and still takes `--project-id`, `--branch-id`, `--org-id`) but is deprecated — prefer `link`, which validates the IDs and writes a complete context. In a repo where `neon link` would clobber a teammate's context, pin a separate file with the global `--context-file <path>`.

## Command map

Use this to pick a landing spot, then open the matching reference for flags and examples.

| Area | Commands | Reference |
|---|---|---|
| Projects, branches, schema diff | `projects`, `branches`, `diff`, `snapshots` | [projects-branches.md](references/projects-branches.md) |
| Databases, roles, connection strings, psql | `databases`, `roles`, `connection-string`, `psql`, `env` | [databases-roles-connections.md](references/databases-roles-connections.md) |
| IP allow, VPC, operations, logs, credentials, API keys | `ip-allow`, `vpc`, `operations`, `logs`, `credentials`, `api-keys`, `api` | [security-operations.md](references/security-operations.md) |
| Functions, triggers, buckets, inspect, `neon.ts` config-as-code | `functions`, `dev`, `triggers`, `buckets`, `inspect`, `config`/`deploy`/`status`, `init`/`mcp`/`skills` | [platform-surfaces.md](references/platform-surfaces.md) |
| Data API and Managed Better Auth (large config surfaces) | `data-api`, `neon-auth` | [data-api-and-auth.md](references/data-api-and-auth.md) |
| The `neon.ts` file format itself — required to use `config`/`deploy`/`dev` | — | [neon-ts-config.md](references/neon-ts-config.md) |
| Setup, agent tooling | `login`, `profile`, `link`, `checkout`, `init`, `mcp`, `skills`, `plugins`, `bootstrap`, `claim`, `ask`, `open` | this file + [migration-from-neonctl.md](references/migration-from-neonctl.md) |

Aliases are pervasive and safe to use: `branch`, `db`, `cs`, `org`, `project`, `role`, `operation`, `snapshot`, `function`, `trigger`, `bucket`, `credential`, and `login` (= `auth`; `auth` is the canonical name, both work).

## Output and scripting

`table` is the default and **it truncates** — long IDs, URIs, and timestamps get cut. Any time output is being parsed, captured, or shown as evidence, use JSON:

```bash
neon branches list --output json | jq -r '.[].name'
CONN=$(neon connection-string dev --pooled)          # already a bare string — no jq needed
```

**Envelope shapes are not uniform, and guessing costs a debugging session.** Verified against 4.18.1 — and
since Neon ships several releases a week, confirm with `jq type` rather than assuming this table is current:

| Command | `--output json` returns | jq path |
|---|---|---|
| `branches list`, `databases list`, `roles list`, `operations list`, `snapshots list`, `orgs list` | a **bare array** | `.[].name` — *not* `.branches[]` |
| `projects list` | object with `projects` and `shared_with_you` | `.projects[].id` |
| `projects get`, `branches get`, `me` | a **flat object**, no wrapper | `.history_retention_seconds` — *not* `.project....` |
| `connection-string` | **plain text, not JSON** — `-o json` changes nothing | use it directly |
| `connection-string --extended` | object: `connection_string`, `host`, `role`, `password`, `database`, `options` | `.connection_string` |

When in doubt, pipe one call through `jq type` before building a script around it.

Two traps in the same area. `projects list` does include org-owned projects, but only for your default org —
a second organization's projects are absent until you pass `--org-id`, so a cross-org audit must iterate
`neon orgs list` or it silently reports a subset and looks like it worked. And `projects list --org-id <id>`
**returns a bare array** rather than the `{projects, shared_with_you}` object the bare call returns, which
breaks the very loop you just wrote.

Global options that apply everywhere: `-o/--output json|yaml|table`, `--api-key`, `--profile`, `--config-dir`, `--context-file`, `--color/--no-color`, `--analytics/--no-analytics`, `-v/--version`, `-h/--help`.

From kryptobaseddev/awesome-skills, MIT.

More from kryptobaseddev/awesome-skills