---
name: adom-digikey
description: Search DigiKey Electronics for components, pricing, stock, and part numbers. Use when the user asks to find components on DigiKey, check DigiKey pricing, look up a DigiKey part number, search for in-stock parts, get price breaks, compare alternatives, or find a datasheet or product page for a specific part. Also use for "open digikey", "digikey app", "digikey search UI".
---

# DigiKey Electronics Search

Search DigiKey's catalog of millions of electronic components from thousands of manufacturers. Real-time pricing, stock, lead times, and product links.

## What you have

A single CLI — `adom-digikey` — with three faces:

1. **One-shot search from the shell**, for when the AI just needs the data:
   ```bash
   adom-digikey search "STM32F103RBT6"
   adom-digikey part 296-STM32F103RBT6-ND
   adom-digikey health
   ```
   Each prints JSON on stdout and an `OK:` / `ERROR:` line on stderr, so `| jq` works cleanly.

2. **A Hydrogen webview app**, for when the user wants to browse interactively:
   ```bash
   adom-digikey app        # opens a "DigiKey Search" tab in Hydrogen
   ```
   The app has a search bar, in-stock filter, per-result cards with price breaks, MPN/DigiKey-PN copy buttons, datasheet + product-page links, and hover tooltips on every control.

3. **A backend HTTP service** (port 8777), which is what the shared `service-digikey` container runs:
   ```bash
   adom-digikey serve      # DIGIKEY_CLIENT_ID must be set
   ```
   The CLI and the app both talk to this backend over HTTP (`POST /` with an `{"action":"search"|"part"|"health", ...}` body, or `GET /search?keyword=...`). It caches responses for 10 min and keeps the API key server-side.

There is no MCP server. All access is through the CLI + HTTP service.

## Commands

### `adom-digikey search <keyword>`

Search by keyword, MPN, or DigiKey PN.

| Flag | Default | Description |
|---|---|---|
| `--limit N` | 10 | Max results (1–50) |
| `--in-stock-only` | false | Only parts currently in stock |
| `--api URL` / `$DIGIKEY_API` | auto | Backend URL. If unset, the CLI tries `http://127.0.0.1:8777`, and if that's also down it falls back to calling DigiKey directly (requires `DIGIKEY_CLIENT_ID`) |

Examples:
```bash
adom-digikey search "STM32F103RBT6" --limit 5
adom-digikey search "USB-C connector" --in-stock-only
adom-digikey search "LDO 3.3V 500mA SOT-23"
adom-digikey search "ESP32 WiFi Bluetooth" | jq '.components[].mpn'
```

### `adom-digikey part <part-number>`

Full detail lookup for a specific part. Accepts DigiKey PN (`296-STM32F103RBT6-ND`) or MPN (`STM32F103RBT6`). Returns a single-component result with full price-break table and attributes.

```bash
adom-digikey part 296-STM32F103RBT6-ND
adom-digikey part STM32F103RBT6 | jq '.components[0].price_tiers'
```

### `adom-digikey app`

Open the search UI in a Hydrogen webview tab.

| Flag | Default | Description |
|---|---|---|
| `--port N` | 8891 | Local app HTTP server port |
| `--api URL` | auto | Backend to use (same resolution as `search`) |
| `--tab-name S` | "DigiKey Search" | Hydrogen tab label |
| `--no-tab` | false | Skip opening the tab (test via curl or browser) |
| `--dev` | false | Enable the `/eval` hot-patch channel |

```bash
adom-digikey app                         # normal use
adom-digikey app --dev                   # enable /eval for UI debugging
adom-digikey app --no-tab --port 8891 &  # local-browser mode
```

When `adom-digikey app` is running, these HTTP endpoints are AI-drivable (no UI clicks needed):

```bash
# run a search via HTTP, watch the UI update live
curl -X POST http://127.0.0.1:8891/search \
  -H 'Content-Type: application/json' \
  -d '{"keyword":"ESP32","limit":5,"inStockOnly":false}'

# state + cached last-search
curl http://127.0.0.1:8891/state | jq

# UI-side console logs (what the frontend JS printed)
curl http://127.0.0.1:8891/console | jq '.messages[-10:]'

# backend-health proxy (so the UI doesn't need CORS to 8777)
curl http://127.0.0.1:8891/backend-health | jq

# shutdown cleanly (removes the Hydrogen tab and exits)
curl -X POST http://127.0.0.1:8891/shutdown
```

### `adom-digikey serve`

Run the backend HTTP proxy. This is what the `service-digikey` container runs.

| Flag | Default | Description |
|---|---|---|
| `--port N` / `$DIGIKEY_PORT` | 8777 | Port |

Requires `DIGIKEY_CLIENT_ID`. Endpoints:

```
GET  /health                                  — health + live API ping
GET  /search?keyword=...&limit=10&inStockOnly=false
GET  /part?partNumber=...
POST /              {"action":"search"|"part"|"health", ...}
GET  /              (text/html landing page)
```

### `adom-digikey health`

Check reachability.

```bash
adom-digikey health                 # checks backend (or falls back to DigiKey direct)
adom-digikey health --api http://127.0.0.1:8777
```

## What's in a result

Each component in `.components[]` has:

- `mouser_pn`    — DigiKey part number, use this for BOM
- `mpn`          — manufacturer part number, use this for schematic/footprint
- `manufacturer` — manufacturer name
- `description`, `category`
- `stock`        — integer count in DigiKey's warehouse (live, 10-min cache on backend)
- `stock_text`   — raw DigiKey text ("In Stock", "Non-Stocked", etc.)
- `popularity`   — `low` / `medium` / `high` heuristic from stock
- `lead_time`    — factory lead time if ordering more
- `unit_price`   — price at qty 1
- `price_tiers`  — array of `{qty, price}` for quantity price breaks
- `min_order`, `mult` — minimum order + order multiple
- `rohs`         — compliance flag
- `lifecycle`    — New Product / Active / NRND / Obsolete
- `datasheet_url`, `product_url`, `image_url`
- `attributes`   — array of `{name, value}` from the product-attribute table

## Typical workflows

### Finding a part from scratch
```bash
adom-digikey search "32-bit ARM Cortex-M3 microcontroller LQFP-48"
# pick one, then:
adom-digikey part <digikey-pn>
```

### Confirming price for a BOM entry
```bash
adom-digikey part STM32F103RBT6 | jq '.components[0] | {mouser_pn, unit_price, price_tiers, stock}'
```

### Browsing interactively
```bash
adom-digikey app
# then type in the search box, click Product page / Datasheet, etc.
```

## Running the backend

There are two common setups.

### Dedicated `service-digikey` container (shared, has the API key)

The backend proxy runs on a dedicated `default-light` container with `DIGIKEY_CLIENT_ID` set in `/etc/environment` and a cron watchdog (`service/watchdog.sh`, every 2 min) that (a) keeps the service healthy and (b) auto-pulls `origin/main` + rebuilds when new versions land. Consumer containers point `DIGIKEY_API` at its public URL:

```
https://digikey-gjuu8l5t69uh.adom.cloud
```

`curl /health` should return `{"ok":true, "api_reachable":true, "version":"X.Y.Z", ...}`. Recover the current URL from `~/service-watcher/services.json` (`digikey` entry, `"primary": true`) if the slug has rotated. To point the CLI at it:

```bash
export DIGIKEY_API=https://digikey-gjuu8l5t69uh.adom.cloud
adom-digikey search "LM317"
adom-digikey app        # UI reads $DIGIKEY_API automatically
```

Users don't need to set `DIGIKEY_API` explicitly — `adom-digikey` is a Tier A app (see `adom-app-model`), so it's installed by every `adompkg install` run from the registry. The CLI autodetects a local `adom-digikey serve` on 127.0.0.1:8777 and falls back to calling DigiKey directly if `DIGIKEY_CLIENT_ID` is set locally.

### Local-only (quick testing)

On any container, if `DIGIKEY_CLIENT_ID` is set and you run `adom-digikey serve &`, the CLI and the app will autodetect `http://127.0.0.1:8777` and use it. This is the dev-loop path.

## Installation

The binary is distributed as a GitHub release from `adom-inc/adom-digikey`. After downloading to `/usr/local/bin/adom-digikey` and making it executable, run:

```bash
adom-digikey install
```

This deploys the skill to `~/.claude/skills/digikey/SKILL.md` and installs bash completions.

## Notes

- Price data does not include shipping or tariffs.
- Stock is live at query time (10-min cache on the backend).
- Results are sorted by DigiKey's internal relevance algorithm, not strictly by stock.
- `DIGIKEY_CLIENT_ID` is only ever needed on the backend (`serve`) side. Consumer containers just need `DIGIKEY_API` pointing at a running backend.