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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions