Skip to content

Conversation

@namespacebrian
Copy link
Contributor

Summary

Adds a new global --curl-debug CLI option that enables verbose cURL output to help troubleshoot TLS and connection issues.

Problem

Customers sometimes receive "Connection refused" errors from Terminus when TLS is not working correctly. Common causes include:

  • Misconfigured system CA certificates
  • Incorrect system clocks causing TLS validation failures
  • Network connectivity problems

Currently, customers get minimal error information and often submit bug reports or contact support about perceived service outages when the issue is actually on their local system.

Solution

This PR adds a --curl-debug option that enables Guzzle's debug mode, which leverages cURL's CURLOPT_VERBOSE option to provide detailed HTTP transaction information including:

  • Connection establishment details
  • TLS handshake information
  • HTTP headers and progress
  • Transfer details

Usage

# Enable debug output for any command
terminus auth:whoami --curl-debug
terminus site:list --curl-debug

# Test with intentionally broken TLS setup
TERMINUS_HOST=invalid-cert.example.com terminus self:info --curl-debug

Example Output

When enabled, users see detailed connection information:

<GET https://terminus.pantheon.io/api/users/...> [CONNECT] 
<GET https://terminus.pantheon.io/api/users/...> [MIME_TYPE_IS] message: "application/json" 
<GET https://terminus.pantheon.io/api/users/...> [PROGRESS] bytes_transferred: "1164"

Test Plan

  • Verify --curl-debug option appears in help output
  • Test with working API calls to confirm debug output
  • Test with invalid TLS scenarios to verify error diagnosis capability
  • Confirm option works globally across all commands
  • Verify no impact on normal operation when flag not used

Implementation Details

  • Added global CLI option in src/Terminus.php
  • Modified HTTP client configuration in src/Request/Request.php to check for the option
  • Uses Guzzle's built-in debug => true parameter which activates cURL verbose mode
  • No breaking changes - purely additive functionality

This commit adds a new global --curl-debug CLI option that enables
verbose cURL output to help troubleshoot TLS and connection issues.

When --curl-debug is specified, detailed HTTP transaction information
is displayed including:
- Connection establishment details
- TLS handshake information
- HTTP headers and progress
- Transfer details

This is particularly useful for diagnosing customer issues related to:
- Misconfigured CA certificates
- Incorrect system clocks causing TLS validation failures
- Network connectivity problems
- Certificate verification errors

The implementation leverages Guzzle's built-in debug functionality
which uses cURL's CURLOPT_VERBOSE option under the hood.
@namespacebrian namespacebrian requested a review from a team as a code owner November 6, 2025 15:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants