appgen-cli

The official command-line interface for AppGen - A modern, extensible project scaffolding platform

🚀 Quick Start

Get started with AppGen in seconds:

# Using npx (recommended)
npx appgen-cli

# Or install globally
npm install -g appgen-cli
appgen

# Create a project directly
npx appgen-cli my-app --template react-tailwind

📦 Installation

Global Installation

npm install -g appgen-cli
# or
yarn global add appgen-cli
# or
pnpm add -g appgen-cli

One-Time Usage (No Installation)

npx appgen-cli

🎯 Features

• 🎨 Interactive UI - Beautiful, user-friendly command-line interface
• 📦 Template Library - Access to curated, production-ready templates
• 🔌 Plugin System - Extend functionality with plugins
• 🔄 Project Upgrades - Keep your projects up-to-date
• 🏥 Health Checks - Diagnose and fix project issues
• 🎛️ Flexible Configuration - Customize to your workflow
• 💾 Local & Remote Templates - Use templates from anywhere

📖 Usage

Create a New Project

# Interactive mode (recommended)
appgen

# Specify project name
appgen my-awesome-project

# With template selection
appgen my-project --template react-tailwind

# Skip all prompts (use defaults)
appgen my-project --template node-express --yes

# Custom options
appgen my-project \
  --template react-tailwind \
  --skip-git \
  --skip-install \
  --verbose

List Available Templates

# List all templates
appgen list

# Filter by category
appgen list --category frontend
appgen list --category backend

# Filter by tags
appgen list --tag react
appgen list --tag typescript

# JSON output for scripting
appgen list --json

Upgrade Existing Project

# Upgrade current directory
appgen upgrade

# Upgrade specific directory
appgen upgrade ./my-project

# Preview changes (dry run)
appgen upgrade --dry-run

# Force upgrade (skip confirmations)
appgen upgrade --force

Health Check & Diagnostics

# Check project health
appgen doctor

# Auto-fix issues
appgen doctor --fix

# Verbose output
appgen doctor --verbose

🎛️ Command Reference

appgen new [name]

Create a new project from a template.

Arguments:

• name - Project name (optional, will prompt if not provided)

Options:

• -t, --template <name> - Template to use
• -y, --yes - Skip prompts and use defaults
• --skip-git - Skip git initialization
• --skip-install - Skip dependency installation
• --skip-hooks - Skip template lifecycle hooks
• --dry-run - Simulate without creating files
• -v, --verbose - Show detailed output

Examples:

appgen new my-app --template react-tailwind
appgen new api-server --template node-express --yes
appgen new --dry-run

appgen list

List available templates from the registry.

Options:

• --category <category> - Filter by category (frontend, backend, fullstack)
• --tag <tag> - Filter by tag (react, typescript, etc.)
• --json - Output as JSON

Examples:

appgen list --category frontend
appgen list --tag react --tag typescript
appgen list --json

appgen upgrade [path]

Upgrade an existing project to the latest template version.

Arguments:

• path - Project path (defaults to current directory)

Options:

• --dry-run - Preview changes without applying
• --force - Skip confirmation prompts
• -v, --verbose - Show detailed output

Examples:

appgen upgrade
appgen upgrade ./my-project --dry-run
appgen upgrade --force

appgen doctor

Run health checks on your system and project.

Options:

• --fix - Attempt to automatically fix issues
• -v, --verbose - Show detailed diagnostics

Examples:

appgen doctor
appgen doctor --fix --verbose

⚙️ Configuration

Environment Variables

Configure AppGen behavior with environment variables:

• APPGEN_REGISTRY_URL - Custom template registry URL
• APPGEN_CACHE_DIR - Custom cache directory
• DEBUG - Enable debug logging (DEBUG=appgen:*)
• NO_COLOR - Disable colored output

Example:

APPGEN_REGISTRY_URL=https://my-registry.com appgen list
DEBUG=appgen:* appgen new my-app

Registry Configuration

Create a .appgenrc.json file in your project root or home directory:

{
  "registry": "https://my-custom-registry.com",
  "templates": {
    "default": "react-tailwind"
  },
  "plugins": ["@myorg/appgen-plugin-custom"]
}

🎨 Available Templates

AppGen comes with production-ready templates:

Frontend

• react-tailwind - React + Tailwind CSS + TypeScript + Vite
• react-chakra - React + Chakra UI + TypeScript
• next-tailwind - Next.js + Tailwind CSS + TypeScript
• vue-tailwind - Vue 3 + Tailwind CSS + TypeScript

Backend

• node-express - Express + TypeScript + REST API
• nest-microservices - NestJS + Microservices
• fastify-api - Fastify + TypeScript + Swagger

Fullstack

• next-fullstack - Next.js + tRPC + Prisma
• remix-fullstack - Remix + Prisma + Tailwind

🔌 Plugins

Extend AppGen functionality with plugins:

# Add during project creation
appgen new my-app --plugins eslint,prettier,docker

# Available plugins
--plugins eslint          # Add ESLint configuration
--plugins prettier        # Add Prettier configuration
--plugins docker         # Add Docker setup
--plugins tailwind       # Add Tailwind CSS
--plugins testing        # Add testing framework

🛠️ Development

Want to contribute or customize AppGen?

# Clone the repository
git clone https://github.com/appgen/appgen.git
cd appgen

# Install dependencies
pnpm install

# Build packages
pnpm build

# Run CLI in development
cd packages/cli
pnpm dev

# Run tests
pnpm test

📚 Documentation

• Template Guidelines
• Plugin Development
• API Reference
• Migration Guide

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

🐛 Troubleshooting

Common Issues

Problem: Command not found after global installation

# Solution: Ensure npm global bin is in PATH
npm config get prefix
# Add <prefix>/bin to your PATH

Problem: Template download fails

# Solution: Clear cache and retry
rm -rf ~/.appgen/cache
appgen new my-app --template react-tailwind

Problem: Permission errors

# Solution: Run with appropriate permissions or use npx
npx appgen-cli new my-app

Get Help

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions
• 🔍 Use appgen doctor for diagnostics

📄 License

MIT © AppGen Team

🙏 Acknowledgments

AppGen is inspired by excellent tools in the ecosystem:

• create-vite
• create-next-app
• create-t3-app

Made with ❤️ by the AppGen Team