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."
Problem
When API calls fail, error messages are generic ("Search failed", "Failed to fetch tweet"). There's no way to see:
Users can't diagnose whether the issue is auth expiry, rate limiting, query ID rotation, or a network problem.
Proposed solution
Add a global
--verboseor--debugflag that enables detailed output:x-reader search "test" --verboseOutput would include:
Implementation
--debugas a global option in Commanderconsole.errorfor debug output (keeps stdout clean for piping)Bonus
Also improve error messages to suggest common fixes:
x-reader setupto refresh your cookies."x-reader query-ids --refreshto update query IDs."