Neon is Generally Available! Serverless Postgres with branching to boost your development velocity.Read more
Reference/Neon CLI

Neon CLI commands — projects

Use the Neon CLI to manage Neon directly from the terminal

Before you begin

  • Before running the projects command, ensure that you have installed the Neon CLI.
  • If you have not authenticated with the neonctl auth command, running a Neon CLI command automatically launches the Neon CLI browser authentication process. Alternatively, you can specify a Neon API key using the --api-key option when running a command. See Connect.

For information about projects in Neon, see Projects.

The projects command

The projects command allows you to list, create, update, delete, and retrieve information about Neon projects.

Usage

neonctl projects <subcommand> [options]
SubcommandDescription
listList projects
createCreate a project
updateUpdate a project
deleteDelete a project
getGet a project

list

This subcommand allows you to list projects that belong to your Neon account.

Usage

neonctl projects list [options]

Options

In addition to the Neon CLI global options, the projects subcommand supports this option:

OptionDescriptionTypeRequired
--context-fileContext file path and file namestring

Example

neonctl projects list
┌────────────────────────┬────────────────────────┬───────────────┬──────────────────────┐
 Id                     │ Name                   │ Region Id     │ Created At           │
├────────────────────────┼────────────────────────┼───────────────┼──────────────────────┤
 late-rain-471577       │ late-rain-471577       │ aws-us-west-2 │ 2023-05-17T17:26:07Z │
├────────────────────────┼────────────────────────┼───────────────┼──────────────────────┤
 tight-wave-371442      │ tight-wave-371442      │ aws-us-east-2 │ 2023-05-15T12:33:39Z │
├────────────────────────┼────────────────────────┼───────────────┼──────────────────────┤
 lingering-brook-802958 │ lingering-brook-802958 │ aws-us-east-2 │ 2023-05-11T12:25:22Z │
└────────────────────────┴────────────────────────┴───────────────┴──────────────────────┘

create

This subcommand allows you to create a Neon project.

The Neon Free Tier supports creating a single project. Paid plans allow multiple projects.

Usage

neonctl projects create [options]

Options

In addition to the Neon CLI global options, the create subcommand supports these options:

OptionDescriptionTypeRequired
--context-fileContext file path and file namestring
--nameThe project name. The project ID is used if a name is not specified.string
--region-idThe region ID. Possible values: aws-us-west-2, aws-ap-southeast-1, aws-eu-central-1, aws-us-east-2, aws-us-east-1. Defaults to aws-us-east-2 if not specified.string number
--psqlConnect to a database via psql using connection string. psql must be installed to use this option.boolean
--set-contextSet the current context to the new project. The default is false.boolean

Examples

  • Create a project with a user-defined name in a specific region:

    neonctl projects create --name mynewproject --region-id aws-us-west-2
    ┌───────────────────┬──────────────┬───────────────┬──────────────────────┐
     Id                │ Name         │ Region Id     │ Created At           │
    ├───────────────────┼──────────────┼───────────────┼──────────────────────┤
     muddy-wood-859533 │ mynewproject │ aws-us-west-2 │ 2023-07-09T17:04:29Z │
    └───────────────────┴──────────────┴───────────────┴──────────────────────┘
    
    ┌──────────────────────────────────────────────────────────────────────────────────────┐
     Connection Uri                                                                       │
    ├──────────────────────────────────────────────────────────────────────────────────────┤
     postgres://[user]:[password]@[neon_hostname]/[dbname]                                │
    └──────────────────────────────────────────────────────────────────────────────────────┘

    tip

    The Neon CLI provides a neonctl connection-string command you can use to extract a connection uri programmatically. See Neon CLI commands — connection-string.

  • Create a project with the --output format of the command set to json. This output format returns all of the project response data, whereas the default table output format (shown in the preceding example) is limited in the information it can display.

    neonctl projects create --output json
    Example output
    {
    "project": {
        "data_storage_bytes_hour": 0,
        "data_transfer_bytes": 0,
        "written_data_bytes": 0,
        "compute_time_seconds": 0,
        "active_time_seconds": 0,
        "cpu_used_sec": 0,
        "id": "long-wind-77910944",
        "platform_id": "aws",
        "region_id": "aws-us-east-2",
        "name": "long-wind-77910944",
        "provisioner": "k8s-pod",
        "default_endpoint_settings": {
        "autoscaling_limit_min_cu": 1,
        "autoscaling_limit_max_cu": 1,
        "suspend_timeout_seconds": 0
        },
        "pg_version": 15,
        "proxy_host": "us-east-2.aws.neon.tech",
        "branch_logical_size_limit": 204800,
        "branch_logical_size_limit_bytes": 214748364800,
        "store_passwords": true,
        "creation_source": "neonctl",
        "history_retention_seconds": 604800,
        "created_at": "2023-08-04T16:16:45Z",
        "updated_at": "2023-08-04T16:16:45Z",
        "consumption_period_start": "0001-01-01T00:00:00Z",
        "consumption_period_end": "0001-01-01T00:00:00Z",
        "owner_id": "e56ad68e-7f2f-4d74-928c-9ea25d7e9864"
    },
    "connection_uris": [
        {
        "connection_uri": "postgres://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname",
        "connection_parameters": {
            "database": "dbname",
            "password": "AbC123dEf",
            "role": "alex",
            "host": "ep-cool-darkness-123456.us-east-2.aws.neon.tech",
            "pooler_host": "ep-cool-darkness-123456-pooler.us-east-2.aws.neon.tech"
        }
        }
    ]
    }
  • Create a project and connect to it with psql.

    neonctl project create --psql
  • Create a project, connect to it with psql, and run an .sql file.

    neonctl project create --psql -- -f dump.sql
  • Create a project, connect to it with psql, and run a query.

    neonctl project create --psql -- -c "SELECT version()"
  • Create a project and set the Neon CLI project and branch context.

    neonctl project create --psql --set-context

update

This subcommand allows you to update a Neon project.

Usage

neonctl projects update <id> [options]

The id is the project ID, which you can obtain by listing your projects or from the Project settings page in the Neon Console.

Options

In addition to the Neon CLI global options, the update subcommand supports this option:

OptionDescriptionTypeRequired
--context-fileContext file path and file namestring
--nameThe project name. The value cannot be empty.string
--ip-allowA list of IP addresses that are allowed to connect to the endpointstring
--ip-primary-onlyIf true, the list will be applied only to the primary branch. The deafault value is false.boolean

Examples

Update the project name:

neonctl projects update muddy-wood-859533 --name dev_project_1
┌───────────────────┬───────────────┬───────────────┬──────────────────────┐
 Id                │ Name          │ Region Id     │ Created At           │
├───────────────────┼───────────────┼───────────────┼──────────────────────┤
 muddy-wood-859533 │ dev_project_1 │ aws-us-west-2 │ 2023-07-09T17:04:29Z │
└───────────────────┴───────────────┴───────────────┴──────────────────────┘

Update the IP allowlist. Multiple values are specified as a list without a delimiter.

neonctl projects update withered-dream-91802149 --ip-allow 192.0.2.1 192.0.2.2 
┌─────────────────────────┬───────────┬───────────────┬──────────────────────┐
 Id                      │ Name      │ Region Id     │ Created At           │
├─────────────────────────┼───────────┼───────────────┼──────────────────────┤
 withered-dream-91802149 │ myproject │ aws-us-east-2 │ 2024-01-07T11:41:52Z │
└─────────────────────────┴───────────┴───────────────┴──────────────────────┘

Apply the IP allowlist to the primary branch only:

neonctl projects update withered-dream-91802149 --ip-only-primary                 
┌─────────────────────────┬───────────┬───────────────┬──────────────────────┐
 Id                      │ Name      │ Region Id     │ Created At           │
├─────────────────────────┼───────────┼───────────────┼──────────────────────┤
 withered-dream-91802149 │ myproject │ aws-us-east-2 │ 2024-01-07T11:41:52Z │
└─────────────────────────┴───────────┴───────────────┴──────────────────────┘

delete

This subcommand allows you to delete a Neon project.

neonctl projects delete <id> [options]

The id is the project ID, which you can obtain by listing your projects or from the Project settings page in the Neon Console.

Options

Only global options apply.

Example

neonctl projects delete muddy-wood-859533
┌───────────────────┬───────────────┬───────────────┬──────────────────────┐
 Id                │ Name          │ Region Id     │ Created At           │
├───────────────────┼───────────────┼───────────────┼──────────────────────┤
 muddy-wood-859533 │ dev_project_1 │ aws-us-west-2 │ 2023-07-09T17:04:29Z │
└───────────────────┴───────────────┴───────────────┴──────────────────────┘

Information about the deleted project is displayed. You can verify that the project was deleted by running neonctl projects list.

get

This subcommand allows you to retrieve details about a Neon project.

Usage

neonctl projects get <id> [options]

The id is the project ID, which you can obtain by listing your projects or from the Project settings page in the Neon Console.

Options

In addition to the Neon CLI global options, the delete subcommand supports this option:

OptionDescriptionTypeRequired
--context-fileContext file path and file namestring

Example

neonctl projects get muddy-wood-859533
┌───────────────────┬───────────────┬───────────────┬──────────────────────┐
 Id                │ Name          │ Region Id     │ Created At           │
├───────────────────┼───────────────┼───────────────┼──────────────────────┤
 muddy-wood-859533 │ dev_project_1 │ aws-us-west-2 │ 2023-07-09T17:04:29Z │
└───────────────────┴───────────────┴───────────────┴──────────────────────┘

Need help?

Join our Discord Server to ask questions or see what others are doing with Neon. Users on paid plans can open a support ticket from the console. For more detail, see Getting Support.

Last updated on

Edit this page
Was this page helpful?