ebay-cli

eBay CLI tool for searching items, managing seller orders, and handling shipping. Also works as a Claude Code plugin.

Install

git clone https://github.com/bradjmsu/ebay-cli.git
cd ebay-cli
npm install
npm link

Verify: ebay --version

Setup

1. Create an eBay Developer Account

1. Sign up at https://developer.ebay.com
2. Go to https://developer.ebay.com/my/keys
3. Create a Production keyset if you don't have one
4. Note your App ID (Client ID) and Cert ID (Client Secret)

2. Store Your Credentials

ebay auth set-credentials --app-id "YOUR_APP_ID" --cert-id "YOUR_CERT_ID" --ru-name "YOUR_RU_NAME"

This saves them to ~/.ebay/.env (never committed to git).

With just App ID + Cert ID, you can search and browse items. For seller features (orders, shipping), you need OAuth2 user authentication — continue to step 3.

3. Authenticate with OAuth2 (for seller features)

ebay auth login

This opens eBay's sign-in page in your browser. After you consent:

1. eBay redirects to a success page
2. Copy the full URL from the browser bar (it contains a code= parameter)
3. Extract the code value (everything after code= up to the next &, URL-decoded)
4. Run:

ebay auth exchange "YOUR_AUTHORIZATION_CODE"

This exchanges the code for an access token (2 hours) and refresh token (~18 months). The CLI auto-refreshes expired access tokens using the stored refresh token.

Note: eBay requires HTTPS redirect URIs in production, so the CLI can't catch the callback automatically on localhost. The manual code exchange is the workaround.

To set up the RuName (redirect URL), go to the User Tokens page on the eBay developer portal and configure an eBay Redirect URL for your app.

Verify

ebay auth status --pretty

Usage

Search for Items

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

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

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

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

Search Options

Flag	Description	Default
--limit <n>	Max results	10
--offset <n>	Skip first N results	0
--sort <field>	price, -price, date, -date, newlyListed	relevance
--condition <cond>	NEW, USED, REFURBISHED, UNSPECIFIED	all
--min-price <n>	Minimum price (USD)	—
--max-price <n>	Maximum price (USD)	—
--category <id>	eBay category ID	—
--buy-now	Fixed price listings only	—
--auction	Auction listings only	—
--free-shipping	Free shipping only	—
--fields <list>	Comma-separated fields to include	all
--pretty	Pretty print JSON	—

Item Details

# Full item details
ebay item get "v1|382282567190|651094235351" --pretty

# Compare multiple items
ebay item compare "v1|123,v1|456,v1|789" --pretty

Seller Orders (requires OAuth2)

# List recent orders
ebay orders list --pretty

# Filter by status
ebay orders list --status IN_PROGRESS --pretty

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

# Full order details
ebay orders get "11-06241-16499" --pretty

# Mark order as shipped
ebay orders ship "ORDER_ID" --tracking "9400111899223456789012" --carrier USPS

Common carriers: USPS, UPS, FEDEX, DHL, OTHER

Shipping Labels (requires eBay partner approval)

# Get shipping rates for an order
ebay labels rates "ORDER_ID" --pretty

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

# Download label PDF
ebay labels download "SHIPMENT_ID"

Note: The Logistics API is restricted to approved eBay partners. If you get a 403 error, buy labels on ebay.com or Pirate Ship, then use ebay orders ship to record the tracking number.

Output

All commands output JSON by default. Add --pretty for formatted output, or pipe to jq:

ebay search "gpu" | jq '.items[] | {title, price}'
ebay item get "v1|123" | jq '.specs'

Claude Code Plugin

This repo works as a Claude Code plugin. To install it:

1. Clone the repo and npm install
2. Symlink it into your plugins directory:

ln -s /path/to/ebay-cli /path/to/your/plugins/ebay-cli-skill

3. Register the plugins directory as a local marketplace in your Claude Code settings.json:

{
  "extraKnownMarketplaces": {
    "my-local": {
      "source": {
        "source": "directory",
        "path": "/path/to/your/plugins"
      }
    }
  }
}

The skill doc teaches Claude how to use every command with examples and workflows.

API Access Levels

Not all eBay APIs are available to every developer account. Here's what you can expect:

Feature	API	Access
Search items	Browse API	Open
Item details	Browse API	Open
Seller orders	Fulfillment API	Open (user OAuth)
Mark shipped	Fulfillment API	Open (user OAuth)
Inventory management	Inventory API	Open (user OAuth)
Shipping labels	Logistics API	Restricted (partner approval)
Place orders / Buy It Now	Order API	Restricted (business approval)
Place auction bids	Offer API	Restricted (business approval)

For restricted APIs, apply through the eBay Developer Portal.

Credentials

All credentials are stored locally in ~/.ebay/.env with 600 permissions. Nothing is committed to this repo. You'll need:

Variable	Where to Get It
EBAY_APP_ID	eBay Developer Portal → App ID (Client ID)
EBAY_CERT_ID	Same page → Cert ID (Client Secret)
EBAY_RU_NAME	User Tokens page → RuName (eBay Redirect URL name)
EBAY_REFRESH_TOKEN	Generated via ebay auth login + ebay auth exchange
EBAY_ACCESS_TOKEN	Auto-managed (refreshed from refresh token)

License

MIT