📦 Installation

Using npx (Recommended — No Install Required)

npx forgestack-os-cli create my-app

Global Installation

npm install -g forgestack-os-cli
forgestack-os-cli create my-app

If you get command not found after global install:

1. Check your npm bin directory:

   npm config get prefix

2. Add it to your PATH:

   • Windows (PowerShell):

     [System.Environment]::SetEnvironmentVariable("Path", "$env:Path;$(npm config get prefix)", [System.EnvironmentVariableTarget]::User)

   • macOS/Linux:

     export PATH="$(npm config get prefix)/bin:$PATH"

3. Verify installation:

   forgestack-os-cli --version

⚡ Quick Start

# Interactive mode — answer prompts to configure your stack
npx forgestack-os-cli create my-saas-app

# Use a preset for instant setup
npx forgestack-os-cli create my-app --preset next-nest-clerk-pg

# Specify options directly
npx forgestack-os-cli create my-app \
  --frontend nextjs \
  --backend nestjs \
  --auth clerk \
  --database postgresql \
  --docker

In 30 seconds, you get:

• ✅ Full authentication system
• ✅ Database with migrations
• ✅ API documentation (Swagger)
• ✅ Docker configuration
• ✅ TypeScript everywhere

🧰 Commands

create — Generate a New Project

npx forgestack-os-cli create <project-name> [options]

doctor — Validate Environment ✨ NEW

Diagnose your dev environment and catch issues before they slow you down.

npx forgestack-os-cli doctor [options]

Example Output:

🩺 ForgeStack Doctor Report

📋 Node.js & Package Managers

✅ Node.js: Node version: 20.2.0
✅ npm: npm version: 10.2.0
⏭️ pnpm: pnpm is not installed (optional)

📋 Environment Variables

❌ Missing .env Variables: DATABASE_URL, JWT_SECRET
   💡 Fix: Add the missing variables to your .env file

📋 Database Connectivity

✅ PostgreSQL Connection: Successfully connected to PostgreSQL

📋 Prisma ORM

✅ Prisma Schema: Prisma schema is valid
✅ Prisma Client: Prisma client is generated
⚠️ Prisma Migrations: Pending migrations detected
   💡 Fix: Run: npx prisma migrate dev

📋 Docker

✅ Docker: Docker installed: 24.0.7
✅ Docker Daemon: Docker daemon is running
✅ Docker Compose: Docker Compose V2: 2.23.0

📋 Port Availability

❌ Backend (port 3000): Port 3000 is used by node (PID: 12345)
   💡 Fix: Stop the process or use a different port. Kill: taskkill /PID 12345 /F
✅ Frontend (port 5173): Port 5173 is available

───────────────────────────────────────────────────────────

📊 Summary:

   Total Checks: 12
   Passed: 8
   Warnings: 1
   Failed: 2
   Skipped: 1

✖ Found 2 critical issue(s) that need to be fixed.

Checks Performed:

| Check | Description | | -------------- | -------------------------------------------------- | | 🟢 Node.js | Version against .nvmrc or package.json engines | | 🟢 npm/pnpm | Package manager availability | | 🟢 Environment | Missing variables from .env.example | | 🟢 Database | PostgreSQL, MongoDB, MySQL, SQLite connectivity | | 🟢 Prisma | Client generation, schema validation, migrations | | 🟢 Docker | Installation, daemon status, Compose availability | | 🟢 Ports | Backend (3000) and frontend (5173) availability | | 🟢 ESLint | Linting issues (with --lint) | | 🟢 TypeScript | Compile errors (with --lint) |

CI/CD Integration:

# GitHub Actions
- name: Validate Environment
  run: |
    npx forgestack-os-cli doctor --json > doctor-report.json
    if [ $(jq '.summary.failed' doctor-report.json) -gt 0 ]; then
      exit 1
    fi

organize — File Organization Utility

Organize files by type or date with duplicate detection.

npx forgestack-os-cli organize <folder-path> [options]

File Categories:

• 📷 Images: jpg, png, gif, svg, webp, bmp, ico
• 📄 Documents: pdf, doc, docx, txt, xlsx, csv, md
• 🎬 Videos: mp4, mkv, avi, mov, wmv, flv
• 🎵 Audio: mp3, wav, flac, aac, m4a, ogg
• 💻 Code: js, ts, py, java, cpp, go, rs, rb
• 📦 Archives: zip, rar, 7z, tar, gz, bz2
• 📊 Data: json, xml, yaml, sql, db, sqlite
• ⚙️ Executables: exe, msi, app, deb, rpm

Example:

# Organize Downloads by file type with duplicate detection
npx forgestack-os-cli organize ~/Downloads --strategy type --duplicates

# Organize photos by month
npx forgestack-os-cli organize ~/Pictures --strategy date

run-tasks — Batch Task Runner

Execute shell commands from JSON config with parallel support.

npx forgestack-os-cli run-tasks <config-path> [options]

Config Format (tasks.json):

{
  "tasks": [
    {
      "name": "Build Frontend",
      "command": "npm run build",
      "cwd": "./frontend"
    },
    { "name": "Build Backend", "command": "npm run build", "cwd": "./backend" },
    { "name": "Run Tests", "command": "npm test" },
    { "name": "Deploy", "command": "npm run deploy" }
  ],
  "parallel": false,
  "stopOnError": true
}

Example:

# Run sequentially
npx forgestack-os-cli run-tasks ./build-pipeline.json

# Run in parallel
npx forgestack-os-cli run-tasks ./build-pipeline.json --parallel

# Continue on errors
npx forgestack-os-cli run-tasks ./tasks.json --stop-on-error false

📚 Examples

Interactive Mode (Recommended)

npx forgestack-os-cli create my-saas
# Answer prompts to configure your perfect stack

Using Presets

# Enterprise: Next.js + NestJS + Clerk + PostgreSQL
npx forgestack-os-cli create my-enterprise --preset next-nest-clerk-pg

# Startup: React + Express + JWT + MongoDB
npx forgestack-os-cli create my-startup --preset react-express-jwt-mongo

# Modern: Next.js + Fastify + Supabase + tRPC
npx forgestack-os-cli create my-modern --preset next-fastify-supabase-trpc

Using Flags

# RESTful API with PostgreSQL
npx forgestack-os-cli create my-api \
  --frontend react-vite \
  --backend express \
  --auth jwt \
  --database postgresql \
  --api rest \
  --docker

# GraphQL with MongoDB
npx forgestack-os-cli create my-graphql \
  --frontend vue-vite \
  --backend nestjs \
  --auth firebase \
  --database mongodb \
  --api graphql

# Multi-tenant SaaS
npx forgestack-os-cli create my-saas \
  --preset next-nest-clerk-pg \
  --multi-tenant \
  --docker

JSON Stack Config

npx forgestack-os-cli create my-custom --stack '{
  "frontend": "nextjs",
  "backend": "fastify",
  "auth": "supabase",
  "database": "postgresql",
  "apiStyle": "trpc",
  "docker": true,
  "multiTenant": true
}'

📁 Generated Project Structure

my-app/
├── 📁 frontend/              # React/Next.js/Vue/Svelte
│   ├── 📁 src/
│   ├── 📄 package.json
│   ├── 📄 tsconfig.json
│   └── 📄 vite.config.ts
│
├── 📁 backend/               # Express/Fastify/NestJS/Bun
│   ├── 📁 src/
│   │   ├── 📁 auth/          # Authentication module
│   │   ├── 📁 users/         # User management
│   │   └── 📄 main.ts
│   ├── 📄 package.json
│   ├── 📄 tsconfig.json
│   └── 📄 .env.example
│
├── 📁 docker/                # If --docker enabled
│   ├── 📄 docker-compose.yml
│   ├── 📄 frontend.Dockerfile
│   └── 📄 backend.Dockerfile
│
├── 📄 .env.example           # Environment template
├── 📄 package.json           # Monorepo workspace
└── 📄 README.md              # Project-specific docs

❓ Troubleshooting

Using npx? Use the full package name:

npx forgestack-os-cli create my-app

Installed globally? Check your PATH includes npm's bin directory.

The package name is forgestack-os-cli, not forgestack:

# ✅ Correct
npx forgestack-os-cli create my-app

# ❌ Wrong
npx forgestack create my-app

Use create, not init:

# ✅ Correct
npx forgestack-os-cli create my-app

# ❌ Wrong
npx forgestack-os-cli init my-app

Available presets (case-sensitive):

• next-nest-clerk-pg
• react-express-jwt-mongo
• next-fastify-supabase-trpc

ForgeStack requires Node.js 18+:

node --version  # Check version
nvm install 18  # Upgrade with nvm

🔗 Links

• 📚 Documentation
• 🐛 Issues
• 💬 Discussions
• 📦 npm Package

👨‍💻 Author

📄 License

MIT License — see LICENSE for details.