There There Cli Laravel Package

Getting Started

Minimal Setup

1. Install the CLI globally:

   composer global require spatie/there-there-cli
   

   Ensure the global bin directory is in your PATH:

   composer global config bin-dir --absolute
   

2. Authenticate:

   there-there login
   

   • Follow the prompt to generate an API token from There There’s API token page.
   • Paste the token when prompted.

3. First Use Case: List all open tickets:

   there-there list-tickets --filter-status=open
   

   Output is JSON-formatted, ready for parsing in Laravel scripts.

Key Starting Points

• Profile Management: Use --profile=NAME to manage multiple workspaces.
• Ticket Actions: Start with show-ticket and reply-to-ticket for basic workflows.
• Agent Skill: Install for AI-assisted workflows:

  there-there install-skill
  

Implementation Patterns

1. Laravel Integration Workflows

Automated Ticket Processing

Use Laravel’s Artisan::call() to trigger CLI commands from within your app:

// app/Console/Commands/ProcessTickets.php
public function handle() {
    $exitCode = Artisan::call('there-there list-tickets --filter-status=open --json');
    $tickets = json_decode(Artisan::output(), true);

    foreach ($tickets['data'] as $ticket) {
        // Process tickets (e.g., update Laravel DB, trigger notifications)
    }
}

Pro Tip: Pipe JSON output to Laravel’s json_decode() for structured data.

Event-Driven Workflows

Pair with Laravel Events to react to ticket changes:

// app/Listeners/UpdateTicketStatus.php
public function handle(ThereThereTicketUpdated $event) {
    $ticketUlid = $event->ticketUlid;
    Artisan::call("there-there update-ticket-status --ticket={$ticketUlid} --field status=closed");
}

2. Multi-Workspace Management

Switch Profiles Dynamically:

# In Laravel, use environment variables to switch profiles
$profile = env('THERE_THERE_PROFILE', 'default');
Artisan::call("there-there list-tickets --profile={$profile}");

Profile-Based Scripts:

# Example: Run a script against a specific workspace
./scripts/process-tickets.sh --profile=acme-eu

3. Data Export/Import

Export Tickets to JSON:

there-there list-tickets --filter-created-after=2024-01-01 --json > tickets.json

Import into Laravel:

$tickets = json_decode(file_get_contents('tickets.json'), true);
Ticket::insert($tickets['data']);

4. Attachment Processing

Download Ticket Attachments:

$ticket = json_decode(Artisan::call("there-there show-ticket --ticket={$ulid} --json"));
foreach ($ticket->inline_images as $image) {
    $response = Http::withHeaders([
        'Authorization' => 'Bearer ' . config('there-there.token'),
    ])->get($image->download_url);

    Storage::put("attachments/{$image->id}.{$image->mime_type}", $response->body());
}

5. AI-Assisted Workflows

Use the agent skill to generate Laravel code:

# Ask the agent to create a script for "list unassigned tickets"
there-there install-skill
# Then use your AI tool to prompt:
# "Generate a Laravel script to list all unassigned There There tickets from the last 7 days."

Gotchas and Tips

Authentication Pitfalls

1. Token Expiry:

   • If you see 401 Unauthorized, re-authenticate:

     there-there logout --all
     there-there login
     

   • Tip: Store tokens in Laravel’s .env and use config('there-there.token') to avoid CLI prompts.

2. Workspace Mismatch:

   • Ensure the X-Workspace-Id header is set. The CLI auto-handles this, but verify with:

     there-there get-me
     

Command Quirks

1. Pagination Handling:

   • Use --page and --per-page for large datasets, but process in batches to avoid memory issues:

     for ($page = 1; $page <= 10; $page++) {
         $tickets = json_decode(Artisan::call("there-there list-tickets --page={$page} --per-page=50 --json"));
         // Process $tickets['data']
     }
     

2. Field Updates:

   • Use --field for updates (e.g., --field status=closed). Always validate the field name against the There There API docs.
   • Gotcha: Some fields (e.g., assignee_ulid) require ULIDs, not names. Use there-there list-members to fetch ULIDs.

3. JSON Output:

   • Always use --json for machine-readable output. Human-readable output may break parsing:

     there-there list-tickets --json > tickets.json
     

Performance Tips

1. Rate Limiting:

   • There There’s API has rate limits (~60 requests/minute). Throttle Laravel jobs:

     use Illuminate\Bus\Queueable;
     use Illuminate\Queue\InteractsWithQueue;
     use Illuminate\Queue\SerializesModels;
     use Illuminate\Support\Facades\Bus;
     
     Bus::dispatch(new ProcessTickets)->delay(now()->addMinute());
     

2. Caching:

   • Cache frequent queries (e.g., ticket lists) in Laravel’s cache:

     $tickets = Cache::remember("there_there_tickets_{$profile}", now()->addHours(1), function () {
         return json_decode(Artisan::call("there-there list-tickets --profile={$profile} --json"), true);
     });
     

Debugging

1. Verbose Output:

   • Enable debug mode for API responses:

     there-there list-tickets --verbose
     

2. Error Handling:

   • Wrap CLI calls in Laravel’s try-catch:

     try {
         $exitCode = Artisan::call('there-there show-ticket --ticket=' . $ulid);
         if ($exitCode !== 0) {
             throw new \RuntimeException("Failed to fetch ticket");
         }
     } catch (\Exception $e) {
         Log::error("There There CLI error: " . $e->getMessage());
     }
     

3. Network Issues:

   • If requests hang, check TLS settings. The CLI enables TLS by default (except for localhost).
   • Fix: Ensure your Laravel server has valid certificates or use --insecure (not recommended for production).

Extension Points

1. Custom Commands:

   • Extend the CLI by creating Laravel Artisan commands that wrap there-there calls:

     // app/Console/Commands/CloseOldTickets.php
     public function handle() {
         $tickets = json_decode(Artisan::call("there-there list-tickets --filter-status=open --filter-created-before=2024-01-01 --json"));
         foreach ($tickets['data'] as $ticket) {
             Artisan::call("there-there update-ticket-status --ticket={$ticket['ulid']} --field status=closed");
         }
     }
     

2. Webhook Integration:

   • Use Laravel’s queue:work to poll for changes and trigger webhooks:

     // app/Console/Commands/PollTickets.php
     public function handle() {
         $newTickets = $this->fetchNewTickets();
         foreach ($newTickets as $ticket) {
             event(new ThereThereTicketCreated($ticket));
         }
     }
     

3. Testing:

   • Mock the CLI in Laravel tests using Artisan::shouldReceive():

     Artisan::shouldReceive('call')
         ->with('there-there list-tickets --json')
         ->andReturn(0)
         ->once();
     

Security

1. Token Storage:

   • Avoid hardcoding tokens. Use Laravel’s .env:

     THERE_THERE_TOKEN=your_token_here
     

   • Restrict file permissions for ~/.there-there/config.json to 0600.

2. Profile Isolation:

   • Use separate profiles for production vs. staging to avoid accidental data leaks.

3. Logging:

   • Log sensitive actions (e.g., ticket updates) but redact tokens:

     Log::info("Updated ticket {$ticketUlid}", ['action' => 'status_update', 'status' => $new