---
name: "Neon CLI (neonctl)"
description: "Skill for Neon CLI (neonctl) — auto-generated from documentation"
version: "1.0.0"
author: "skynet"
category: "infrastructure"
agents: ["claude-code", "codex", "gemini"]
tags: ["neon-cli", "infrastructure", "auto-generated"]
---

# Neon CLI (neonctl)

---
name: Neon CLI (neonctl)
description: Use this skill when you need to manage Neon PostgreSQL databases through the command line, including creating projects, managing branches, handling database connections, and performing database operations.
metadata:
  author: skynet
  version: 1.0.0
category: infrastructure
---

# Neon CLI (neonctl) Management

## Quick Start

```bash
# Install neonctl
npm install -g neonctl

# Authenticate
neonctl auth

# List projects
neonctl projects list

# Create a new project
neonctl projects create --name "my-app"
```

## Core Commands

### Authentication & Setup
```bash
# Interactive authentication
neonctl auth

# Set API key directly
neonctl auth --api-key YOUR_API_KEY

# Check current authentication status
neonctl auth show
```

### Project Management
```bash
# List all projects
neonctl projects list

# Create new project
neonctl projects create --name "production-db" --region us-east-1

# Get project details
neonctl projects get PROJECT_ID

# Delete project
neonctl projects delete PROJECT_ID

# Set default project
neonctl set-context --project-id PROJECT_ID
```

### Branch Operations
```bash
# List branches
neonctl branches list

# Create branch from main
neonctl branches create --name feature-branch

# Create branch from specific parent
neonctl branches create --name hotfix --parent-branch main

# Create branch with specific compute settings
neonctl branches create --name staging --compute-size small --suspend-timeout 3600

# Get branch details
neonctl branches get BRANCH_ID

# Delete branch
neonctl branches delete BRANCH_ID

# Reset branch to parent state
neonctl branches reset BRANCH_ID
```

### Database Management
```bash
# List databases in current project
neonctl databases list

# Create database
neonctl databases create myapp_db

# Create database on specific branch
neonctl databases create --branch-id BRANCH_ID production_db

# Delete database
neonctl databases delete myapp_db
```

### Connection Management
```bash
# Get connection string
neonctl connection-string --database-name myapp_db

# Get connection string for specific branch
neonctl connection-string --branch-id BRANCH_ID --database-name myapp_db

# Get pooled connection string
neonctl connection-string --pooled --database-name myapp_db

# Connect with psql
neonctl connection-string --database-name myapp_db --psql
```

## Workflow Patterns

### Feature Development Workflow
```bash
# 1. Create feature branch
neonctl branches create --name feature-user-auth

# 2. Get connection details
CONN_STRING=$(neonctl connection-string --branch-id BRANCH_ID --database-name myapp)

# 3. Run migrations on feature branch
psql "$CONN_STRING" -f migrations/001_add_users.sql

# 4. Test changes
# ... run tests ...

# 5. Clean up when done
neonctl branches delete feature-user-auth
```

### Staging Environment Setup
```bash
# Create staging branch
neonctl branches create --name staging --compute-size medium

# Create staging database
neonctl databases create --branch-id STAGING_BRANCH_ID staging_db

# Get connection string for deployment
neonctl connection-string --branch-id STAGING_BRANCH_ID --database-name staging_db --pooled
```

### Production Deployment
```bash
# Create production-ready branch
neonctl branches create --name production --compute-size large --suspend-timeout 0

# Set up production database
neonctl databases create --branch-id PROD_BRANCH_ID production_db

# Get production connection details
neonctl connection-string --branch-id PROD_BRANCH_ID --database-name production_db --pooled
```

## Decision Trees

### When to Create a New Branch
- **New feature development** → Create feature branch
- **Testing schema changes** → Create temporary test branch
- **Production deployment** → Create stable production branch
- **Rollback scenario** → Create branch from known good state

### Compute Size Selection
- **Development/Testing** → `--compute-size small`
- **Staging** → `--compute-size medium`
- **Production (low traffic)** → `--compute-size large`
- **Production (high traffic)** → `--compute-size xlarge`

### Connection String Types
- **Development** → Direct connection
- **Production** → `--pooled` for connection pooling
- **Serverless apps** → `--pooled` to handle connection limits

## Advanced Operations

### Backup and Restore Simulation
```bash
# Create backup branch from current state
neonctl branches create --name backup-$(date +%Y%m%d) --parent-branch main

# Restore by creating new branch from backup
neonctl branches create --name restored-main --parent-branch backup-20231201
```

### Multi-Environment Management
```bash
# Set up environments
neonctl branches create --name development --compute-size small
neonctl branches create --name staging --compute-size medium  
neonctl branches create --name production --compute-size large --suspend-timeout 0

# Quick environment switching
export NEON_PROJECT_ID="your-project-id"
export DEV_BRANCH_ID="dev-branch-id"
export STAGING_BRANCH_ID="staging-branch-id"
export PROD_BRANCH_ID="prod-branch-id"
```

### Monitoring and Metrics
```bash
# Get branch compute metrics
neonctl branches get BRANCH_ID --show-metrics

# List recent operations
neonctl operations list --limit 10

# Get operation details
neonctl operations get OPERATION_ID
```

## Troubleshooting

### Authentication Issues
**Error**: `Authentication required`
```bash
# Solution: Re-authenticate
neonctl auth
# Or set API key
export NEON_API_KEY="your-api-key"
```

### Branch Creation Failures
**Error**: `Branch limit exceeded`
```bash
# Solution: Delete unused branches
neonctl branches list
neonctl branches delete UNUSED_BRANCH_ID
```

**Error**: `Invalid parent branch`
```bash
# Solution: Verify parent branch exists
neonctl branches list
neonctl branches create --name new-branch --parent-branch VALID_BRANCH_NAME
```

### Connection String Issues
**Error**: `Database not found`
```bash
# Solution: Verify database exists on branch
neonctl databases list --branch-id BRANCH_ID
# Create if missing
neonctl databases create --branch-id BRANCH_ID DATABASE_NAME
```

### Compute Timeout Issues
**Error**: `Compute endpoint suspended`
```bash
# Solution: Adjust suspend timeout
neonctl branches update BRANCH_ID --suspend-timeout 7200
# Or disable auto-suspend for production
neonctl branches update BRANCH_ID --suspend-timeout 0
```

### Project Access Issues
**Error**: `Project not found`
```bash
# Solution: Verify project ID and permissions
neonctl projects list
neonctl set-context --project-id CORRECT_PROJECT_ID
```

## Best Practices

1. **Use descriptive branch names**: `feature-auth`, `hotfix-login`, `staging-v2`
2. **Set appropriate compute sizes** based on workload
3. **Use pooled connections** in production
4. **Clean up unused branches** regularly to stay within limits
5. **Set suspend timeouts** appropriately (0 for production, shorter for dev)
6. **Version control your database schemas** alongside branch creation
7. **Use environment variables** for connection strings in applications