Cloud Cli Laravel Package

Getting Started

Minimal Steps

1. Installation:

   gh repo clone laravel/cloud-cli && cd cloud-cli && composer install
   

   Add the alias to your shell config (e.g., ~/.zshrc or ~/.bashrc):

   alias cloud="php $(pwd)/cloud"
   

   Reload your shell (source ~/.zshrc or equivalent).

2. Authenticate: Run cloud auth to open OAuth in your browser. The CLI stores tokens in ~/.config/cloud/config.json.

3. First Use Case: Link your local Git repo to a Laravel Cloud app and set defaults:

   cloud repo:config
   

   This configures the current directory as a deployable project, auto-detecting the Laravel app and environment.

Implementation Patterns

Core Workflows

1. Deployment Pipeline:

   • Deploy: Trigger a deployment for the configured app/environment:

     cloud deploy
     

   • Rollback: Revert to a previous release:

     cloud rollback <release-id>
     

   • Logs: Stream real-time logs:

     cloud logs
     

2. Resource Management:

   • Environments: List, create, or switch environments:

     cloud env:list
     cloud env:create --name=staging
     cloud env:use staging
     

   • Databases: Manage databases (create, list, connect):

     cloud db:create --name=app_db
     cloud db:list
     

   • Domains: Add/remove custom domains:

     cloud domain:add example.com
     

3. Configuration:

   • Environment Variables: Push/pull .env files:

     cloud env:pull  # Download .env from Cloud
     cloud env:push  # Upload .env to Cloud
     

   • Secrets: Manage encrypted secrets:

     cloud secret:set DB_PASSWORD --value="..."
     

4. CI/CD Integration:

   • Token Management: Generate tokens for CI (e.g., GitHub Actions):

     cloud auth:token --generate
     

   • Webhooks: Configure deployment webhooks:

     cloud webhook:create --url="https://your-ci.com/webhook"
     

5. Object Storage:

   • Upload/download files:

     cloud storage:upload file.txt storage/
     cloud storage:download storage/file.txt
     

Integration Tips

• Laravel Projects: Use cloud repo:config in your project root to auto-configure the CLI for the current repo.
• Team Workflows: Share config.json (tokens) securely via CI secrets or team tools (e.g., 1Password).
• Scripting: Use --json flag for machine-readable output (e.g., cloud deploy --json).
• Composer Scripts: Add custom scripts in composer.json to wrap CLI commands:

  "scripts": {
    "deploy": "cloud deploy",
    "logs": "cloud logs --tail=100"
  }
  

Gotchas and Tips

Pitfalls

1. Authentication:

   • Token Leaks: Avoid committing ~/.config/cloud/config.json to version control. Use .gitignore:

     ~/.config/cloud/
     

   • CI Tokens: Regenerate tokens for CI/CD pipelines (cloud auth:token --generate) and restrict permissions.

2. Repository Configuration:

   • Detached Repos: cloud repo:config fails if the repo isn’t a Git project. Ensure .git exists.
   • Multi-Repo Projects: Run cloud repo:config in the root of each Laravel app directory.

3. Environment Variables:

   • Overwrites: cloud env:push overwrites existing variables. Use --merge to append:

     cloud env:push --merge
     

   • Sensitive Data: Never hardcode secrets in .env files pushed to Cloud. Use cloud secret:set instead.

4. Deployment Issues:

   • Failed Deploys: Check logs with cloud logs --tail=50 or cloud release:show <id>.
   • Build Errors: Ensure composer.json has a scripts.deploy hook or use the --build flag:

     cloud deploy --build
     

5. API Rate Limits:

   • Laravel Cloud’s API may throttle requests. Add retries or delays in scripts:

     cloud deploy --retry 3
     

Debugging

• Verbose Output: Enable debug mode for troubleshooting:

  cloud --verbose deploy
  

• API Errors: Check the raw API response with --json:

  cloud env:list --json
  

• Network Issues: Ensure gh (GitHub CLI) is authenticated and the Laravel Cloud API is reachable.

Extension Points

1. Custom Commands: Extend the CLI by creating a Laravel Zero command in your project:

   // app/Console/Commands/CloudCustomCommand.php
   namespace App\Console\Commands;
   use Laravel\Cloud\Cloud;
   class CloudCustomCommand extends Command {
       protected $cloud;
       public function __construct(Cloud $cloud) {
           parent::__construct();
           $this->cloud = $cloud;
       }
       public function handle() {
           $this->cloud->deploy();
       }
   }
   

   Register it in app/Console/Kernel.php:

   protected $commands = [
       Commands\CloudCustomCommand::class,
   ];
   

2. Pre/Post Hooks: Use Laravel’s event system to trigger actions before/after deployments:

   // app/Providers/CloudServiceProvider.php
   use Laravel\Cloud\Events\DeploymentStarted;
   class CloudServiceProvider extends ServiceProvider {
       public function boot() {
           event(DeploymentStarted::class, function () {
               // Run pre-deploy tasks (e.g., database backups)
           });
       }
   }
   

3. Local Overrides: Override Cloud configurations locally by creating a cloud.php file in your project root:

   return [
       'default_environment' => 'local',
       'deploy_hooks' => [
           'pre_deploy' => 'php artisan migrate',
       ],
   ];
   

Configuration Quirks

• Default Environment: Set a global default in ~/.config/cloud/config.json:

  {
      "default_environment": "production",
      "default_application": "my-app"
  }
  

• GitHub Repo Linking: Ensure the GitHub repo is linked to the Laravel Cloud project in the Cloud dashboard before running cloud repo:config.
• PHP Version: The CLI requires PHP 8.2+, but your Laravel app may target an older version. Use .php-version or phpbrew to switch versions during deployments.