{"id":18597,"library":"neonctl","title":"Neon CLI","description":"Official command-line tool for managing Neon Serverless Postgres databases. Version 2.22.0, released March 2026. Requires Node.js >=18. Provides project, branch, database, role, and IP allow management, plus connection string retrieval. Supports authentication via browser OAuth or API key. Installable via npm, Homebrew, or binary downloads. Not to be confused with neon.js SDK — this is a CLI binary, not a library for programmatic use.","status":"active","version":"2.22.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/neondatabase/neonctl","tags":["javascript"],"install":[{"cmd":"npm install neonctl","lang":"bash","label":"npm"},{"cmd":"yarn add neonctl","lang":"bash","label":"yarn"},{"cmd":"pnpm add neonctl","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"npx executes the CLI directly; global install optional.","wrong":"npm install neonctl && neonctl","symbol":"npx neonctl","correct":"npx neonctl"},{"note":"Global install recommended for regular use; local install in project works but CLI won't be in PATH.","wrong":"npm install neonctl (missing -g)","symbol":"npm i -g neonctl","correct":"npm i -g neonctl"},{"note":"Homebrew installation; upgrade with brew upgrade neonctl.","symbol":"brew install neonctl","correct":"brew install neonctl"}],"quickstart":{"code":"# Authenticate (opens browser)\nneonctl auth\n\n# Or with API key\nneonctl projects list --api-key $(process.env.NEON_API_KEY ?? '')\n\n# Create a project\nneonctl projects create --name my-project --region-id us-east-2 --pg-version 16\n\n# List branches\nneonctl branches list\n\n# Get connection string\nneonctl connection-string\n","lang":"typescript","description":"Shows authentication (browser or API key), project creation, branch listing, and connection string retrieval."},"warnings":[{"fix":"Use --org-slug <slug> instead of --org-id <id>.","message":"The --org-id flag is deprecated in favor of --org-slug for organization-scoped commands.","severity":"deprecated","affected_versions":">=2.19.0"},{"fix":"Upgrade Node.js to v18 or higher.","message":"Node.js 18 is required. Lower versions will fail to run (engine requirement).","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade to v2.20.0 or later, or ensure you are using the correct org slug.","message":"Commands that require a project ID will fail with 'org_id is required' if organization context is wrong. This was a bug in v2.19.1 fixed in v2.20.0.","severity":"gotcha","affected_versions":"2.19.1"},{"fix":"Use neonctl auth with browser OAuth for shared machines, or securely pass via environment variable.","message":"When using --api-key, it is visible in process listing; avoid in shared environments.","severity":"gotcha","affected_versions":">=1.0.0"},{"message":"The --branch flag for 'connection-string' command may be removed; use --branch-name or --branch-id explicitly.","severity":"deprecated","affected_versions":">=2.18.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Run 'npm i -g neonctl' or use 'npx neonctl' instead.","cause":"The package is not installed globally or not in PATH.","error":"neonctl: command not found"},{"fix":"Upgrade to v2.20.0 or later, or provide the correct --org-slug.","cause":"Missing or incorrect organization context when running project-scoped commands.","error":"Error: org_id is required","affected_versions":"2.19.1"},{"fix":"Run 'neonctl auth' to log in with browser, or pass your API key: 'neonctl projects list --api-key <key>'.","cause":"No authentication token found; either run 'neonctl auth' or provide a valid API key with --api-key.","error":"Error: API key not valid. Pass it via --api-key"},{"fix":"Retry after checking network connectivity. If issue persists, contact Neon support.","cause":"Network issue or API outage; check your internet connection and status.neon.tech.","error":"Error: Connection timeout. The Neon API is not reachable."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}