socialscrape-cli

socialscrape: social media data on the command line, as JSON for scripts and agents or a table for people. Python 3.10+, one dependency (httpx).

pip install socialscrape-cli        # or: pipx install socialscrape-cli
socialscrape login                  # paste your key once (saved to ~/.config/socialscrape/config.json, mode 600)

socialscrape github user torvalds
socialscrape transcript "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
socialscrape search threads "open source" -o table
socialscrape threads profile-posts zuck --pages 3
socialscrape ad-libraries facebook-search nike --region US --all --max-credits 5
socialscrape credits

The CLI reads the same endpoint catalog as the socialscrape-mcp server, so a platform appears here in the release after its endpoints are built. It uses plain httpx and needs no other SocialScrape package.

Commands

The positional value is the resource's main parameter; the form is detected (a URL goes to url, anything else to handle, id or query). Every parameter is also a flag (--handle, --url, --sort, --limit, --region, ...), with the API's aliases (--username).

Output

• stdout is data only: pretty JSON on a terminal, compact JSON in a pipe. -o table and -o ndjson (one item per line) change the format; --envelope prints the whole response (data, credits_charged, cursor, ...); --raw asks for the platform's original object (raw=true) and prints the whole response.
• stderr carries the price: credits charged: 1 | remaining: 4999. -q silences it.
• --dry-run prints the request and what it would cost and sends nothing (no key needed).

Paging

--pages N follows the cursor up to N pages; --all follows it to the end (cap --max-pages, default 50). Each page costs credits, so bound it: --max-items N, --max-credits N. The merged result is one list with every item; if a later page fails you still get the earlier ones.

Exit codes

0 ok, 1 API error (not found, private, invalid parameters, ...), 2 usage error (nothing was sent, nothing charged), 3 key or credits (unauthorized, forbidden, insufficient_credits), 4 retryable (rate limited, upstream blocked or timed out, network). Failures are free.

Key and server

The key comes from --key, then $SOCIALSCRAPE_API_KEY, then the saved config. login checks the key against the API before it saves anything. --api-url or $SOCIALSCRAPE_API_URL points at another server (default https://api.socialscrape.dev).