FlipScout — install and run

Written for a flipper, not a developer. If you can copy a command from this page and paste it into a terminal, you are set. If a command surprises you, stop and email support@flipscout.dev before running it.

What you'll need

• A Mac, Linux box, or Windows machine (WSL is fine).
• Node.js 20 or newer. Install from nodejs.org — the "LTS" download is the one you want.
• About 500 MB free disk for Chromium (installed once, in the next step).
• Your own name, email, phone, and ZIP. That's what the CLI sends to Algo — see the warning two sections down.

Install

npm install -g flipscout
npx playwright install chromium   # one time, ~200 MB

If npm install fails with a permissions error on Mac or Linux, either re-run under a Node version manager (nvm, fnm, volta) or prefix with sudo. Neither is required if Node was installed under your user account.

Configure your contact block

Copy the shipped example to a local override and edit it:

cp $(npm root -g)/flipscout/config.example.json ./config.local.json
$EDITOR config.local.json

Fill in real values for the four fields under contact:

{
  "contact": {
    "firstName": "Dylan",
    "lastName": "Worsoff",
    "email": "you@example.com",
    "phone": "5125550123",
    "zip": "78704"
  },
  "state": "TX"
}

The CLI refuses to run quote if any of the four contact fields are missing, still holding a placeholder (YOUR_FIRST_NAME), or badly formatted (an email without an @, a phone that isn't 10 digits, etc.). This is not a warning — it's a hard stop. That is what keeps a YOUR_FIRST_NAME lead from ever reaching Auto Lenders' CRM.

Your first scan

flipscout scan --zip 78704 --radius 75 --max-price 20000 --pages 3

What the scan does, top to bottom:

1. Opens an Autotrader by-owner search for the ZIP + radius + price cap.
2. Walks up to --pages pages, collecting every listing (deduped by VIN).
3. Pulls each listing's KBB Fair Purchase Price from the search row.
4. Scores each row with the red-flag ladder and the ranking formula.
5. Prints the top 25 (by rank) as an aligned terminal table.
6. Writes a sortable HTML report to data/report.html.
7. Stores every listing (with a per-VIN price history) in data/db.json.

Re-run flipscout scan tomorrow. It'll upsert the same rows and flag any price drops in the per-VIN price history. That is how you catch a motivated seller cutting an asking price on a car FlipScout already knows about.

What each column in the report means

The ranking formula

rank = max(0, kbbFpp − price) / price
        × for each flag: fatal→0, major→0.4, minor→0.7
        × daysOnSite multiplier (bell curve, peaks 20-60d, penalises > 90d)
        × imageCount multiplier (≤ 2 photos = 0.60, 6-20 with no flags = 1.10)
        × mileage multiplier (over 120k graduated, floor 0.40)

Deterministic. No ML, no black box. If you disagree with a rank, the reasons array tells you exactly which multiplier drove it.

Requesting an Algo floor (flipscout quote)

flipscout quote --vins WMWSY1C50DT429431 --yes           # one VIN
flipscout quote --top 5 --yes                             # top 5 unfloored
flipscout quote --vins A,B --yes --dry-run                # dry run, safe

What every submission does:

1. Validates the four contact fields (missing / placeholder / bad format = hard stop).
2. Opens a fresh Chromium context per VIN.
3. Walks the Algo instant-offer form: VIN → radio-check → contact → trim pick → confirm → get estimate.
4. Parses the estimate range from Algo's confirmation page.
5. Stores {low, high, decodedVehicle, trimPicked, leadId} on the listing.
6. Writes an audit-log line to data/leads.jsonl.
7. Waits ~40 seconds before the next VIN, so ten quotes take ~7 minutes.

Activate your paid license (Pro / Shop)

flipscout scan and flipscout report are free forever. flipscout quote is the paid feature — the Algo instant-offer floor is what Pro and Shop pay for. After paying at pricing you'll be redirected to a success page showing your license key. Bind it to this machine with:

flipscout activate flp_live_XXXXXXXXXXXXXXXXXXXXXXXX

What activation does:

• Computes a stable machine id — sha256(hostname + username + first non-internal MAC).
• POSTs {key, machine_id} to /activate on the license server.
• On success writes ~/.config/flipscout/license.json (chmod 600) with {key, plan, activated_at, machine_id, last_verified_at}. The license-server URL comes from licenseServer in config.local.json; the request payload is the key and the machine id only — no card details, no email, no phone.
• On refusal (bad key, machine cap reached, unknown plan) prints the server's message and exits with code 1. Nothing is written on failure.

Check what's currently installed with flipscout license. That subcommand prints the plan, a masked key (first 4 + last 4, middle stars), the activation timestamp, the machine id, and the last-verify timestamp. It never prints the raw key.

Offline grace. flipscout quote verifies against the license server before each run. If the server is unreachable, the CLI honours a seven-day offline grace anchored on the last successful verify. Ten days of no connectivity turns into a refusal; three days does not.

Re-render the report without a fresh scan

flipscout report

Opens data/db.json, re-runs scoring, writes the terminal top-25 and the HTML report. No network. Handy after you've run quote on a handful of VINs and want a fresh HTML file that shows the new floors.

Check your config without leaking PII

flipscout config

Prints which files were loaded, which fields are set, and whether the contact block would pass Algo validation. Emails and phones are redacted to first-char + last-char (d********************m) so the output is safe to paste into a bug report.

Known limitations

• Autotrader by-owner only. Dealer listings are excluded — dealers price to KBB, so there's no arbitrage.
• KBB FPP is a retail reference. A listing 15% below FPP isn't automatically a deal — it's a deal only if the private-party value covers it. See the "Rank off private-party value" v0.2 ticket.
• Algo covers ~90% of US ZIPs but not every vehicle. Pre-2005 or exotic vehicles come back with no estimate. That's a floor: null, not a bug.
• One region per config. If you flip in both Austin and Chicago, keep two config.local.json files in two directories.
• The store is a JSON file. Atomic (temp + rename) but not concurrent — don't run two scans against the same data/db.json at the same time.
• Fresh browser context per Algo call. ~40 seconds per VIN. Ten quotes = ~7 minutes wall time. That's not a bug — it's the cost of not tripping Algo's returning-visitor form variant.

Legal and ethics — read this before quote

• Every quote submission is a real lead in Auto Lenders' CRM. A salesperson will call. Don't quote a VIN you have no intention of considering — you're spending a real person's time.
• Texas caps unlicensed private-party sales at 4 per rolling 12 months. Above that the state considers you a dealer. Other states range 2 to 12 — see the long-form article on state caps.
• Autotrader / KBB scraping is for personal use only. The CLI runs in your browser session, at your IP. Don't point it at a shared service, don't resell the output, don't crank concurrency.
• The Algo quote is real. Auto Lenders will honor the number if the vehicle matches the VIN decode. Treat floor.low as your true downside.
• Nothing is fabricated. If Algo doesn't return a number within 30 seconds, the floor stays null and the report says so.

Docs last verified against FlipScout v0.1 (2026-09-11). Report inaccuracies to support@flipscout.dev.