Major update to our Free Plan: now with 1 GB of Postgres storage per project, 100 projects included
Neon
    Docs
    Log inSign up
    /APIs & SDKs/Projects and branches/projects

    Neon CLI command: projects

    List, create, update, delete, recover, and get Neon projects

    The projects command lists, creates, updates, deletes, recovers, and retrieves Neon projects from the terminal. For information about projects in Neon, see Projects. Subcommands that show no options table accept only the global options. If --project-id is omitted, the CLI resolves it from your context file, auto-selects when your account has only one project, and otherwise asks you to pass --project-id.

    Subcommands: create, delete, get, list, recover, update

    neon projects list

    Lists projects that belong to your Neon account, as well as any projects that were shared with you.

    neon projects list [options]
    OptionDescriptionTypeDefaultRequired
    --org-idList projects of a given organizationstring—No
    --recoverable-onlyList only deleted projects within their deletion grace periodboolean—No

    • List projects in your default organization. If no organization context is set, the CLI prompts you to select one.

      neon projects list
      Projects
ID                      Name      Region ID      Created At
crimson-voice-12345678  frontend  aws-us-east-2  2026-04-15T11:17:30Z
calm-thunder-12121212   backend   aws-us-east-2  2026-04-10T15:21:01Z
nameless-hall-87654321  billing   aws-us-east-2  2026-04-10T14:35:17Z
Shared with you
ID                 Name  Region ID         Created At
noisy-fire-212121  API   aws-eu-central-1  2026-04-22T18:41:13Z

      In the default table, your currently linked project (the one recorded in .neon) is marked [current] next to its name.

    List all projects belonging to a specific organization:

    neon projects list --org-id org-xxxx-xxxx

    List projects that can be recovered (deleted within the last 7 days):

    neon projects list --recoverable-only
    Output
    Projects
ID                   Name       Region ID      Created At            Deleted At            Recoverable Until
crimson-voice-12345  myproject  aws-us-east-2  2026-04-15T11:17:30Z  2026-04-16T14:22:15Z  2026-04-23T14:22:15Z

    neon projects create

    Creates a Neon project.

    neon projects create [options]
    OptionDescriptionTypeDefaultRequired
    --block-public-connectionsWhen set, connections from the public internet are disallowed. This supersedes the AllowedIPs list. This parameter is under active development and its semantics may change in the future.boolean—No
    --block-vpc-connectionsWhen set, connections using VPC endpoints are disallowed. This parameter is under active development and its semantics may change in the future.boolean—No
    --cuThe number of Compute Units. Could be a fixed size (e.g. "2") or a range delimited by a dash (e.g. "0.5-3").string—No
    --databaseThe database name. If not specified, the default database name, neondb, will be used.stringneondbNo
    --hipaaEnable HIPAA compliance for the project.boolean—No
    --nameThe project name. If not specified, the name will be identical to the generated project IDstringproject IDNo
    --org-idThe project's organization IDstring—No
    --pg-versionMajor PostgreSQL version (14–19). Version 19 is available only in regions where it has been enabled.number—No
    --psqlConnect to a new project via psqlbooleanfalseNo
    --region-idThe region ID. Possible values: aws-us-west-2, aws-ap-southeast-1, aws-ap-southeast-2, aws-eu-central-1, aws-us-east-2, aws-us-east-1, azure-eastus2string—No
    --roleThe role name. If not specified, the default role name, {database_name}_owner, will be used.string{database}_ownerNo
    --secretsInclude connection credentials in command output. Use --no-secrets to omit thembooleantrueNo
    --set-contextSet the current context to the new projectbooleanfalseNo

    The --region-id value defaults to aws-us-east-2 if not specified. --block-public-connections and --block-vpc-connections are part of Private Networking; --hipaa enables HIPAA compliance for the project.

    note

    Neon projects created using the CLI use the default Postgres version, which is Postgres 18. To create a project with a different Postgres version, pass --pg-version:

    neon projects create --name mynewproject --pg-version 17

    You can also enable logical replication for an existing project with neon projects update <project-id> --enable-logical-replication (add --yes to skip the confirmation prompt), and create protected branches with neon branches create --protected.

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

    neon projects create --name mynewproject --region-id aws-us-west-2
    Output
    Project
ID          muddy-wood-123456
Name        mynewproject
Region ID   aws-us-west-2
Created At  2026-07-09T17:04:29Z

Connection URIs
Connection URI
postgresql://[user]:[password]@[neon_hostname]/[dbname]

    tip

    The Neon CLI provides a neon connection-string command you can use to extract a connection URI programmatically. See the connection-string command.

    Create a project with a specific Postgres major version:

    neon projects create --name mynewproject --pg-version 17

    Omit the connection string from the output, keeping it out of terminal scrollback and CI logs:

    neon projects create --name mynewproject --no-secrets

    Needs Neon CLI 4.9.0+; older versions ignore --no-secrets and still print the connection string.

    • Create a project with --output json, which returns the full project response data and is the recommended format for scripts and agents. The output below was captured on an earlier CLI version; new projects report "pg_version": 18.

      neon projects create --output json
      Show 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": 17,
    "proxy_host": "us-east-2.aws.neon.tech",
    "branch_logical_size_limit": 204800,
    "branch_logical_size_limit_bytes": 214748364800,
    "store_passwords": true,
    "creation_source": "neon",
    "history_retention_seconds": 604800,
    "created_at": "2026-08-04T16:16:45Z",
    "updated_at": "2026-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": "postgresql://alex:AbC123dEf@ep-cool-darkness-123456.us-east-2.aws.neon.tech/dbname?sslmode=require&channel_binding=require",
      "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 immediately. Arguments after -- are passed through to psql, so you can run an .sql file or a query on creation:

    neon projects create --psql
neon projects create --psql -- -f dump.sql
neon projects create --psql -- -c "SELECT version()"

    Create a project and set the Neon CLI project context to it:

    neon projects create --set-context

    neon projects update

    Updates a Neon project. The <id> is the project ID, which you can obtain by listing your projects or from the Settings page in the Neon Console.

    neon projects update <id> [options]
    OptionDescriptionTypeDefaultRequired
    --block-public-connectionsWhen set, connections from the public internet are disallowed. This supersedes the AllowedIPs list. This parameter is under active development and its semantics may change in the future. Use --block-public-connections=false to set the value to false.boolean—No
    --block-vpc-connectionsWhen set, connections using VPC endpoints are disallowed. This parameter is under active development and its semantics may change in the future. Use --block-vpc-connections=false to set the value to false.boolean—No
    --cuThe number of Compute Units. Could be a fixed size (e.g. "2") or a range delimited by a dash (e.g. "0.5-3").string—No
    --enable-logical-replicationEnable logical replication for all project endpoints. This suspends active endpoints and cannot be disabled.boolean—No
    --hipaaEnable HIPAA compliance for the project.boolean—No
    --nameThe project namestring—No
    --yesSkip the confirmation prompt when enabling logical replication.booleanfalseNo

    --block-public-connections, --block-vpc-connections, and --hipaa behave as described under projects create.

    Update the project name:

    neon projects update muddy-wood-123456 --name dev_project_1
    Output
    ID          muddy-wood-123456
Name        dev_project_1
Region ID   aws-us-west-2
Created At  2026-07-09T17:04:29Z

    Block connections from the public internet (see restrict public internet access):

    neon projects update orange-credit-12345678 --block-public-connections=true

    Enable logical replication for the project. This suspends active endpoints and cannot be disabled, so --yes skips the confirmation prompt:

    neon projects update orange-credit-12345678 --enable-logical-replication --yes

    neon projects delete

    Deletes a Neon project. The <id> is the project ID.

    neon projects delete <id> [options]
    neon projects delete muddy-wood-123456
    Output
    ID          muddy-wood-123456
Name        dev_project_1
Region ID   aws-us-west-2
Created At  2026-07-09T17:04:29Z

    Verify the deletion with neon projects list.

    neon projects recover

    Recovers a deleted project within the deletion recovery period. The <id> is the project ID, which you can obtain by listing recoverable projects with neon projects list --recoverable-only.

    neon projects recover <id> [options]
    neon projects recover crimson-voice-12345678
    Output
    ID          crimson-voice-12345678
Name        myproject
Region ID   aws-us-east-2
Created At  2026-04-15T11:17:30Z

    For details on what's recovered and what requires reconfiguration after recovery, see Recover a deleted project.

    neon projects get

    Retrieves details about a Neon project. The <id> is the project ID.

    neon projects get <id> [options]
    neon projects get muddy-wood-123456
    Output
    Project
Name               dev_project_1
ID                 muddy-wood-123456
Region ID          aws-us-west-2
Postgres Version   18
Organization       org-xxxxxxxx-xxxx
Default Compute    0.25 CU
History Retention  6 hours
Created At         2026-07-09T17:04:29Z
Updated At         2026-07-09T17:04:29Z

    The table shows a detail view: Postgres version, organization, default compute range, and history retention alongside the identifiers. For the complete project record, including all settings and quotas, use --output json.

    Was this page helpful?
    Edit on GitHub
    Previous diffNext branches

    On this page

    Copy neon init command