There There Cli Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer global require spatie/there-there-cli
   

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

2. First Use Case:

   • Authenticate with your There There workspace:

     there-there login
     

   • Confirm the API token is added to your ~/.config/there-there-cli/profiles.json (or the specified profile file).

3. Quick Command: List tickets to verify connectivity:

   there-there tickets:list
   

Where to Look First

• Documentation: there-there.com (official docs).
• CLI Help: Run there-there --help or there-there <command>:help (e.g., there-there tickets:list --help).
• Profile Management: Check ~/.config/there-there-cli/ for stored credentials and profiles.

Implementation Patterns

Workflows

1. Multi-Workspace Management:

   • Use profiles to switch between workspaces seamlessly:

     there-there login --profile=client1
     there-there tickets:list --profile=client2
     

   • Automate profile switching in scripts (e.g., CI/CD pipelines).

2. Ticket Automation:

   • List/Triage Tickets:

     there-there tickets:list --status=unresolved --limit=10
     

   • Create/Update Tickets:

     there-there tickets:create --title="Server Down" --description="..." --priority=high
     there-there tickets:update 123 --status=resolved
     

   • Bulk Actions:

     there-there tickets:update-many --status=in_progress --ids="1,2,3"
     

3. Integration with Laravel:

   • Artisan Commands: Wrap CLI calls in custom Artisan commands for internal tools:

     // app/Console/Commands/ProcessTickets.php
     public function handle() {
         $output = $this->call('there-there', ['tickets:list', '--status=unresolved']);
         // Parse output and trigger Laravel logic (e.g., notifications).
     }
     

   • Event Listeners: Use the CLI to fetch tickets and dispatch Laravel events:

     // app/Listeners/CheckTickets.php
     public function handle() {
         $tickets = shell_exec('there-there tickets:list --json');
         $tickets = json_decode($tickets, true);
         foreach ($tickets as $ticket) {
             if ($ticket['priority'] === 'critical') {
                 event(new CriticalTicketAlert($ticket));
             }
         }
     }
     

4. Scheduled Tasks:

   • Use Laravel’s schedule to run CLI commands periodically (e.g., daily ticket summaries):

     // app/Console/Kernel.php
     protected function schedule(Schedule $schedule) {
         $schedule->command('there-there tickets:list --status=unresolved --json')
                  ->dailyAt('9:00')
                  ->appendOutputTo(storage_path('logs/there-there-tickets.log'));
     }
     

Integration Tips

• JSON Output: Use --json flag for programmatic parsing:

  there-there tickets:list --status=pending --json | jq '.[] | select(.priority == "high")'
  

• Environment Variables: Store API tokens in .env and pass them via --token:

  there-there tickets:create --token=$THERE_THERE_TOKEN --title="..."
  

• Error Handling: Validate CLI output in Laravel:

  $exitCode = shell_exec('there-there tickets:create --title="Test" 2>&1', $output);
  if ($exitCode !== 0) {
      throw new \RuntimeException(implode("\n", $output));
  }
  

Gotchas and Tips

Pitfalls

1. Profile File Permissions:

   • Ensure ~/.config/there-there-cli/profiles.json is writable by your user.
   • Fix: Run chmod 600 ~/.config/there-there-cli/profiles.json if permission errors occur.

2. Token Expiry:

   • There There may invalidate tokens silently. Test commands fail with:

     Error: Authentication failed. Please log in again.
     

   • Fix: Re-run there-there login or specify a valid --token.

3. Rate Limiting:

   • Aggressive polling (e.g., every minute) may trigger API rate limits.
   • Fix: Add delays in scheduled tasks or use --limit to fetch smaller batches.

4. Output Parsing:

   • CLI output format may change between versions. Avoid relying on undocumented formatting.
   • Fix: Always use --json for stable parsing.

5. Global Composer Dependencies:

   • composer global require may not update symlinks correctly.
   • Fix: Use composer global update spatie/there-there-cli or reinstall.

Debugging

• Verbose Mode: Enable debug output with -v:

  there-there tickets:list -v
  

• Dry Runs: Test commands with --dry-run (if supported) or redirect output to a file:

  there-there tickets:create --title="Test" --dry-run > debug.log
  

• API Logs: Check There There’s API logs (if you have admin access) for failed requests.

Config Quirks

1. Profile File Location:

   • Default: ~/.config/there-there-cli/profiles.json.
   • Override with --profile-file=/custom/path/profiles.json.

2. Token Storage:

   • Tokens are stored in plaintext in profiles.json. Avoid sharing this file.
   • Alternative: Use Laravel’s env() or a secrets manager for tokens in scripts.

3. Command Aliases:

   • The CLI supports shorthand (e.g., there-there t:list for tickets:list), but these may not be documented.
   • Tip: Run there-there without arguments to see all available shorthands.

Extension Points

1. Custom Commands:

   • Extend the CLI by creating wrapper scripts (e.g., bin/there-there-wrapper) that chain commands:

     #!/bin/bash
     there-there tickets:list --status=$1 | your-custom-parser.sh
     

   • Laravel Example: Create a facade to abstract CLI calls:

     // app/Facades/ThereThere.php
     public static function listTickets($status = null) {
         return json_decode(
             shell_exec('there-there tickets:list --status=' . $status . ' --json'),
             true
         );
     }
     

2. Webhook Integration:

   • Use the CLI to verify webhook payloads by replaying API calls:

     there-there tickets:create --title="Webhook Test" --description="..." --json
     

   • Compare output with incoming webhook data.

3. Testing:

   • Mock CLI calls in Laravel tests using expectsJob() or expectsOutput():

     $this->artisan('there-there tickets:list --status=unresolved')
          ->expectsOutput('Ticket ID: 123')
          ->assertExitCode(0);