## Getting Started

### Minimal Steps to First Use
1. **Installation**:
   ```sh
   gh repo clone laravel/cloud-cli
   cd cloud-cli
   composer install

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

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

Authenticate:
```
cloud auth
```
This opens a browser for OAuth and stores tokens in ~/.config/cloud/config.json.
Configure Repository (One-Time Setup):
```
cd /path/to/your/laravel-project
cloud repo:config
```
This links your local repo to a Laravel Cloud application and sets defaults for future commands.
First Deployment:
```
cloud deploy
```
The CLI will prompt for missing details (e.g., environment) if not already configured.

First Use Case: Deploying a New App

Use the ship command for a guided workflow to create an application and deploy it:

cloud ship

This handles:

Application creation (name, region, stack).
Environment setup (e.g., production, staging).
Database, cache, and storage provisioning.
Initial deployment with zero configuration prompts.

Implementation Patterns

Workflows

1. Deployment Workflow

Local Development → Cloud:

# Configure repo defaults (run once)
cloud repo:config

# Deploy to Cloud (uses repo defaults)
cloud deploy

# Monitor deployment progress
cloud deploy:monitor

Rollback:

cloud deployment:list  # Find the previous deployment ID
cloud deployment:get <deployment-id>  # Verify details
cloud deploy --rollback  # Rollback to the selected deployment

2. Environment Management

Create and Update Environments:

# Create a new environment
cloud environment:create --name staging --application my-app

# Update environment variables (append, set, or replace)
cloud environment:variables --set DB_DATABASE=staging_db --application my-app --environment staging

# View logs for debugging
cloud environment:logs --application my-app --environment staging

3. Infrastructure as Code (IaC) Pattern

Use the CLI in scripts or CI/CD pipelines:

# Example: Deploy in CI (GitHub Actions)
- name: Deploy to Laravel Cloud
  run: |
    cloud deploy --application ${{ secrets.CLOUD_APP_ID }} --environment production

Machine-Readable Output:
```
cloud environment:variables --json --application my-app --environment staging
```
Outputs masked environment variables in JSON for parsing in scripts.

4. Resource Provisioning

Databases:

# Create a database cluster
cloud database-cluster:create --name my-cluster --region us-east-1

# Create a database (schema) in the cluster
cloud database:create --name my_db --cluster my-cluster

# Open database locally (e.g., for migrations)
cloud database:open --name my_db --cluster my-cluster

Object Storage:

# Create a bucket and key for S3-like storage
cloud bucket:create --name my-bucket
cloud bucket-key:create --bucket my-bucket --name my-key

5. Background Processes and Commands

Scheduled Jobs:

# Run an Artisan command on the environment
cloud command:run --application my-app --environment staging --command "queue:work --once"

Background Processes:

# Create a background process (e.g., for queues)
cloud background-process:create --application my-app --environment staging --command "php artisan queue:work --daemon"

Integration Tips

1. GitHub Actions Integration

Use the CLI in CI/CD pipelines for automated deployments:

- name: Deploy
  run: |
    cloud deploy --application ${{ secrets.CLOUD_APP_ID }} --environment ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }}

Token Management: Store API tokens in GitHub Secrets (CLOUD_API_TOKEN) and use:
```
cloud auth:token --set ${{ secrets.CLOUD_API_TOKEN }}
```

2. Local Development with Cloud Resources

Database Snapshots:

# Create a snapshot before migrations
cloud database-snapshot:create --database my_db --cluster my-cluster --name pre-migration-snapshot

# Restore from snapshot
cloud database-restore:create --snapshot pre-migration-snapshot --database my_db

Local Tunnels: Use cloud browser or cloud dashboard to test features in a real environment without deploying locally.

3. Shell Completions

Enable tab completions for faster workflows:

cloud completions > ~/.cloud-completions.sh
echo 'source ~/.cloud-completions.sh' >> ~/.zshrc
source ~/.zshrc

Now you can autocomplete commands like cloud environment:var → cloud environment:variables.

4. Billing and Usage Monitoring

Track costs in real-time:

# View current period usage
cloud usage

# Detailed breakdown (e.g., per-environment)
cloud usage --detailed --environment staging

Integrate into financial reviews or cost optimization scripts.

Gotchas and Tips

Pitfalls

1. Authentication Issues

Symptom: Commands fail with 401 Unauthorized.
Fix:
- Ensure cloud auth was run successfully (check ~/.config/cloud/config.json).
- For CI, use cloud auth:token --set $API_TOKEN with a valid token.
- Verify GitHub CLI (gh) is authenticated if linking repos.

2. Repository Configuration Mismatches

Symptom: cloud deploy ignores repo defaults or prompts unexpectedly.
Fix:
- Run cloud repo:config from the root of your Git repository.
- Verify the linked application/environment with:
```
git config --local --get cloud.application
git config --local --get cloud.environment
```
- Re-run cloud repo:config if values are incorrect.

3. Environment Variable Masking

Symptom: Sensitive values leak in --json output.
Fix: The CLI masks values in JSON output by default (added in v0.2.6). If you need raw values, use:
```
cloud environment:variables --application my-app --environment staging --no-mask
```
(Note: This is not recommended for production.)

4. Region-Specific Resources

Symptom: Commands fail when resources (e.g., databases) are in a different region.
Fix: Always specify the --region flag when creating resources:
```
cloud database-cluster:create --name my-cluster --region us-east-1
```
Check available regions with:
```
cloud ip:addresses
```

5. WebSocket Cluster Limitations

Symptom: cloud websocket-cluster:create fails or hangs.
Fix: Ensure your application is configured to use WebSockets in Laravel Cloud (check the dashboard). WebSocket clusters require a dedicated cluster (not shared instances).

6. Background Process Timeouts

Symptom: Long-running background processes (e.g., queue:work) fail silently.
Fix: Use the --timeout flag or ensure your process is optimized for Laravel Cloud’s execution environment:
```
cloud background-process:create --command "php artisan queue:work --timeout=300"
```

Debugging Tips

1. Verbose Output

Enable debug mode for troubleshooting:

cloud deploy --verbose

Or set the VERBOSE environment variable:

export VERBOSE=true
cloud deploy

2. API Rate Limiting

Symptom: Commands fail with 429 Too Many Requests.
Fix: Add a delay between API calls in scripts:
```
sleep 2
cloud environment:variables --application my-app
```
Or use the --throttle flag (if supported in future versions).

3. Git Repository Linking

Symptom: cloud repo:config fails to link the repo.
Fix: Ensure:
- The repo is a GitHub repository (GitHub CLI is required).
- You have **admin access

Cloud Cli Laravel Package