Forjex CLI

The Modern CLI for Instant Project Scaffolding

Generate, configure, and deploy your next project in seconds.

🚀 Features

• 🎯 One Command Setup - Create GitHub repos, add CI/CD, and deploy to Vercel with a single command
• 🤖 Smart Commit Messages - Generates smart commit messages that describe your changes accurately
• ⚡ Lightning Fast - Optimized workflows that save you hours of manual configuration
• 🔄 Auto-Deployment - Push to GitHub and watch your changes deploy automatically to Vercel
• 🛠️ Multi-Framework Support - Works with Next.js, React, Vue, Python, Go, Rust, and more
• 📦 Package Manager Agnostic - Works seamlessly with npm, yarn, pnpm, and bun
• 🔐 Secure Authentication - GitHub OAuth device flow - no tokens to manage

📦 Installation

Install Forjex globally using your preferred package manager:

# npm
npm install -g forjex

# yarn
yarn global add forjex

# pnpm
pnpm add -g forjex

# bun
bun add -g forjex

🎯 Quick Start

Navigate to your project directory and run:

forjex forge

That's it! Forjex will guide you through:

1. Authenticating with GitHub (browser-based OAuth)
2. Creating or selecting a repository
3. Setting up CI/CD pipeline (GitHub Actions)
4. Deploying to Vercel (optional)

📖 Usage

Basic Command

forjex forge

Interactive Options

When you run forjex forge, you'll be prompted to choose:

• ✨ Create a new GitHub repository - Start fresh with a new repo
• 🔗 Push to an existing GitHub repository - Use an existing repo
• ⚙️ Add CI/CD pipeline (GitHub Actions) - Automated testing and building
• 🚀 Deploy to Vercel - Instant deployment with auto-deploy on push

You can select any combination of these options!

🔧 How It Works

1. GitHub Repository Setup

Forjex automatically:

• Creates a new GitHub repository (or connects to existing)
• Initializes git in your local directory
• Adds all your files
• Generates smart commit messages by analyzing your code changes
• Pushes to GitHub

Example commit messages generated by Forjex:

feat: add Button and Modal components to navbar.tsx
fix: update authentication logic in auth.ts
chore: add axios import to api.ts
docs: update README

2. CI/CD Pipeline

Forjex detects your project type and generates a customized GitHub Actions workflow:

Supported Languages/Frameworks:

• Node.js - Next.js, React, Vue, Angular, etc.
• Python - Django, Flask, FastAPI
• Go - Any Go project
• Rust - Cargo projects

What the pipeline does:

• ✅ Runs on every push to main and pull requests
• ✅ Tests on multiple Node versions (20.x, 22.x)
• ✅ Lints your code
• ✅ Runs tests (if available)
• ✅ Builds your project

3. Vercel Deployment

Forjex deploys your project to Vercel with:

• Auto-framework detection (Next.js, React, Vue, etc.)
• Automatic GitHub integration - future pushes trigger deployments
• Production-ready URLs - Get your live URL instantly

🎨 Examples

Example 1: New Next.js Project

# Create a new Next.js app
npx create-next-app@latest my-app
cd my-app

# Set up everything with Forjex
forjex forge

What happens:

1. Authenticates with GitHub ✓
2. Creates my-app repository on GitHub ✓
3. Generates CI/CD workflow for Node.js ✓
4. Analyzes your code and creates commit message ✓
5. Pushes to GitHub ✓
6. Deploys to Vercel ✓
7. Shows you the live URL ✓

Example 2: Existing Project

# Navigate to your existing project
cd my-existing-project

# Run Forjex
forjex forge

# Select "Push to an existing GitHub repository"
# Forjex finds your remote or lets you enter one

Example 3: CI/CD Only

cd my-project
forjex forge

# Uncheck "Deploy to Vercel"
# Only set up GitHub + CI/CD

🔐 Authentication

First Time Setup

When you first run Forjex:

1. Forjex opens your browser automatically
2. You'll see a code like: ABCD-EFGH
3. Enter the code on GitHub
4. Click "Authorize"
5. Done! Your credentials are saved securely

Your credentials are stored locally in:

• ~/.forjex/config.json (GitHub token)
• Vercel CLI handles Vercel auth internally

Re-authentication

Forjex remembers your authentication. You won't need to log in again unless:

• You explicitly log out
• Your token expires (after 1 year)

📁 Project Detection

Forjex automatically detects your project type by looking for:

If Forjex can't detect your project type, it will skip CI/CD generation.

🎯 Smart Commit Messages

Forjex analyzes your code changes and generates meaningful commit messages following Conventional Commits:

Commit Types:

• feat: - New features
• fix: - Bug fixes
• docs: - Documentation changes
• style: - CSS/styling changes
• refactor: - Code refactoring
• test: - Test additions
• chore: - Maintenance tasks

Examples:

# Adding a new component
feat: add LoginForm component to auth.tsx

# Fixing a bug
fix: resolve authentication timeout in api.ts

# Updating documentation
docs: update installation instructions in README

# Removing old code
refactor: remove deprecated functions from utils.ts

🔄 CI/CD Workflow

The generated GitHub Actions workflow includes:

# .github/workflows/ci.yml

✓ Checkout code
✓ Setup Node.js (20.x, 22.x)
✓ Install dependencies
✓ Lint code
✓ Run tests
✓ Build project

Customization:
You can edit .github/workflows/ci.yml after generation to add:

• Additional test suites
• Code coverage reports
• Deployment steps
• Notifications

🚀 Deployment

Vercel Integration

When you deploy with Forjex:

1. First deployment - Deploys your current code
2. Future deployments - Automatic on every push to main
3. Preview deployments - Automatic on pull requests

Your deployment URL:

✅ Deployed to Vercel
   https://your-project.vercel.app

Auto-Deployment

After initial setup, every push to main automatically:

1. Triggers GitHub Actions (build & test)
2. Deploys to Vercel (if tests pass)
3. Updates your production URL

🛠️ Troubleshooting

Issue: "Command not found: forjex"

Solution:

# Check if installed globally
npm list -g forjex

# If not found, reinstall
npm install -g forjex

# Verify installation
forjex --version

Issue: "Authentication failed"

Solution:

1. Check your internet connection
2. Make sure you completed the browser authentication
3. Try removing saved credentials:

   rm -rf ~/.forjex

4. Run forjex forge again

Issue: "Could not detect project type"

Solution:

• Make sure you have a package.json, requirements.txt, go.mod, or Cargo.toml
• For Node.js projects: Run npm init -y to create a package.json

Issue: "Vercel deployment failed"

Solution:

1. Make sure you completed Vercel authentication
2. Check Vercel CLI is installed: vercel --version
3. Try manual Vercel login: vercel login

Issue: "Push failed - already a git repository"

Solution:
When prompted "Commit and push changes?", select Yes to commit and push your changes.

📝 Configuration Files

Forjex creates these files in your project:

.github/workflows/ci.yml

Your CI/CD pipeline configuration. Customize as needed.

vercel.json (if deploying to Vercel)

Vercel deployment configuration. Auto-generated based on your framework.

.gitignore (if selected)

Common ignore patterns for your project type.

README.md (if selected)

Basic project documentation.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• GitHub for the OAuth device flow API
• Vercel for seamless deployment
• The open-source community

🔗 Links

• Website: https://forjex.vercel.app
• Documentation: https://forjex.vercel.app/docs
• GitHub: https://github.com/daviddozie/forjex
• Issues: https://github.com/daviddozie/forjex/issues

Made with ❤️ by David

If you find Forjex useful, please consider giving it a ⭐ on GitHub!