In Neon, you can provision Postgres databases in < 1s. Don't believe us? Check out this demo
Command line & SDKs

Neon CLI

Use the Neon CLI to manage Neon directly from the terminal

The Neon CLI is a command-line interface that lets you manage Neon directly from the terminal. This documentation references all commands and options available in the Neon CLI.

Install

To install the Neon CLI via npm:

npm i -g neonctl

Requires Node.js 18.0 or higher.

For more about installing, upgrading, and connecting, see Neon CLI — Install and connect.

Synopsis

neonctl --help
usage: neonctl <command> [options]                               [aliases: neon]

Commands:
  neonctl auth                        Authenticate              [aliases: login]
  neonctl me                          Show current user
  neonctl projects                    Manage projects         [aliases: project]
  neonctl ip-allow                    Manage IP Allow
  neonctl branches                    Manage branches          [aliases: branch]
  neonctl databases                   Manage databases   [aliases: database, db]
  neonctl roles                       Manage roles               [aliases: role]
  neonctl operations                  Manage operations     [aliases: operation]
  neonctl connection-string [branch]  Get connection string        [aliases: cs]
  neonctl set-context                 Set the current context
  neonctl completion                  generate completion script

Global options:
  -o, --output      Set output format
                  [string] [choices: "json", "yaml", "table"] [default: "table"]
  --config-dir      Path to config directory [string] [default: ""]
  --api-key         API key  [string] [default: ""]
  --analytics       Manage analytics. Example: --no-analytics, --analytics false
                                                       [boolean] [default: true]
  -v, --version     Show version number                                [boolean]
  -h, --help        Show help                                          [boolean]

Options:
--context-file      Context file [string] [default: (current-context-file)]

Commands

CommandSubcommandsDescription
authAuthenticate
meShow current user
projectslist, create, update, delete, getManage projects
ip-allowlist, add, remove, resetManage IP Allow
brancheslist, create, reset, restore, rename, schema-diff, set-primary, add-compute, delete, getManage branches
databaseslist, create, deleteManage databases
roleslist, create, deleteManage roles
operationslistManage operations
connection-stringGet connection string
set-contextSet context for session
completionGenerate a completion script

Global options

Global options are supported with any Neon CLI command.

OptionDescriptionTypeDefault
-o, --outputSet the Neon CLI output format (json, yaml, or table)stringtable
--config-dirPath to the Neon CLI configuration directorystring/home/<user>/.config/neonctl
--api-keyNeon API keystringNEON_API_KEY environment variable
--analyticsManage analyticsbooleantrue
-v, --versionShow the Neon CLI version numberboolean-
-h, --helpShow the Neon CLI helpboolean-
  • -o, --output

    Sets the output format. Supported options are json, yaml, and table. The default is table. Table output may be limited. The json and yaml output formats show all data.

    neonctl me --output json
  • --config-dir

    Specifies the path to the neonctl configuration directory. To view the default configuration directory containing you credentials.json file, run neonctl --help. The credentials file is created when you authenticate using the neonctl auth command. This option is only necessary if you move your neonctl configuration file to a location other than the default.

    neonctl projects list --config-dir /home/<user>/.config/neonctl
  • --api-key

    Specifies your Neon API key. You can authenticate using a Neon API key when running a Neon CLI command instead of using neonctl auth. For information about obtaining an Neon API key, see Create an API key.

    neonctl <command> --api-key <neon_api_key>

    To avoid including the --api-key option with each CLI command, you can export your API key to the NEON_API_KEY environment variable.

    export NEON_API_KEY=<neon_api_key>

    info

    The authentication flow for the Neon CLI follows this order:

    • If the --api-key option is provided, it is used for authentication.
    • If the --api-key option is not provided, the NEON_API_KEY environment variable setting is used.
    • If there is no --api-key option or NEON_API_KEY environment variable setting, the CLI looks for the credentials.json file created by the neonctl auth command.
    • If the credentials file is not found, the Neon CLI initiates the neonctl auth web authentication process.
  • --analytics

    Analytics are enabled by default to gather information about the CLI commands and options that are used by our customers. This data collection assists in offering support, and allows for a better understanding of typical usage patterns so that we can improve user experience. Neon does not collect user-defined data, such as project IDs or command payloads. To opt-out of analytics data collection, specify --no-analytics or --analytics false.

  • -v, --version

    Shows the Neon CLI version number.

    $ neonctl --version
    1.15.0
  • -h, --help

    Shows the neonctl command-line help. You can view help for neonctl, a neonctl command, or a neonctl subcommand, as shown in the following examples:

    neonctl --help
    
    neonctl branches --help
    
    neonctl branches create --help

Options

OptionDescriptionTypeDefault
--context-fileThe context file for CLI sessionsstringcurrent-context-file
  • --context-file

    Sets a background context for your CLI sessions, letting you perform project or branch-specific actions without having to specify the project or branch id in every command. For example, this command lists all branches using the branches list command. No need to specify the project since the context file provides it.

    neonctl branches list --context-file path/to/context_file_name

    To define a context file, see Neon CLI commands — set-context.

GitHub repository

The GitHub repository for the Neon CLI is found here.

Last updated on

Edit this page
Was this page helpful?