What is the Neon CLI?

neonctl is the command-line tool for Neon — the serverless PostgreSQL platform with database branching. It creates and manages database branches for development workflows, generates TypeScript types, and integrates with CI/CD pipelines.

Installation

# npm
npm install -g neonctl

# macOS
brew install neon

# Verify
neonctl --version

Authentication

# Login (opens browser)
neonctl auth

# API key (for CI/CD)
export NEON_API_KEY=your-api-key-here
# Or: neonctl <command> --api-key $NEON_API_KEY

Project Management

# List projects
neonctl projects list

# Create project
neonctl projects create --name my-app

# Get project details
neonctl projects get <project-id>

# Delete project
neonctl projects delete <project-id>

Branch Workflow

# List branches
neonctl branches list --project-id <project-id>

# Create a branch (instant, uses copy-on-write)
neonctl branches create \
  --project-id <project-id> \
  --name feature/new-auth

# Create from specific parent (e.g., a point in time)
neonctl branches create \
  --project-id <project-id> \
  --name feature/experiment \
  --parent main

# Get connection string for a branch
neonctl connection-string feature/new-auth \
  --project-id <project-id>
# Output: postgresql://user:[email protected]/neondb?sslmode=require

# Reset branch to parent state (discard all changes)
neonctl branches reset feature/new-auth --project-id <project-id>

# Delete branch
neonctl branches delete feature/new-auth --project-id <project-id>

CI/CD: Database Branch Per Pull Request

# .github/workflows/pr-database.yml
name: PR Database Branch
on:
  pull_request:
    types: [opened, synchronize]
  pull_request_target:
    types: [closed]

jobs:
  create-branch:
    if: github.event.action != 'closed'
    runs-on: ubuntu-latest
    outputs:
      db_url: ${{ steps.create.outputs.db_url }}
    steps:
      - uses: actions/checkout@v4

      - name: Create Neon Branch
        id: create
        uses: neondatabase/create-branch-action@v5
        with:
          project_id: ${{ vars.NEON_PROJECT_ID }}
          branch_name: pr-${{ github.event.pull_request.number }}
          api_key: ${{ secrets.NEON_API_KEY }}

      - name: Run Migrations
        run: npx prisma migrate deploy
        env:
          DATABASE_URL: ${{ steps.create.outputs.db_url }}

      - name: Run Integration Tests
        run: npm run test:integration
        env:
          DATABASE_URL: ${{ steps.create.outputs.db_url }}

  cleanup:
    if: github.event.action == 'closed'
    runs-on: ubuntu-latest
    steps:
      - name: Delete Neon Branch
        uses: neondatabase/delete-branch-action@v3
        with:
          project_id: ${{ vars.NEON_PROJECT_ID }}
          branch: pr-${{ github.event.pull_request.number }}
          api_key: ${{ secrets.NEON_API_KEY }}

Connection Strings

# Get psql-compatible connection string
neonctl connection-string main \
  --project-id abc123 \
  --database-name myapp \
  --role-name webuser

# Output to file
neonctl connection-string main > .env.local

Neon Branching for Database Testing

The power of Neon CLI in development:

#!/bin/bash
# Create isolated test database for each developer
BRANCH_NAME="dev-$(whoami)"

# Create personal dev branch
neonctl branches create \
  --project-id $NEON_PROJECT_ID \
  --name $BRANCH_NAME \
  --parent main

# Get connection string
DB_URL=$(neonctl connection-string $BRANCH_NAME --project-id $NEON_PROJECT_ID)

echo "DATABASE_URL=$DB_URL" > .env.local
echo "Branch created: $BRANCH_NAME"
echo "Your database is ready!"

The Neon CLI enables the most developer-friendly database workflow available — every branch, PR, and developer gets their own isolated PostgreSQL database in seconds.

Best For

Full-stack developers on Vercel or Railway who want serverless PostgreSQL that scales to zero and eliminates idle database costs
Feature branch workflows — create an isolated database branch per PR, run migrations and tests against it, then discard — identical to how you branch code
Teams using database branching to safely test schema migrations without affecting production or shared development databases
Startups wanting zero-infrastructure-management PostgreSQL — Neon handles connection pooling (via PgBouncer), backups, and scaling automatically

Neon vs. Alternatives

	Neon	Supabase	PlanetScale	Railway Postgres
Database	PostgreSQL	PostgreSQL	MySQL (Vitess)	PostgreSQL
Branching	✅	✗	✅ (deploy requests)	✗
Scale to zero	✅	Partial (Pro)	✅	✗
Free tier	0.5 CU, 512MB	500MB	5GB	$5 credit/mo
Best for	Branch-per-PR workflows	Full-stack app backend	MySQL/multi-tenancy	Simple Postgres

Neon’s branch-per-PR workflow is its differentiator. For teams that need a full backend-as-a-service (auth, storage, real-time), Supabase is a better fit.

Neon CLI — Command-Line Tool for Neon Serverless PostgreSQL

✅ Pros

⚠️ Cons