pp-offerup

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/commerce/offerup/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/". -->

# OfferUp — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `offerup-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 offerup --cli-only
   ```
2. Verify: `offerup-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/offerup/cmd/offerup-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.

## When to Use This CLI

Use this CLI when an agent or user needs local-marketplace data from OfferUp: searching listings near a ZIP, pulling an item's full detail, vetting a seller, or — its real edge — answering price questions (what's the going rate, what's underpriced, what dropped) over a local store of listings. All of that works with no login. When logged in (`auth login --chrome`), it also manages your own account: your listings (view active/archived, mark sold, archive), saved lists, and messages. It does not create listings (OfferUp web posts Jobs only; listing creation is mobile-app-only) or send messages.

## When Not to Use This CLI

The public commands are read-only. The authenticated commands add two account mutations — `my-listings mark-sold` and `my-listings archive` — both gated behind login and an explicit `--confirm`. Do not use this CLI to create/post a listing (mobile-app-only), send messages, make or accept offers, purchase, or otherwise change remote state it does not expose.

## Unique Capabilities

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

### Local price intelligence
- **`price-check`** — See the real going rate for an item in your area — median, 25th/75th percentile, min, max, and the firm-vs-negotiable split — computed across every listing you've pulled.

  _Reach for this before buying or pricing a resale — it answers "what is this actually worth here" with a number instead of a scroll._

  ```bash
  offerup-pp-cli price-check "herman miller aeron" --zip 85001 --agent
  ```
- **`deals`** — Surface listings priced a chosen percentage below the local median for that item — the underpriced finds, ranked by how far under they are.

  _The deal-sniping command: it tells an agent which listings are underpriced right now, not just what exists._

  ```bash
  offerup-pp-cli deals "dewalt drill" --zip 98101 --below 25 --agent
  ```
- **`price-drops`** — Detect listings whose price fell between syncs — the same item, now cheaper — sorted by the size of the drop.

  _Catches sellers who just cut a price on something you're tracking — the moment to make an offer._

  ```bash
  offerup-pp-cli price-drops "macbook pro" --since 7d --agent
  ```

### Track saved searches
- **`new-since`** — Show only the listings that appeared since a cutoff for a saved search, so you never re-scan items you already saw.

  _Use this for a recurring watch — it answers "what dropped since I last looked" in one call._

  ```bash
  offerup-pp-cli new-since "road bike" --since 24h --agent
  ```
- **`digest`** — A single composite report for a saved search combining what's new, what dropped in price, and what's underpriced.

  _The morning-ritual command and the natural single MCP tool call for an agent watching a market._

  ```bash
  offerup-pp-cli digest "snowboard" --since 24h --agent
  ```

### Seller intelligence
- **`seller-scan`** — Pull a seller's full synced inventory alongside their reputation badges (business/dealer/TruYou), join date, and the median asking price across their listings.

  _Vet a dealer before buying to flip, or watch a high-volume seller's pricing in one view._

  ```bash
  offerup-pp-cli seller-scan 161842229 --agent
  ```

## Authenticated Commands (login required)

These act on the user's own OfferUp account and need a captured session. Auth is the OfferUp web session cookie, captured once via the `press-auth` companion through a controlled Chrome login window (no API key; the session is encrypted at rest). All public commands above need none of this.

```bash
offerup-pp-cli auth login --chrome     # one-time: opens Chrome, captures the session
offerup-pp-cli auth status --json      # {"loggedIn": true, "pressAuthInstalled": true}
offerup-pp-cli account --agent         # your own profile + reputation (auth tokens never surfaced)
offerup-pp-cli my-listings --agent     # your active listings
offerup-pp-cli my-listings archived --agent
offerup-pp-cli saved --agent           # your saved/favorited lists
offerup-pp-cli messages --agent        # your message threads
offerup-pp-cli messages read <discussion-id> --agent
```

Mutations preview by default and apply only with `--confirm`:

```bash
offerup-pp-cli my-listings mark-sold <listing-id> --confirm
offerup-pp-cli my-listings archive <listing-id> --confirm
```

Without login, these commands exit with an auth error pointing at `auth login --chrome` (exit code 4). Creating a new listing is not supported (mobile-app-only).

## 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.

## Command Reference

**listings** — Search and view OfferUp listings (public, no login)

- `offerup-pp-cli listings get` — Get the full detail for one listing
- `offerup-pp-cli listings search` — Search live OfferUp listings by keyword and location


### Finding the right command

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

```bash
offerup-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.

## Recipes

### Narrow a verbose search for an agent

```bash
offerup-pp-cli listings search "macbook pro" --zip 98101 --agent --select listingId,title,price,locationName,conditionText
```

Listing payloads are wide; --agent with --select returns only the fields an agent needs, saving context.

### Find this week's underpriced finds

```bash
offerup-pp-cli deals "aeron chair" --zip 85001 --below 30 --agent
```

Lists Aeron chairs priced at least 30% below the local median around Phoenix.

### Daily watch on a saved search

```bash
offerup-pp-cli digest "road bike" --since 24h --agent
```

One call returns what's new, what dropped in price, and what's a deal for road bikes since yesterday.

### Vet a seller before buying to flip

```bash
offerup-pp-cli seller-scan 161842229 --agent
```

Shows the seller's badges, join date, full inventory, and median asking price in one view.

## Auth Setup

Public commands need no login: search, item detail (listings get), seller lookup, category-scoped browse, and every price-intelligence command (price-check, deals, new-since, price-drops, digest, seller-scan). Set location with --zip (or --lat/--lon), not a credential. Account commands act on your own OfferUp account and require