Skip to main content
Use the CLI when you need X API data without an application wrapper. It fits a shell script, cron job, CI workflow, or operations runbook. It can search tweets and export follower data. It can scrape tweets to JSON Lines, CSV, or XLSX. It can upload media, post media tweets, and post tweet replies. It can also send direct messages and monitor tweets. Hand results to jq, Python, a warehouse loader, or a queue worker.

Install

Or run it once without installing.
npm installs the build for your platform. With Go, install from source.
Confirm your Go bin directory is on PATH.

Authenticate

You can also pass --api-key per command. For OAuth 2.1 access tokens, use X_TWITTER_SCRAPER_BEARER_TOKEN.

Basic example

Use --help at any level.

Tweet search workflow to JSON Lines, CSV, or XLSX

Use this workflow to get tweets from an X (Twitter) search query. It suits an analyst, data engineer, or growth operator. Deliver the tweets as a JSON Lines handoff, analyst CSV file, or XLSX workbook. They can also go to a warehouse load, CRM enrichment job, or queue. The CLI command below calls GET /x/tweets/search. It maps the same REST API query parameters to CLI flags. The flags are --q, --limit, --cursor, --since-time, --until-time, and --query-type.
The response includes .tweets[], .has_next_page, and .next_cursor. Each tweet can include id, text, createdAt, engagement counts, bookmarkCount, and isNoteTweet. It can also include author, media, quoted_tweet, and retweeted_tweet. Each field appears only when the result has it. Project .tweets[] into xquik-tweet-search.jsonl and xquik-tweet-search.csv rows. Give each row tweet_id, author_username, engagement counts, page_index, page_cursor, next_cursor, and has_next_page. Scripts can then resume. They can also load the same records into XLSX, CRM, warehouse, or agent workflows.
Save the cursor with the job checkpoint before requesting the next page.
Use --limit as a 1 to 200 upper bound for a bounded pull. When .has_next_page is true, keep the same --q, filters, --query-type, and --limit. Only --cursor changes. Tweet search costs 1 credit per tweet returned. If credits cannot cover a bounded --limit request, the API can return fewer tweets. If credits cover no results, it returns 402 insufficient_credits. If a bounded pull returns fewer tweets than --limit, pass .next_cursor back as --cursor. Send the same query, filters, --query-type, and --limit with it. Use --format-error json so batch jobs can branch on status and code. Retry 429 or temporary 5xx responses with backoff. For XLSX handoff, keep xquik-tweet-search.jsonl as the master file. When account managers need a workbook, convert the same projected rows in your pipeline.

Follower export workflow to CSV, JSON, or XLSX

Use this workflow when a team needs an owned follower list. It fits sales, support, research, or marketing teams. Deliver the list as a CRM import, warehouse load, or analyst CSV file. You can also deliver it as an XLSX workbook or resumable JSON handoff. follower_explorer requires targetUsername. The CLI flag is --target-username.
The estimate calls POST /extractions/estimate and returns allowed, estimatedResults, creditsRequired, creditsAvailable, and source. For follower exports, source is usually followers.
The run command calls POST /extractions and returns the queued 202 Accepted receipt. The receipt holds id, toolType, and status: "running". Store follower-run.json, job_id, the source username, and the estimate before polling. Credit reservation happens after the job starts. If available credits changed since the estimate, the run has 2 outcomes. It can fetch only the affordable count before export. Or it can mark the job failed with insufficient_credits.
The retrieve command returns .job, .results, .hasMore, and .nextCursor. When .hasMore is true, pass .nextCursor back as --cursor. That fetches the next saved page.
Use --format json --output xquik-followers.json for app ingestion or --format xlsx --output xquik-followers.xlsx for XLSX handoff. Map User ID or result xUserId as the CRM unique key. Keep xquik-followers.jsonl for queue replay or warehouse loads, and xquik-followers.json for app ingestion. Keep xquik-followers.csv for CRM import and xquik-followers.xlsx for analyst handoff. The cost is 1 credit per follower extracted or returned. Exports cost no credits after the extraction job exists.

Tweet replies workflow to CSV, JSON, or XLSX

Use this workflow when you need every reply under one Tweet. Export CSV, JSON, or XLSX. Write a local JSON Lines file from paginated JSON rows. reply_extractor requires targetTweetId. The CLI flag is --target-tweet-id.
The estimate calls POST /extractions/estimate and returns allowed, estimatedResults, creditsRequired, creditsAvailable, and source. For replies, source is usually replyCount.
The run command calls POST /extractions. Store job_id before polling. With it, a shell restart, queue retry, or CI rerun can resume that extraction. Reuse the follower export polling loop above with reply filenames.
The retrieve command calls GET /extractions/{id} and returns .job, .results, .hasMore, and .nextCursor. Append .results[] to your queue, CRM import, or warehouse load. While .hasMore is true, pass .nextCursor back as --cursor "$next_cursor".
The export command calls GET /extractions/{id}/export and writes bytes to --output. Use --format csv, --format json with --output xquik-tweet-replies.json, or --format xlsx with --output xquik-tweet-replies.xlsx. The cost is 1 credit per reply extracted or returned. Exports cost no credits after the extraction job exists.

Workflow to post media tweets, replies, and DM attachments

Use this workflow when an operator, support queue, or agent sends media. It can publish a media-backed tweet or reply with media. It can also send one media attachment in a DM. The workflow runs from a connected X account. Tweet and reply media posts use public media URLs directly on x:tweets create. Pass repeated --media flags for up to 4 image URLs. Or pass exactly 1 MP4 video URL up to 100 MB. Do not mix video with other media. Do not upload first when you already have public media URLs.
To reply with media, add the parent tweet ID. The --reply-to-tweet-id flag maps to reply_to_tweet_id. --media maps to the public URL array on POST /x/tweets.
Send a unique Idempotency-Key. Store the durable action’s id, request.hash, billing, result, and statusUrl. Poll while terminal is false. Retry only when safeToRetry is true, using a new key. Keep one JSON Lines handoff shape for every lifecycle state.
Each create-tweet call costs 30 credits. Use x:media upload when you need an uploaded media ID for a DM attachment. The CLI upload command accepts a local file through --file. --transform mediaId extracts the upload response ID for scripts.
The --media-id flag maps to the REST media_ids body field. DMs accept exactly 1 uploaded media ID. Store messageId from the DM response. Put it on the support ticket, CRM record, queue job, or agent memory. Keep DM body text in private systems. Shared logs, public artifacts, queue status, and agent handoffs should omit full DM bodies. They should store message_id, optional media_id, and send status. They should also store recipient and account identifiers from your job context. Uploading media costs 10 credits. Sending the DM costs 10 credits. Do not pass --reply-to-message-id to x:dm send. The REST endpoint rejects reply_to_message_id. Start a new DM with --user-id, --account, --text, and optional one-item --media-id instead. Do not pass uploaded mediaId values to x:tweets create. That command uses --media with public media URLs.

Useful commands

Search tweets or scrape tweets

Run x-twitter-scraper x:tweets search to return tweet objects, author objects, metrics, media, has_next_page, and next_cursor.

Fetch one tweet

Run x-twitter-scraper x:tweets retrieve to return the full tweet text, author, and metrics. It also returns media, the quoted tweet, and the retweeted tweet.

Get tweet replies

Run x-twitter-scraper x:tweets get-replies to return reply tweets plus cursor fields.

Export followers

Run x-twitter-scraper x:users retrieve-followers to return user profiles, follower counts, and cursor fields.

Post a tweet or reply

Run x-twitter-scraper x:tweets create to return tweetId, success, charged, and chargedCredits. When confirmation is pending, it returns writeActionId instead.

Upload media for a DM attachment

Run x-twitter-scraper x:media upload to return mediaId for one-item DM media_ids. It also returns mediaUrl for tweet media URL handoff.

Send a direct message

Run x-twitter-scraper x:dm send to return messageId and success.
Use --format json for scripts and --format yaml for readable operations output. When you only need one field from the response, use --transform with GJSON syntax.

Error handling

The CLI writes API errors to stderr and exits non-zero for failed requests. Use --format-error json when scripts need machine-readable errors.
Retryable API responses follow the same semantics as the REST API. See error handling and rate limits.

Pagination

Commands that call paginated endpoints include pagination fields in their JSON output. Keep the response body when your script needs the next page. The script requests that page with endpoint cursor parameters.

Webhooks & references