Neon CLI command: init

Initialize an app project with Neon, including auth, MCP server, extensions, and agent skills

The `init` command

The init command sets up your app project to use Neon with your AI coding assistant. Run it once from your project root to get started.

This command will:

Authenticate via OAuth (opens your browser if needed)
Create a Neon API key
For Cursor and VS Code, install the Neon Local Connect extension and configure the MCP server
For Claude Code, configure the MCP server in ~/.claude.json
Install Neon agent skills

What gets created

Artifact	Location	Scope
Neon API key	Neon account (named `neonctl-init-{timestamp}`)	Account
OAuth credentials (created on first auth)	`~/.config/neonctl/credentials.json`	Global
MCP config (Cursor)	`~/.cursor/mcp.json` (written by extension)	Global
MCP config (VS Code)	VS Code global `mcp.json` (written by extension)	Global
MCP config (Claude Code)	`~/.claude.json` (written by init)	Global
Neon Local Connect extension	Cursor / VS Code	Global
Agent skills	`.agents/skills/`	Project
Skills symlink (Claude Code only)	`.claude/skills/neon-postgres`	Project
`skills-lock.json`	Project root	Project

Credentials and API keys

If you previously authenticated with neon auth, init reuses those credentials (from ~/.config/neonctl/credentials.json). Otherwise, it opens the browser for OAuth.

init creates a new API key each time it runs (named neonctl-init-{timestamp}). If you run it more than once, you can revoke old keys in the Neon Console API Keys settings.

For Claude Code, if a Neon MCP entry already exists in ~/.claude.json, init prompts before overwriting it.

Usage

Run from the root directory of your project:

npx neonctl@latest init

If you have the Neon CLI installed, you can also run:

neon init

After running the command, restart your editor and ask your AI assistant to "Get started with Neon" to launch an interactive onboarding guide. The command installs Neon agent skills to help you get started with Neon, including helping you configure a database connection. For Cursor and VS Code users, the Neon Local Connect extension also provides database schema browsing, SQL editing, and table data management directly in your IDE.

Under the hood, init runs npx skills add neondatabase/agent-skills --skill neon-postgres --agent <name> for each selected editor. You can also run this command directly to install skills without the rest of the init flow, or use npx skills add ... -g to install globally. See neon-postgres on skills.sh for more about the skill.

warning

Skills are installed at the project level in the current working directory. Run init from your project root, otherwise skills will end up in the wrong location. You may want to commit project-level files so teammates get the same skills, or add them to .gitignore for per-developer setup.

Options

Option	Description
`-a, --agent <name>`	Configure a specific editor, skipping the interactive selection prompt. Supported values: `cursor`, `copilot` (VS Code), `claude`.

When no --agent is specified, init is an interactive wizard that detects installed editors and lets you choose which to configure.

Example

Navigate to the root directory of your application and run the neonctl@latest init command:

cd /path/to/your/app
npx neonctl@latest init

The command outputs progress as it completes each step:

npx neonctl@latest init

┌  Adding Neon MCP server, extension (for VS Code and Cursor) and agent skills
│
◆  Which editor(s) would you like to configure? (Space to toggle each option, Enter to confirm your selection)
│  ◼ Cursor
│  ◼ VS Code
│  ◻ Claude CLI
│
◒  Authenticating...
┌────────┬──────────────────┬────────┬────────────────┐
│ Login  │ Email            │ Name   │ Projects Limit │
├────────┼──────────────────┼────────┼────────────────┤
│ alex   │ alex@domain.com  │ Alex   │ 100            │
└────────┴──────────────────┴────────┴────────────────┘
◇  Authentication successful ✓
│
◇  Installing agent skills for Neon...
│
◇  Agent skills installed ✓
│
◇  Neon Local Connect extension installed for Cursor / VS Code.
│
├  What's next? ───────────────────────────────────────────────────────────────────────────────────╮
│                                                                                                  │
│  Restart Cursor / VS Code, open the Neon extension and type                                      │
│  in "Get started with Neon" in your agent chat                                                   │
│                                                                                                  │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯
│
└  Have feedback? Email us at feedback@neon.tech

Manual setup

If you prefer to configure manually or need to set up for other IDEs, create a Neon API key in the Neon Console and use this configuration:

Example configuration for Claude Code (~/.claude.json):

{
  "mcpServers": {
    "Neon": {
      "type": "http",
      "url": "https://mcp.neon.tech/mcp",
      "headers": {
        "Authorization": "Bearer <NEON_API_KEY>"
      }
    }
  }
}

For detailed manual setup instructions for all editors, see Connect MCP clients.

Need help?

Join our Discord Server to ask questions or see what others are doing with Neon. For paid plan support options, see Support.