Neon CLI

The Neon CLI is a command-line interface for managing Neon Serverless Postgres directly from your terminal. It provides the same capabilities as the Neon Platform API and is ideal for scripting, CI/CD pipelines, and developers who prefer terminal workflows.

Installation

macOS (Homebrew):

brew install neonctl

npm (cross-platform):

npm install -g neonctl

Authentication

Authenticate with your Neon account:

neonctl auth

This opens a browser for OAuth authentication and stores credentials locally.

For CI/CD or non-interactive environments, use an API key:

export NEON_API_KEY=your-api-key

Get your API key from: https://console.neon.tech/app/settings/api-keys

Common Commands

Project Management

# List all projects
neonctl projects list

# Create a new project
neonctl projects create --name my-project

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

# Delete a project
neonctl projects delete <project-id>

Branch Operations

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

# Create a branch
neonctl branches create --project-id <project-id> --name dev

# Delete a branch
neonctl branches delete <branch-id> --project-id <project-id>

Connection Strings

# Get connection string
neonctl connection-string --project-id <project-id>

# Get connection string for specific branch
neonctl connection-string --project-id <project-id> --branch-id <branch-id>

# Get pooled connection string
neonctl connection-string --project-id <project-id> --pooled

SQL Execution

# Run SQL query
neonctl sql "SELECT * FROM users LIMIT 10" --project-id <project-id>

# Run SQL from file
neonctl sql --file schema.sql --project-id <project-id>

Database Management

# List databases
neonctl databases list --project-id <project-id> --branch-id <branch-id>

# Create database
neonctl databases create --project-id <project-id> --name mydb

# List roles
neonctl roles list --project-id <project-id> --branch-id <branch-id>

Output Formats

The CLI supports multiple output formats:

# JSON output (default for scripting)
neonctl projects list --output json

# Table output (human-readable)
neonctl projects list --output table

# YAML output
neonctl projects list --output yaml

CI/CD Integration

Example GitHub Actions workflow:

- name: Create preview branch
  env:
    NEON_API_KEY: ${{ secrets.NEON_API_KEY }}
  run: |
    neonctl branches create \
      --project-id ${{ vars.NEON_PROJECT_ID }} \
      --name preview-${{ github.event.pull_request.number }}

CLI vs MCP Server vs SDKs

Tool	Best For
Neon CLI	Terminal workflows, scripts, CI/CD pipelines
MCP Server	AI-assisted development with Claude, Cursor, etc.
TypeScript SDK	Programmatic access in Node.js/TypeScript apps
Python SDK	Programmatic access in Python applications
REST API	Direct HTTP integration in any language

Documentation Resources

Topic	URL
CLI Reference	https://neon.com/docs/reference/neon-cli
CLI Install	https://neon.com/docs/reference/cli-install
CLI Auth	https://neon.com/docs/reference/cli-auth
CLI Projects	https://neon.com/docs/reference/cli-projects
CLI Branches	https://neon.com/docs/reference/cli-branches
CLI Connection	https://neon.com/docs/reference/cli-connection-string

Fetch CLI documentation:

curl -H "Accept: text/markdown" https://neon.com/docs/reference/neon-cli

3.9 KiB Raw Blame History