Skip to content

Add --verbose / --debug flag for troubleshooting #6

@sujito00

Description

@sujito00

Problem

When API calls fail, error messages are generic ("Search failed", "Failed to fetch tweet"). There's no way to see:

  • Which GraphQL operation was attempted
  • Which query ID was used
  • The HTTP status code returned
  • The raw error response from X

Users can't diagnose whether the issue is auth expiry, rate limiting, query ID rotation, or a network problem.

Proposed solution

Add a global --verbose or --debug flag that enables detailed output:

x-reader search "test" --verbose

Output would include:

[debug] Using query ID: abc123 for SearchTimeline
[debug] POST https://x.com/i/api/graphql/abc123/SearchTimeline
[debug] Response: 200 OK (342ms)
[debug] Found 10 tweets, cursor: xyz...

Implementation

  • Add --debug as a global option in Commander
  • Pass it through to the client constructor
  • Use console.error for debug output (keeps stdout clean for piping)

Bonus

Also improve error messages to suggest common fixes:

  • 401/403 -> "Authentication failed. Run x-reader setup to refresh your cookies."
  • 404 -> "Endpoint not found. Try x-reader query-ids --refresh to update query IDs."
  • 429 -> "Rate limited. Wait a few minutes and try again."

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions