---
name: ebay
description: "MUST use this skill for ANY eBay operations — searching for items, comparing prices, finding deals, managing seller orders, shipping fulfillment, or printing shipping labels. Use when the user asks to search eBay, find something on eBay, check eBay prices, compare eBay listings, look up an eBay item, list their eBay orders, mark an order as shipped, get shipping labels, or mentions eBay in any buying or selling context. Also use when the user mentions ebay CLI. This is the only approved tool for eBay operations — do not use curl or direct API calls."
---

# eBay CLI

Search, shop, sell, and ship on eBay from the terminal using the `ebay` CLI.

## API Access Levels

Some eBay APIs require special approval. Here's what works now vs. what needs eBay's approval:

| Feature | Status | Notes |
|---------|--------|-------|
| Search items | **Works** | Browse API, no user auth needed |
| Item details | **Works** | Browse API |
| List seller orders | **Works** | Requires user OAuth |
| Mark order shipped | **Works** | Requires user OAuth |
| Shipping labels | **May be restricted** | Logistics API, needs eBay partner approval |
| Place orders / Buy It Now | **Restricted** | Order API, needs eBay business approval |
| Place auction bids | **Restricted** | Offer API, needs eBay business approval |

## Prerequisites

```bash
npm link  # from /Users/brad/Projects/lazio/cli-tools/ebay/
```

Verify: `ebay --version`

## Authentication

Credentials are stored in `~/.ebay/.env`. The CLI auto-loads them.

### Quick Setup (App ID only — for searching)

```bash
ebay auth set-credentials --app-id "YOUR_APP_ID" --cert-id "YOUR_CERT_ID"
```

### Full Setup (for selling/orders)

1. Go to https://developer.ebay.com/my/keys
2. Under OAuth tab, click "Sign in to Production"
3. Sign in and authorize
4. Copy the refresh token
5. Run:

```bash
ebay auth set-credentials --app-id "YOUR_APP_ID" --cert-id "YOUR_CERT_ID" --ru-name "YOUR_RU_NAME"
ebay auth set-token YOUR_REFRESH_TOKEN
```

**Verify auth:**
```bash
ebay auth status --pretty
```

## Output Formats

All commands output JSON by default. Add `--pretty` for formatted output. Pipe to `jq` for processing:

```bash
ebay search "vintage watch" | jq '.items[].title'
ebay item get v1|123456 | jq '.price'
```

## Core Workflows

### Search for Items

```bash
# Basic search
ebay search "mechanical keyboard" --pretty

# With filters
ebay search "macbook pro" --condition USED --max-price 800 --buy-now --pretty

# Auction only, sorted by price
ebay search "vintage rolex" --auction --sort price --limit 5 --pretty

# Free shipping only
ebay search "usb-c dock" --free-shipping --min-price 50 --max-price 200 --pretty

# By category
ebay search "shoes" --category 93427 --condition NEW --pretty
```

**Search options:**
- `--limit <n>` — max results (default 10)
- `--sort <field>` — price, -price, date, -date, newlyListed
- `--condition <cond>` — NEW, USED, REFURBISHED, UNSPECIFIED
- `--min-price <n>` / `--max-price <n>` — price range
- `--buy-now` — fixed price only
- `--auction` — auctions only
- `--free-shipping` — free shipping only
- `--category <id>` — eBay category ID

### Get Item Details

```bash
ebay item get "v1|382282567190|651094235351" --pretty
```

Returns: title, price, condition, seller info, shipping options, return policy, specs, images, and eBay URL.

### Compare Items

```bash
ebay item compare "v1|123,v1|456,v1|789" --pretty
```

### List Seller Orders

```bash
# All recent orders
ebay orders list --pretty

# In-progress orders only
ebay orders list --status IN_PROGRESS --pretty

# Last 7 days
ebay orders list --days 7 --pretty
```

### Get Order Details

```bash
ebay orders get "11-06241-16499" --pretty
```

### Mark Order as Shipped

```bash
ebay orders ship "11-06241-16499" --tracking "9400111899223456789012" --carrier USPS --pretty
```

Common carriers: USPS, UPS, FEDEX, DHL

### Shipping Labels

> Note: The Logistics API may require eBay partner approval. If you get a 403 error, buy labels on ebay.com or Pirate Ship, then use `ebay orders ship` to record tracking.

```bash
# Get shipping rates
ebay labels rates "11-06241-16499" --pretty

# Create label from quote
ebay labels create "QUOTE_ID" --pretty

# Download label PDF
ebay labels download "SHIPMENT_ID"
```

### Common Multi-Step Workflows

**Find the best deal:**
```bash
# Search and compare top results
ebay search "sony wh-1000xm5" --buy-now --sort price --limit 5 --pretty
# Then get details on the cheapest
ebay item get "v1|ITEM_ID" --pretty
```

**Ship an order:**
```bash
# 1. List unshipped orders
ebay orders list --status NOT_STARTED --pretty
# 2. Get order details for shipping address
ebay orders get "ORDER_ID" --pretty
# 3. After purchasing label externally, mark shipped
ebay orders ship "ORDER_ID" --tracking "TRACKING_NUM" --carrier USPS
```

## Command Quick Reference

| Group | Commands | Details |
|-------|----------|---------|
| `auth` | set-credentials, set-token, status, login | [—] |
| `search` | (direct) | [search.md](references/search.md) |
| `item` | get, compare | [search.md](references/search.md) |
| `orders` | list, get, ship | [orders.md](references/orders.md) |
| `labels` | rates, create, download | [labels.md](references/labels.md) |

## Troubleshooting

**"EBAY_APP_ID not set":** Run `ebay auth set-credentials --app-id <id> --cert-id <secret>`.

**"Not authenticated":** Run `ebay auth set-token <refresh_token>`. Get token from https://developer.ebay.com/my/keys.

**"403" on labels commands:** Logistics API requires eBay partner approval. Buy labels on ebay.com or Pirate Ship instead.

**"403" on search:** Your App ID may be invalid. Check `ebay auth status --pretty`.

**Empty search results:** Try broader keywords, remove filters, or check category ID is valid.