Amazon Search Skill

Search Amazon for products matching a keyword query and return structured JSON results.

Prerequisites

Install Bun runtime:

curl -fsSL https://bun.sh/install | bash

Install skill dependencies:

cd skills/amazon-search
bun install

Install Playwright browsers (required for Amazon search):

cd skills/amazon-search/scripts
npm install
npx playwright install chromium

Cookie

This skill uses Playwright to search Amazon directly in a headless browser. No manual cookie management is required.

Playwright Prerequisites

Install npm dependencies and Playwright browsers:

cd skills/amazon-search/scripts
npm install
npx playwright install chromium

Inputs

Output Format

Returns a JSON object containing search metadata and an array of Amazon product objects.

Results are automatically saved to results/<keyword>_<timestamp>_<count>.json.

{
  "keyword": "shirt",
  "timestamp": "2026-04-06T12:34:56.789Z",
  "count": 10,
  "items": [
    {
      "id_": "B09TPN9NJ6",
      "uuid": "418e2c7d-ccaa-4ca3-9d1b-6b4f3bd406b0",
      "original_image_url": "https://m.media-amazon.com/images/I/91YprRrDB4L._AC_UL960_FMwebp_QL65_.jpg",
      "title": "Amazon Essentials Men's Slim-Fit Crewneck T-Shirts, Short Sleeve",
      "item_page": "https://www.amazon.com/dp/B09TPN9NJ6",
      "rating": 4.4,
      "review_count": 1787,
      "price": "$19.99",
      "description": "Amazon Essentials Men's Slim-Fit Crewneck T-Shirts, Short Sleeve"
    }
  ]
}

Item Fields

Execution

Use the script at scripts/amazon_search.ts.

All TypeScript files must be run with Bun:

# Simple search
bun run scripts/amazon_search.ts "shirt"

Configuration Tool

Use scripts/configure.ts to generate environment variable commands and manage cache:

# Generate proxy setting command (copy and run the output)
bun run scripts/configure.ts proxy "http://127.0.0.1:7890"

# List cache files
bun run scripts/configure.ts listcache

# Clear cache for specific keyword
bun run scripts/configure.ts clearcache "shirt"

# Clear all caches
bun run scripts/configure.ts clearcache --all

Usage Notes

• Runtime: All TypeScript files must be run with bun run
• Search Method: Uses Playwright to search Amazon directly in a headless browser (no manual cookie management needed)
• Proxy Support: Proxy is read from T2P_PROXY environment variable (or --proxy CLI flag). Supports both HTTP/HTTPS and SOCKS5 proxies (e.g., socks5://127.0.0.1:1080).
• Cache & Deduplication: Search results are cached to resultscache/<sanitizedQuery>_cache.md. Each line is an ASIN/uuid used for deduplication.
• Incremental Mode: Use --incremental to output only items not present in the cache.
• Clear Cache: Use --clear-cache to delete this keyword cache before searching, or use scripts/configure.ts clearcache.
• Custom Output: Use --output=/path/to/dir to save results to a custom directory.
• Download Images: Use --download to automatically download product images using @t2p/image-cache after search completes.

Example

All commands use bun run:

# Simple search
bun run scripts/amazon_search.ts "t-shirt"

# Incremental search - only output new results not in cache
bun run scripts/amazon_search.ts "t-shirt" --incremental

# Clear cache before searching
bun run scripts/amazon_search.ts "t-shirt" --clear-cache --incremental

# Use proxy
bun run scripts/amazon_search.ts "t-shirt" --incremental --proxy "http://127.0.0.1:10809"

# Multi-page search (fetch 2 pages, ~40-120 results)
bun run scripts/amazon_search.ts "t-shirt" --pages=2

# Multi-page + incremental (only new items from all pages)
bun run scripts/amazon_search.ts "t-shirt" --pages=2 --incremental

# Limit to specific number of products (stops early if limit reached)
bun run scripts/amazon_search.ts "t-shirt" --pages=5 --num-products=50

# Specify custom output directory
bun run scripts/amazon_search.ts "t-shirt" --output=/path/to/custom/results

# Download images after search
bun run scripts/amazon_search.ts "t-shirt" --download

# Combined: search with download and custom output
bun run scripts/amazon_search.ts "t-shirt" --download --output=/path/to/results

Error Handling