Metadata-Version: 2.4
Name: socialscrape-cli
Version: 0.1.1
Summary: SocialScrape on the command line: social media data as JSON or a table
License-Expression: MIT
Project-URL: Homepage, https://socialscrape.dev/?utm_source=pypi&utm_medium=package&utm_campaign=socialscrape-cli
Project-URL: Documentation, https://socialscrape.dev/docs?utm_source=pypi&utm_medium=package&utm_campaign=socialscrape-cli
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1,>=0.27
Dynamic: license-file

# 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

| | |
|---|---|
| `socialscrape <platform> <resource> [value] [--param value]` | Any endpoint. `socialscrape github --help` lists a platform's resources, `socialscrape github user --help` the parameters. Resource names use hyphens: `profile.posts` is `profile-posts` (dots and underscores also work). |
| `transcript URL` | Transcript of a video or post on any supported platform. |
| `profile`, `post`, `comments`, `search PLATFORM VALUE` | The same job on any platform that has it (`search` takes `--kind`). Shortcuts for `<platform> <resource>`. |
| `credits`, `usage [daily\|routes]`, `job ID` | Balance, request history, an async job. All free. |
| `batch FILE\|-` | Up to 100 requests in one call from JSON: `[{"endpoint": "github.user", "params": {"handle": "torvalds"}}]`. |
| `monitors list\|create\|delete\|test\|deliveries\|events\|redeliver` | Webhook monitors. |
| `endpoints [PLATFORM]` | What can be called. |
| `login`, `logout`, `config` | Save, remove, show (masked) the key. |

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`).
