Neon Deploy: Learn how Neon helps developers ship faster with Postgres. Grab your ticket
Community

Postgres at your fingertips with the Neon CLI

Streamlining database management with Neon CLI

Old computer with a terminal being displayed, placed on a colorful background

Today, we are releasing Neon CLI, a command-line interface that enables developers to manage Neon resources directly from the terminal! With Neon CLI, you can handle authentication, and manage projects, branches, databases, roles, and much more without leaving your command line.

Get started by installing the CLI using the following command:

npm i -g neonctl

Use neonctl auth command to connect to your Neon account, or create a new one.

What Can You Do with the Neon CLI?

The CLI offers an integrated approach to managing other aspects of your projects, including CRUD (Create, Read, Update, Delete) operations on your projects, branches, databases, and roles. Here are a few examples of what you can do using the CLI:

Projects

With Neon CLI you can create a Postgres database and get a connection string in seconds: 

neonctl projects create

Output:

┌───────────────────┬──────┬───────────────┬──────────────────────┐
 Id                │ Name Region Id     │ Created At           │
├───────────────────┼──────┼───────────────┼──────────────────────┤
│  cold-lab-971294  cli  aws-us-east-2 2023-07-05T12:05:02Z
└───────────────────┴──────┴───────────────┴──────────────────────┘
┌───────────────────────────────────────────────────────────────────────────────────────┐
 Connection Uri                                                                        │
├───────────────────────────────────────────────────────────────────────────────────────┤
 postgres://<user>:<password>@ep-lingering-moon-792025.us-east-2.aws.neon.tech/neondb
└───────────────────────────────────────────────────────────────────────────────────────┘

The projects create returns your new project-id (cold-lab-971294) and the connection string so you can immediately use it in your project.

Branches and connection string

You can also list your branches and create a new one to use for local development:

neonctl branches list

Output:

┌────────────────────────┬──────┬──────────────────────┬──────────────────────┐
 Id                     │ Name Created At           │ Updated At           │
├────────────────────────┼──────┼──────────────────────┼──────────────────────┤
 br-purple-tooth-335860 main 2023-07-05T12:06:49Z 2023-07-05T12:11:04Z
└────────────────────────┴──────┴──────────────────────┴──────────────────────┘

The CLI allows you to create Neon branches, similarily to when you create a local Git branch for local development. Neon branches are isolated copy of your database that you can modify without compromising your main database, ideal for development and testing. You can create a branch using the following command:

neonctl branches create –-project-id=<your-project-id>

The branches and projects create commands return a connection string. However, you can use the following command to display your connection string at any moment:

neonctl cs <branch> --project-id=<your-project-id>

Once you are done with your feature and have merged your code and schema changes, you can dispose of the branch:

neonctl branches delete <your-branch-id> --project-id <your-project-id> 

Integrated the CLI in your CI/CD pipelines

You can use the CLI in your developer workflows and pipelines. If not authenticated, the CLI expects a NEON_API_KEY as an argument, that you can create in the Neon console. You can also pass the API key as a parameter like in the command below:

npx neonctl branches create --project-id=<your_project_id> --api-key=<key>

We invite you to visit the documentation for more information about the supported commands.

We’d love to hear your feedback

We are currently actively developing CLI, so more features to the CLI are to come. Share feedback and let us know what you’d like to see in Neon CLI.

We thank you for your valuable contributions, encourage you to explore Neon CLI, and would love to hear from you to make the experience managing your Postgres databases better.