# gxbvc/ebay-cli architecture

> Architecture diagram of the GitHub repository gxbvc/ebay-cli, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gxbvc/ebay-cli
- Repository: https://github.com/gxbvc/ebay-cli

## Overview

ebay-cli is a command-line market-research tool: users search active listings, retrieve item details, or inspect sold prices, with JSON results written to stdout. The CLI dispatches each command; search and item use Browse API OAuth, while sold uses Finding API app-ID authentication. Shared configuration supplies credentials and API environment, and OAuth tokens are cached locally. The README documents these capabilities; edges reflect the sampled command, auth, and configuration code.

Main entry points: [`src/auth.ts`](https://github.com/gxbvc/ebay-cli/blob/main/src/auth.ts) (OAuth token manager), [`src/commands/search.ts`](https://github.com/gxbvc/ebay-cli/blob/main/src/commands/search.ts) (Active search), [`src/commands/item.ts`](https://github.com/gxbvc/ebay-cli/blob/main/src/commands/item.ts) (Item details), [`src/cli.ts`](https://github.com/gxbvc/ebay-cli/blob/main/src/cli.ts) (Command dispatcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["CLI interface"]
  node_launcher["CLI launcher<br/>[ebay-cli.js]"]
  node_dispatcher["Command dispatcher<br/>[cli.ts]"]
  node_config["Credential config<br/>[config.ts]"]
  node_json_output["JSON stdout"]
end

subgraph group_browse["Browse workflow"]
  node_search["Active search<br/>[search.ts]"]
  node_item["Item details<br/>[item.ts]"]
  node_auth["OAuth token manager<br/>[auth.ts]"]
  node_token_cache[("Token cache<br/>[auth.ts]")]
  node_oauth["eBay OAuth service"]
  node_browse_api["eBay Browse API"]
end

subgraph group_research["Sold research"]
  node_sold["Sold listings<br/>[sold.ts]"]
  node_finding_api["eBay Finding API"]
end

node_user(("CLI user"))

node_user -->|"runs commands"| node_launcher
node_launcher -->|"loads"| node_dispatcher
node_dispatcher -->|"dispatches search"| node_search
node_dispatcher -->|"dispatches item"| node_item
node_dispatcher -->|"dispatches sold"| node_sold
node_search -->|"gets token"| node_auth
node_item -->|"gets token"| node_auth
node_auth -->|"reads credentials"| node_config
node_search -->|"reads API URL"| node_config
node_item -->|"reads API URL"| node_config
node_sold -->|"reads app ID"| node_config
node_auth -->|"reads and writes"| node_token_cache
node_auth -->|"requests token"| node_oauth
node_oauth -->|"returns token"| node_auth
node_search -->|"searches listings"| node_browse_api
node_item -->|"fetches item"| node_browse_api
node_sold -->|"searches completed"| node_finding_api
node_search -->|"prints results"| node_json_output
node_item -->|"prints details"| node_json_output
node_sold -->|"prints results"| node_json_output

click node_launcher "https://github.com/gxbvc/ebay-cli/blob/main/bin/ebay-cli.js"
click node_dispatcher "https://github.com/gxbvc/ebay-cli/blob/main/src/cli.ts"
click node_search "https://github.com/gxbvc/ebay-cli/blob/main/src/commands/search.ts"
click node_item "https://github.com/gxbvc/ebay-cli/blob/main/src/commands/item.ts"
click node_auth "https://github.com/gxbvc/ebay-cli/blob/main/src/auth.ts"
click node_config "https://github.com/gxbvc/ebay-cli/blob/main/src/config.ts"
click node_token_cache "https://github.com/gxbvc/ebay-cli/blob/main/src/auth.ts"
click node_sold "https://github.com/gxbvc/ebay-cli/blob/main/src/commands/sold.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_launcher,node_dispatcher,node_config,node_json_output,node_user toneBlue
class node_search,node_item,node_auth,node_token_cache,node_oauth,node_browse_api toneAmber
class node_sold,node_finding_api toneMint
```

## Components

### CLI interface

- [CLI launcher](https://github.com/gxbvc/ebay-cli/blob/main/bin/ebay-cli.js): `bin/ebay-cli.js`
- [Command dispatcher](https://github.com/gxbvc/ebay-cli/blob/main/src/cli.ts): `src/cli.ts`
- [Credential config](https://github.com/gxbvc/ebay-cli/blob/main/src/config.ts): `src/config.ts`
- **JSON stdout**

### Browse workflow

- [Active search](https://github.com/gxbvc/ebay-cli/blob/main/src/commands/search.ts): `src/commands/search.ts`
- [Item details](https://github.com/gxbvc/ebay-cli/blob/main/src/commands/item.ts): `src/commands/item.ts`
- [OAuth token manager](https://github.com/gxbvc/ebay-cli/blob/main/src/auth.ts): `src/auth.ts`
- [Token cache](https://github.com/gxbvc/ebay-cli/blob/main/src/auth.ts): `src/auth.ts`
- **eBay OAuth service**
- **eBay Browse API**

### Sold research

- [Sold listings](https://github.com/gxbvc/ebay-cli/blob/main/src/commands/sold.ts): `src/commands/sold.ts`
- **eBay Finding API**

### Other components

- **CLI user**

## Connections

- CLI user → CLI launcher: runs commands (evidence: `README.md`)
- CLI launcher → Command dispatcher: loads (evidence: `bin/ebay-cli.js`)
- Command dispatcher → Active search: dispatches search (evidence: `src/cli.ts`)
- Command dispatcher → Item details: dispatches item (evidence: `src/cli.ts`)
- Command dispatcher → Sold listings: dispatches sold (evidence: `src/cli.ts`)
- Active search → OAuth token manager: gets token (evidence: `src/commands/search.ts`)
- Item details → OAuth token manager: gets token (evidence: `src/commands/item.ts`)
- OAuth token manager → Credential config: reads credentials (evidence: `src/auth.ts`)
- Active search → Credential config: reads API URL (evidence: `src/commands/search.ts`)
- Item details → Credential config: reads API URL (evidence: `src/commands/item.ts`)
- Sold listings → Credential config: reads app ID (evidence: `src/commands/sold.ts`)
- OAuth token manager → Token cache: reads and writes (evidence: `src/auth.ts`)
- OAuth token manager → eBay OAuth service: requests token (evidence: `src/auth.ts`)
- eBay OAuth service → OAuth token manager: returns token (evidence: `src/auth.ts`)
- Active search → eBay Browse API: searches listings (evidence: `src/commands/search.ts`)
- Item details → eBay Browse API: fetches item (evidence: `src/commands/item.ts`)
- Sold listings → eBay Finding API: searches completed (evidence: `src/commands/sold.ts`)
- Active search → JSON stdout: prints results (evidence: `src/commands/search.ts`)
- Item details → JSON stdout: prints details (evidence: `src/commands/item.ts`)
- Sold listings → JSON stdout: prints results (evidence: `src/commands/sold.ts`)