Forge CLI

Forge provides a comprehensive command-line interface that helps you develop, build, and deploy your applications. The CLI uses a hierarchical subcommand structure for better organization and includes commands for project management, code generation, database operations, and more.

Installation

Install the CLI Tool

# Homebrew (macOS/Linux) - recommended
brew install xraph/tap/forge

# Or using Go install
go install github.com/xraph/forge/cmd/forge@latest

# Verify installation
forge version

See the Installation guide for all available methods (Scoop, binary download, Linux packages, Docker).

CLI Commands Overview

# Get help
forge --help

# Get version information
forge version

# Initialize a new project
forge init

# Start development server
forge dev

# Generate code
forge generate app --name=my-app

# Build the application
forge build

# Deploy the application
forge deploy

Command Structure

Forge CLI uses a hierarchical subcommand structure for better organization:

forge <command> <subcommand> [flags]

Most commands support aliases for faster typing:

forge generate app       # Full command
forge gen app            # Alias
forge g app              # Short alias

Core Commands

Project Management

• forge init - Initialize a new Forge project
• forge doctor - Check system requirements and project health

Development

• forge dev - Start development server and tools
  • forge dev list - List available apps
  • forge dev build - Build app for development

Code Generation

• forge generate (aliases: gen, g) - Generate code from templates
  • forge generate app - Generate a new application
  • forge generate service - Generate a new service
  • forge generate extension - Generate a new extension
  • forge generate controller - Generate a controller
  • forge generate model - Generate a database model

Database Management

• forge db (aliases: database) - Database management tools
  • forge db migrate - Run database migrations
  • forge db rollback - Rollback database migrations
  • forge db status - Show migration status
  • forge db create - Create a new migration
  • forge db seed - Seed the database
  • forge db reset - Reset the database

Build and Deployment

• forge build — Build applications
• forge deploy — Deploy applications
  • forge deploy docker — Build and push Docker image
  • forge deploy k8s — Deploy to Kubernetes
  • forge deploy status — Show deployment status

Infrastructure

• forge infra — Infrastructure deployment and management
  • forge infra docker deploy — Deploy using Docker Compose
  • forge infra docker export — Export Dockerfiles and Compose config
  • forge infra k8s deploy — Deploy to Kubernetes
  • forge infra k8s export — Export Kubernetes manifests (Kustomize)
  • forge infra do deploy — Deploy to DigitalOcean App Platform
  • forge infra do export — Export DigitalOcean app spec
  • forge infra render deploy — Deploy to Render.com
  • forge infra render export — Export Render blueprint

Forge Cloud

• forge cloud — Forge Cloud managed deployment platform
  • forge cloud deploy — Deploy services to Forge Cloud
  • forge cloud status — Show deployment status
  • forge cloud login — Authenticate with Forge Cloud
  • forge cloud logout — Log out from Forge Cloud
  • forge cloud logs — View service logs
  • forge cloud rollback — Rollback to a previous version
  • forge cloud scale — Scale service instances

Extensions

• forge extension (aliases: ext) — Extension management tools
  • forge extension list — List available extensions
  • forge extension info — Show extension information

Client Tools

• forge client — Client generation and management tools

Quick Start Examples

Create a New API

forge init --layout=single-module --template=api
forge gen app -n api-gateway
forge gen ctrl -n users -a api-gateway
forge gen model -n User --fields=name:string,email:string
forge db create -n create_users_table
forge db migrate
forge dev -a api-gateway

Docker Development Workflow

forge init --layout=single-module
forge gen app -n api-gateway
forge dev --docker -a api-gateway -p 8080     # Run in Docker with hot reload

Microservices Development

forge init --layout=multi-module
forge gen app -n api-gateway
forge gen app -n auth-service
forge gen app -n user-service
forge build --production
forge deploy docker -a api-gateway -t v1.0.0
forge deploy k8s -e staging

Infrastructure Export and Deploy

forge infra docker export              # Generate Docker Compose + Dockerfiles
forge infra docker deploy --build      # Build and run with Docker Compose
forge infra k8s export                 # Generate Kubernetes manifests
forge infra k8s deploy --env=prod      # Deploy to Kubernetes

Forge Cloud Deployment

forge cloud login                       # Authenticate
forge cloud deploy -e prod              # Deploy to production
forge cloud status --env=prod           # Check status
forge cloud logs -s api-gateway -f      # Stream logs
forge cloud scale -s api-gateway -r 5   # Scale to 5 replicas

Configuration

Forge Configuration File

The .forge.yaml file configures your Forge project:

# .forge.yaml
project:
  name: my-project
  module: github.com/me/my-project
  layout: single-module  # or multi-module
  structure:
    cmd: ./cmd
    apps: ./apps
    pkg: ./pkg
    internal: ./internal
    deployments: ./deployments

dev:
  auto_discover: true
  hot_reload:
    enabled: true
    delay: 500ms
  watch:
    enabled: true
    paths:
      - "./apps/**/internal/**/*.go"
      - "./pkg/**/*.go"
    exclude:
      - "**/*_test.go"
      - "**/vendor/**"
  docker:
    image: golang:1.25-alpine
    network: bridge

database:
  driver: postgres
  migrations_path: ./database/migrations
  seeds_path: ./database/seeds

build:
  output_dir: ./bin
  auto_discover: true
  platforms:
    - os: linux
      arch: amd64
    - os: darwin
      arch: arm64

deploy:
  registry: ghcr.io/myorg
  docker:
    network: forge-network
  kubernetes:
    namespace: default

Environment Variables

# Set environment variables
export DATABASE_URL="postgres://user:pass@localhost/myapp"
export AUTH_SECRET="your-secret-key"

# Use in configuration
forge dev --env development

Aliases Quick Reference

Tips and Best Practices

1. Tab Completion: Most shells support tab completion. Run forge completion bash or forge completion zsh to enable it.

2. Help Everywhere: Add --help to any command to see detailed usage:

   forge --help
   forge generate --help
   forge generate app --help

3. Interactive Mode: Most commands prompt for missing required arguments:

   forge gen app    # Will prompt for name
   forge dev        # Will show app selector

4. Aliases: Use shorter aliases for faster typing:

   forge g app -n my-app     # Instead of forge generate app
   forge db up               # Instead of forge db migrate
   forge ext ls              # Instead of forge extension list

5. Config Search: Run commands from any subdirectory - .forge.yaml is found automatically.

Troubleshooting

Common Issues

Command not found:

# Check if forge is in PATH
which forge

# Reinstall if needed
go install github.com/xraph/forge/cmd/forge@latest

Permission errors:

# Fix permissions
sudo chown -R $(whoami) $GOPATH

Configuration errors:

# Validate configuration
forge doctor

# Check configuration
forge doctor --verbose

Debug Mode

# Enable debug mode
forge dev --debug

# Verbose output
forge dev --verbose

# Log level
forge dev --log-level debug