Flare Cli Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer global require spatie/flare-cli
   

   Ensure the global bin directory is in your PATH (verify with composer global config bin-dir --absolute).

2. Authenticate:

   flare login
   

   Paste your Flare API token (obtained from flareapp.io/settings/api-tokens).

3. First Use Case: List recent errors in your project:

   flare errors
   

   Or fetch a specific error by ID:

   flare error:show 123
   

Where to Look First

• README: Focus on the Usage section for core commands.
• Flare Dashboard: Cross-reference CLI output with the web UI to correlate errors/performance data.
• Flare API Docs: For advanced queries, refer to Flare’s API documentation.

Implementation Patterns

Core Workflows

1. Error Triage:

   # List recent errors (last 24h)
   flare errors --days=1
   
   # Filter by project
   flare errors --project=my-project-name
   
   # Show full error details
   flare error:show <ID> --with-trace
   

2. Performance Monitoring:

   # List slowest requests
   flare requests --slowest
   
   # Compare request durations
   flare requests --compare=1h
   

3. Automated Reporting:

   # Export errors to JSON (for CI/CD pipelines)
   flare errors --export=errors.json
   
   # Slack notification for critical errors
   flare errors --critical | xargs -I{} curl -X POST -d "text=New error: {}" <SLACK_WEBHOOK>
   

Integration Tips

• Laravel Artisan Hooks: Add Flare CLI to your post-deploy script in deploy.php (Deployer) or after-deploy in Laravel Forge:

  flare errors --critical --days=1 | mail -s "Critical Errors" devs@example.com
  

• CI/CD Pipelines: Use in GitHub Actions to block deployments on critical errors:

  - name: Check Flare Errors
    run: |
      ERRORS=$(flare errors --critical --days=1 --count)
      if [ "$ERRORS" -gt 0 ]; then
        echo "Critical errors found: $ERRORS"
        exit 1
      fi
  

• Local Development: Alias frequent commands in your ~/.bashrc or ~/.zshrc:

  alias flare-latest="flare errors --days=1 --limit=5"
  alias flare-slow="flare requests --slowest --limit=3"
  

Gotchas and Tips

Pitfalls

1. Token Management:

   • Gotcha: Forgetting to log out (flare logout) on shared machines can expose your API token.
   • Fix: Use flare logout explicitly or set a short token expiry in Flare’s settings.

2. Rate Limiting:

   • Gotcha: Aggressive polling (e.g., flare errors --poll) may hit Flare’s API limits.
   • Fix: Add delays between requests or use --limit to cap results:

     flare errors --days=7 --limit=100
     

3. Project Context:

   • Gotcha: Running flare errors without specifying a project may return data from all projects.
   • Fix: Always use --project or set a default in your ~/.flare-cli/config.json:

     {
       "default_project": "my-project-name"
     }
     

4. Trace Depth:

   • Gotcha: Long error traces may truncate in CLI output.
   • Fix: Use --with-trace and pipe to a pager:

     flare error:show 123 --with-trace | less
     

Debugging

• Silent Failures: If commands hang or return no data, verify:

  • Token validity (flare whoami).
  • Project existence (flare projects).
  • API connectivity (test with flare ping).

• JSON Output: For debugging, use --json to inspect raw API responses:

  flare errors --json | jq '.data[0].trace'
  

Extension Points

1. Custom Commands: Extend functionality by wrapping Flare CLI in a custom script. Example (flare-custom.sh):

   #!/bin/bash
   ERRORS=$(flare errors --critical --days=1 --count)
   if [ "$ERRORS" -gt 0 ]; then
     flare errors --critical --export=critical_errors.json
     echo "Exported $ERRORS critical errors to critical_errors.json"
   fi
   

2. Webhook Integration: Use Flare’s webhook API alongside CLI to trigger actions:

   # Fetch webhook payloads
   flare webhooks --limit=5
   

3. Configuration: Override defaults via ~/.flare-cli/config.json:

   {
     "days": 7,
     "limit": 50,
     "with_trace": true
   }
   

   Now flare errors will use these defaults.

Pro Tips

• Alias for Critical Paths:

  alias flare-critical="flare errors --critical --days=1 --with-trace"
  

• Combine with fzf: Fuzzy-search errors interactively:

  flare errors --json | jq -r '.data[] | "\(.id): \(.message)"' | fzf | awk '{print $1}' | xargs flare error:show
  

• Monitor Deployments: Tag errors by deployment hash:

  flare errors --tag=deploy:abc123