Forge Cli Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer global require laravel/forge-cli
   

   Ensure ~/.composer/vendor/bin is in your PATH.

2. Authentication:

   forge-cli auth login
   

   Follow prompts to authenticate via Forge API token (stored securely in ~/.forge-cli).

3. First Use Case: List available servers:

   forge-cli server:list
   

   Deploy a Laravel app:

   forge-cli site:deploy <site-id>
   

Key Starting Points

• Forge Dashboard: https://forge.laravel.com/docs/1.0/cli.html
• SSH Configuration:

  forge-cli ssh:configure
  

  (Auto-generates SSH keys and configures remote access.)

Implementation Patterns

Core Workflows

1. Server Management

• Provisioning:

  forge-cli server:create --name "prod-server" --server-type "digital_ocean" --plan "basic"
  

• Rebooting:

  forge-cli server:reboot <server-id>
  

• Tagging (for filtering):

  forge-cli server:tag <server-id> "env:production"
  

2. Site Deployment

• Deploy from Git:

  forge-cli site:deploy <site-id> --branch "main"
  

• Rollback:

  forge-cli site:rollback <site-id>
  

• Environment Sync:

  forge-cli env:pull <site-id> .env  # Pull remote .env to local
  forge-cli env:push <site-id> .env  # Push local .env to server
  

3. CI/CD Integration

• Automated Deployments (GitHub Actions example):

  - name: Deploy to Forge
    run: |
      forge-cli site:deploy ${{ secrets.FORGE_SITE_ID }} --branch ${{ github.ref_name }}
    env:
      FORGE_API_TOKEN: ${{ secrets.FORGE_API_TOKEN }}
  

• Environment Variables: Use env:push to sync secrets post-deployment (avoid hardcoding in repo).

4. Logging & Debugging

• Tail Logs:

  forge-cli site:logs <site-id> --follow
  

• Queue Worker Logs:

  forge-cli daemon:logs <site-id> --daemon "queue:worker"
  

• Database Shell:

  forge-cli database:shell <site-id>
  

5. SSH & Remote Commands

• Run Custom Commands:

  forge-cli ssh <server-id> "php artisan queue:work --once"
  

• Open Server in Browser:

  forge-cli open <server-id>
  

Integration Tips

• Laravel Artisan Hooks: Extend app/Console/Kernel.php to trigger Forge deployments post-migration:

  protected function commands()
  {
      $this->call('forge:deploy', [
          '--site-id' => env('FORGE_SITE_ID'),
          '--branch' => 'main',
      ]);
  }
  

  (Requires custom forge:deploy command using the CLI under the hood.)

• Local Development Sync: Use env:pull in a post-clone Git hook to sync .env files:

  forge-cli env:pull <site-id> .env.production
  

• Multi-Environment Workflows: Tag servers/sites by environment (e.g., env:staging) and filter CLI commands:

  forge-cli site:list --tag "env:staging"
  

Gotchas and Tips

Pitfalls

1. Authentication Issues:

   • Symptom: 401 Unauthorized errors.
   • Fix:
     • Ensure FORGE_API_TOKEN is set (check ~/.forge-cli/config.json).
     • Regenerate token in Forge dashboard if corrupted.
     • For CI, use FORGE_API_TOKEN env var (not interactive login).

2. SSH Configuration:

   • Symptom: Permission denied (publickey).
   • Fix: Run forge-cli ssh:configure to regenerate keys. Verify ~/.ssh/config includes Forge’s SSH settings.

3. Deployment Failures:

   • Symptom: Silent failures or partial deploys.
   • Debug: Use --verbose flag:

     forge-cli site:deploy <site-id> --verbose
     

     Check server logs:

     forge-cli site:logs <site-id> --follow
     

4. Environment Variable Conflicts:

   • Symptom: .env files not updating.
   • Fix: Ensure env:push targets the correct path (e.g., /home/forge/app/.env). Use --force to overwrite:

     forge-cli env:push <site-id> .env --force
     

5. Non-Interactive Mode:

   • Symptom: Commands hang in CI/CD.
   • Fix: Use --no-interaction flag:

     forge-cli site:deploy <site-id> --no-interaction
     

     Pre-configure answers in ~/.forge-cli/config.json:

     {
       "deploy_branch": "main",
       "deploy_message": "CI Deployment"
     }
     

Debugging Tips

• Check CLI Version:

  forge-cli --version
  

  Update if outdated (CLI warns users automatically).

• Inspect API Calls: Enable debug mode:

  forge-cli --debug server:list
  

  (Logs raw API responses to ~/.forge-cli/forge-cli.log.)

• SSH Debugging: Use -vvv for verbose SSH output:

  forge-cli ssh <server-id> "command" -vvv
  

Extension Points

1. Custom Commands: Extend the CLI by creating a Laravel Zero command that wraps forge-cli:

   // app/Console/Commands/DeployToForge.php
   public function handle()
   {
       $output = $this->callSilently('forge:deploy', [
           '--site-id' => $this->argument('site-id'),
           '--branch' => $this->option('branch'),
       ]);
       $this->info($output);
   }
   

2. Provider-Specific Logic: Override default provider behavior by extending the CLI’s ServerProvider class (advanced).

3. Webhook Triggers: Use Forge’s webhooks to trigger CLI commands via HTTP endpoints (e.g., deploy on Git push).

Configuration Quirks

• Custom SSH Ports: Configure in ~/.forge-cli/config.json:

  {
    "ssh_port": 2222
  }
  

  (Affects all ssh commands.)

• Rate Limits: Forge API has rate limits (~60 requests/minute). Batch commands or add retries:

  forge-cli --retry 3 server:list
  

• PHP Version Pinning: Ensure your local PHP version matches the server’s (CLI uses server’s PHP for deployments). Check with:

  forge-cli server:show <server-id> --php