Next.js Fullstack Agent CLI
npm install kyawthiha-nextjs-agent-cli~/.nextjs-agent-cli/cred.json
bash
Windows (winget)
winget install BurntSushi.ripgrep.MSVC
winget install sharkdp.fd
macOS (Homebrew)
brew install ripgrep fd
Ubuntu/Debian
sudo apt install ripgrep fd-find
`
---
🚀 Quick Start
$3
`bash
npm install -g kyawthiha-nextjs-agent-cli
`
$3
`bash
next-agent config set-api-key
`
$3
`bash
next-agent start
`
---
📖 Commands
| Command | Description |
|---------|-------------|
| next-agent start | Start the AI agent to build a new project |
| next-agent config set-api-key | Set or update your Gemini API key |
| next-agent config show | Show current configuration |
| next-agent --help | Display all available commands |
$3
`bash
next-agent start [options]
Options:
-n, --project-name Project name (created in current directory)
-m, --max-iterations Maximum agent iterations (default: 500)
--skip-db Skip PostgreSQL configuration
--no-verbose Disable verbose logging
`
---
🎯 Interactive Workflow
$3
`
╔═══════════════════════════════════════════════════════════╗
║ 🚀 Next.js Fullstack Agent CLI ║
║ Build full-stack apps with AI assistance ║
╚═══════════════════════════════════════════════════════════╝
✔ Ready to build!
? What is your project name? my-app
`
$3
`
? Please enter your Gemini API Key: **
? Save API key for future sessions? Yes
✔ API key saved to C:\Users\User\.nextjs-agent-cli\cred.json
`
$3
`
? Select Gemini Model:
❯ gemini-3-flash-preview
gemini-3-pro-preview
`
$3
`
--- PostgreSQL Configuration ---
? Host: localhost
? Port: 5432
? Username: postgres
? Password: postgres
? Database Name: my-app
`
Use --skip-db to skip this step for static sites.
$3
`
? What do you want to build or modify?
> Build a todo app with user authentication and task categories
`
The agent will:
- 📝 Create an implementation plan
- ✅ Execute tasks step by step
- 🔍 Verify builds and runtime
- 🔧 Auto-fix errors when possible
---
🗂️ Project Structure
After the agent runs, your project will have:
`
my-app/
├── .agent/
│ ├── plan1.md # Implementation plan
│ └── task1.md # Task checklist
├── src/
│ ├── app/ # Next.js app router
│ ├── components/ # React components
│ └── lib/ # Utilities
├── prisma/ # Database schema (if using DB)
├── package.json
└── ...
`
---
⚙️ Configuration
$3
API keys are stored securely at:
- Windows: C:\Users\
- macOS/Linux: ~/.nextjs-agent-cli/cred.json
$3
You can also set your API key via environment variable:
`bash
export GEMINI_API_KEY=your_api_key_here
`
Priority: Environment variable > Credential store > Interactive prompt
---
🧪 After Generation
Once the agent finishes, run your project:
`bash
cd my-app
npm run dev
`
Open http://localhost:3000 in your browser.
---
🛠️ Development
$3
`bash
git clone https://github.com/kywthiha/nextjs-agent-cli.git
cd nextjs-agent-cli
npm install
npm run build
`
$3
`bash
npm run dev
`
---
📝 Examples
$3
`bash
next-agent start -n my-todo-app
Then enter: "Build a todo app with categories and due dates"
`
$3
`bash
next-agent start -n my-shop
Then enter: "Build a product catalog with shopping cart and checkout"
`
$3
`bash
next-agent start -n landing --skip-db
Then enter: "Build a modern landing page for a SaaS product"
``