Metadata-Version: 2.5
Name: scrapebadger-cli
Version: 0.24.1
Summary: ScrapeBadger CLI — Twitter, Vinted, Google, and Web Scraping from the command line
Author: ScrapeBadger Team
License: MIT
Keywords: ai-tools,cli,mcp,scrapebadger,twitter,vinted,web-scraping
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.26.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: websockets>=12.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.2.0; extra == 'dev'
Description-Content-Type: text/markdown

# ScrapeBadger CLI

Google Light Search uses the dedicated `/v1/google/light/search` endpoint:

```bash
scrapebadger google light-search "vinted api" --gl us --hl en
```

Light returns organic results and related searches for 10 credits per successful
uncached request. Regular `scrapebadger google search` costs 20 credits and
returns the full SERP. Cache hits and failed requests are free.

Command-line access to ScrapeBadger APIs, including Etsy, AliExpress, Target, ASOS, Best Buy, search engines, social media and general web scraping.

## Install

```bash
pip install scrapebadger-cli
# or: uv tool install scrapebadger-cli
```

The installed command is `scrapebadger`. To run without installing:

```bash
uvx --from scrapebadger-cli scrapebadger --help
```

## Quick Start

```bash
scrapebadger login                 # approve in the browser; or: scrapebadger login --api-key sb_live_...
scrapebadger twitter user elonmusk
scrapebadger twitter search "AI agents" --output table
scrapebadger vinted search "nike shoes" --market de
scrapebadger web scrape https://example.com --js
```

## Getting a key and setting up agents (0.24.0+)

```bash
scrapebadger init                  # detect Claude Code / Codex / Cursor; install skill + MCP
scrapebadger init --yes --all      # same, without prompts
scrapebadger login                 # device flow: open the link, approve, key is saved
scrapebadger trial                 # 50 free credits without an account (one per network, 7 days)
scrapebadger connect               # print the link that attaches a trial key to an account
```

`init` installs the ScrapeBadger skill (`SKILL.md` and `references/endpoints.md`)
into `~/.claude/skills/scrapebadger` and `~/.codex/skills/scrapebadger`, registers
the hosted MCP server (`claude mcp add --scope user ...`, `codex mcp add ...`, or a
merge into `~/.cursor/mcp.json` that keeps your other servers), and offers `login`
or `trial` when no key is configured. Cursor has no on-disk global rules location,
so it gets the MCP server only.

`trial` solves a short proof of work, saves the key and prints a notice to pass on
to your human. A trial key works only from the IP that created it, on read APIs,
at 10 requests/min, and not through the hosted MCP server. It refuses to replace an
account key unless you pass `--force`.

## Saved results and free re-reads

Every API command also writes its full JSON response to
`~/.cache/scrapebadger/results/<api>-<command>-<UTC timestamp>.json` (honours
`XDG_CACHE_HOME`; the newest 200 are kept) and prints one line to stderr:

```
saved: ~/.cache/scrapebadger/results/google-search-20261023T101500123456Z.json · credits: 20 · result_id: 6f1c...
```

stdout is unchanged. Disable with `scrapebadger --no-save ...` or `SCRAPEBADGER_SAVE=0`.

Re-slice a saved result locally, for free:

```bash
scrapebadger view --summary                       # newest result: types, list lengths, byte sizes
scrapebadger view --last google --max-items 5 --fields title,link
scrapebadger view path/to/result.json --jq '.organic_results[].link'   # needs jq on PATH
```

`--fields` (dotted paths) and `--max-items` apply to the main item list (the
top-level array, else the largest top-level list); truncation adds
`"_truncated": {"path", "kept", "total"}`.

Re-read a result from the server within ~15 minutes, free, sliced server-side:

```bash
scrapebadger results get <result_id> --max-items 3 --fields id,text
```

## Quotes, bug reports and feedback (all free)

```bash
scrapebadger quote /v1/google/search -p q="coffee" -p gl=us     # cost, validation, latency
scrapebadger quote /v1/web/scrape --method POST --body '{"url": "https://example.com"}'
scrapebadger report-bug "Empty results for a public profile" --request-id <X-Request-ID> --endpoint /v1/instagram/users/x
scrapebadger feedback "Please add Pinterest" --details "..."
```

Error messages include the `request_id` to quote in a bug report, and the
upgrade or claim link when you are out of credits.

## Environment

| Variable | Default | Purpose |
| --- | --- | --- |
| `SCRAPEBADGER_API_KEY` | | API key (wins over `.env` and `~/.config/scrapebadger/config.json`) |
| `SCRAPEBADGER_API_URL` | `https://scrapebadger.com` | API base URL, e.g. a local stack |
| `SCRAPEBADGER_SITE_URL` | `https://scrapebadger.com` | Where `init` downloads the skill from |
| `SCRAPEBADGER_MCP_URL` | `https://mcp.scrapebadger.com/mcp` | MCP server `init` registers |
| `SCRAPEBADGER_SAVE` | `1` | `0` disables saving results |

## Vinted mobile data (0.14.0+)

```sh
scrapebadger vinted mobile-operations
scrapebadger vinted mobile sold-comparables --market fr --params '{"catalog_id":"1242","brand_id":"53","status_id":"2"}'
scrapebadger vinted search "nike" --sizes 206 --materials 43
```

The catalog lists 76 public read operations with parameter types and examples.
Each mobile read costs 1 credit; discovery is free. Sold comparables are a
Vinted-selected sample, not a complete sales history or guaranteed final sale prices.

### Vinted image search

```bash
scrapebadger vinted search-by-image --image photo.jpg --market nl --price-to 50
scrapebadger vinted search-by-image --image-url https://example.com/photo.webp --brand-ids 53
```

Provide exactly one of `--image`, `--image-url` or `--image-base64`. JPEG, PNG and
WebP up to 5 MiB are supported. Returns active listings in visual ranking order;
10 credits per successful request. Filter with `--catalog-ids`, `--brand-ids`,
`--status-ids`, `--color-ids`, `--size-ids`, `--material-ids` and price bounds.
Resend the same image and `--time` from pagination when requesting `--page 2`.

## Dedicated ecommerce APIs

```bash
scrapebadger etsy search "ceramic mug" --currency USD --country US
scrapebadger aliexpress search "keyboard"
scrapebadger target search "laptop" --zip-code 55403 --store-id 1375
scrapebadger asos search "shoes" --market uk
scrapebadger bestbuy search "laptop"
```

Run `scrapebadger <api> --help` to list product, review, store, availability and
reference commands for that API. Each command supports `--help` for its exact
parameters. Requests use your API key's existing permissions and credit balance.
