Neon CLI command: init

The init command sets up your app project to use Neon with your AI coding assistant. It authenticates via OAuth, creates a Neon API key, configures the Neon MCP server for your editor (installing the Neon Local Connect extension for Cursor and VS Code), and installs Neon agent skills. Run it once from your project root.

Usage

neon init [options]

You can also run init without installing the CLI:

npx neon@latest 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 installed agent skills help you get started, including configuring a database connection. For Cursor and VS Code, 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	Type	Default	Required
`--agent`, `-a`	Enable agent/JSON mode (agent type is auto-detected).	boolean	`false`	No
`--data`	JSON object with a "step" field to route to a specific phase and phase-specific options.	string	—	No
`--preview`	Enable preview features (e.g. project bootstrapping from templates).	boolean	`false`	No
`--skip-migrations`	Skip the migrations phase.	boolean	`false`	No

Use --agent to configure a specific editor, skipping the interactive selection prompt. Without --agent, init runs an interactive wizard that detects installed tools and lets you choose which to configure; if nothing is detected, you go straight to that list.

Coding assistant support

init is backed by the neon-init package bundled with neon. Besides Cursor, VS Code, and Claude Code, the interactive flow can configure any client that add-mcp supports. To register only the Neon MCP server in a client config (no init, no agent skills, no extension install), run npx add-mcp https://mcp.neon.tech/mcp. See Connect MCP clients to Neon.

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.

Examples

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

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

Show output

Output

┌  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. 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.