pp-ebay

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/commerce/ebay/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# eBay — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `ebay-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install ebay --cli-only
   ```
2. Verify: `ebay-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/commerce/ebay/cmd/ebay-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.

### Discovery and intelligence
- **`auctions`** — Search active auctions filtered by bid count and ending window (e.g. "Steph Curry cards with at least 3 bids ending in next hour"). The eBay site can no longer answer this query since the Finding API was retired in February 2025.

  _Finds price-discoverable competition windows where last-second bidding actually moves the price._

  ```bash
  ebay-pp-cli auctions "Steph Curry rookie" --has-bids --ending-within 1h --json --select item_id,price,bids,time_left
  ```
- **`comp`** — Average sale price for any item over the last 90 days with smart matching, condition normalization, outlier trim, and percentile distribution.

  _When pricing a bid (or deciding whether to even bother), you need the realistic distribution of recent sales, not a single anchor. Trim handles outliers; dedupe handles title variants._

  ```bash
  ebay-pp-cli comp "Cooper Flagg /50 Topps Chrome" --trim --json --select mean,median,sample_size
  ```
- **`comp` outlier trim** — 1.5x IQR outlier trim on sold-comp results. Surfaces the realistic price band buyers should anchor on, with stddev and quartiles.

  _Tells you what a normal buyer actually paid versus a record sale or a fire-sale outlier._

  ```bash
  ebay-pp-cli comp "Rolex Submariner 116610LN" --trim --json --select p25,median,p75,std_dev
  ```
- **`comp --dedupe-variants`** — Collapse near-duplicate sold listings to one exemplar per fingerprint (token-bag, order-insensitive).

  _Without dedupe, the comp distribution is biased toward whichever seller listed the same card 5 times._

  ```bash
  ebay-pp-cli comp "Cooper Flagg /50" --dedupe-variants
  ```
- **`listings`** — Active listing search filtered by auction/BIN, condition, and price band.

  ```bash
  ebay-pp-cli listings --nkw "PSA Mariners Griffey" --lh-bin 1 --udlo 10 --udhi 30
  ```

## When to use

- User asks "what did this card / watch / item sell for" → `ebay-pp-cli comp "<title>" --trim`
- User asks "find auctions ending soon with bids" → `ebay-pp-cli auctions "<query>" --has-bids --ending-within 1h`
- User asks "find Buy It Now listings under $X for ..." → `ebay-pp-cli listings --nkw "<query>" --lh-bin 1 --udhi <max>`
- User asks "watch this listing" / "show my watchlist" → `ebay-pp-cli watch list`
- User asks to bid programmatically → **explain the limitation** (eBay step-ups auth on `/bfl/placebid`); link them to bid in the browser. Do not run `bid` or `snipe` on their behalf.

## Anti-triggers

This CLI is NOT the right tool for:
- **Placing bids.** `bid`/`snipe`/`bid-group` are experimental and fail end-to-end. Direct the user to bid in their browser.
- Listing items as a seller (use the eBay Sell APIs / Seller Hub directly).
- Order fulfillment or shipping label generation.
- Bulk inventory management for sellers.

## Known Limitations

- **Bid placement** (`bid`, `snipe`, `bid-group`) cannot complete end-to-end because eBay step-ups auth on `/bfl/placebid` for cookie-only sessions. These commands are hidden from default `--help` and print a warning when invoked. Users should bid in the browser.
- **Rate limiting**: Sustained scraping triggers eBay 403s. Recovery: `ebay-pp-cli auth refresh` and back off.
- **Stub commands**: Watchlist write paths, saved-search CRUD, feed, offer-hunter ship as "not yet implemented" stubs.

## HTTP Transport

This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls.

## Discovery Signals

This CLI was generated with browser-observed traffic context.
- Capture coverage: 15 API entries from 25 total network entries
- Protocols: html_scraping (95% confidence), rest_json (90% confidence)
- Auth signals: — cookies: cid, s, nonsession, dp1, ebaysid, ds1, ds2, shs, npii
- Generation hints: requires_browser_auth, requires_protected_client, uses_chrome_cookie_import, has_per_request_csrf, has_per_request_fraud_token
- Caveats: placebid_step_up: eBay redirects /bfl/placebid/<id> to sign-in for cookie-only sessions, so bid placement cannot complete from this CLI today; akamai_active: Akamai bot manager active — Surf must use Chrome TLS fingerprint or stdlib HTTP will be blocked; rate_limit: sustained scraping triggers 403s, recover with auth refresh and back off

## Command Reference

**deal** — eBay Deals feed

- `ebay-pp-cli deal` — Browse the eBay Deals feed

**item** — Item details

- `ebay-pp-cli item <itemId>` — Get item detail by listing id

**listings** — Active listing search (HTML scrape of /sch/i.html)

- `ebay-pp-cli listings` — Search active eBay listings by keyword

**sold** — Sold/completed listings (last 90 days, HTML scrape)

- `ebay-pp-cli sold` — Search sold completed listings by keyword (90 day window)

**watch** — Watchlist (authenticated, read-only)

- `ebay-pp-cli watch` — List items in the user's watchlist


**Hand-written commands**

- `ebay-pp-cli comp <query>` — Sold-comp intelligence: average sale price, distribution, trendline for items matching the query over the last 90 days.
- `ebay-pp-cli auctions <query>` — Search active auctions filtered by bid count, ending window, condition. The 'has bids ending in next hour' query.
- `ebay-pp-cli feed <saved-search>` — Stream new listings matching a saved search, with sold-comp context appended to each item.
- `ebay-pp-cli history` — Buying history (won, lost, paid) over a configurable window.
- `ebay-pp-cli saved-search` — Local saved-search CRUD.

**Hidden experimental commands**

These commands exist in the binary but are excluded from `--help` because they currently fail end-to-end. Reach them by name (e.g. `ebay-pp-cli snipe --help`) for details.

- `ebay-pp-cli bid` — Place bids (experimental; eBay step-up auth blocks).
- `ebay-pp-cli snipe <itemId> --max <amount>` — Sniper bid (experimental; depends on bid flow).
- `ebay-pp-cli bid-group` — Coordinated multi-item snipe groups (experimental; depends on snipe).


### Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

```bash
ebay-pp-cli which "<capability in your own words>"
```

`which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query.

## Auth Setup

This CLI uses a browser session. Log in to .ebay.com in Chrome, then:

```bash
ebay-pp-cli auth login --chrome
``