lsusd 1.1.0

List USB serial devices with their associated USB metadata

lsusd — List USB Serial Devices

A zero-dependency command-line tool that maps USB serial device nodes to their USB metadata (vendor, product, serial number, VID:PID).

Example Output

❯ lsusd
┌────────────────────────────────┬────────────────────────────┬──────────────────┬───────────────────┬───────────┐
│          Device Node           │        USB Product         │    USB Vendor    │     USB Serial    │  VID:PID  │
├────────────────────────────────┼────────────────────────────┼──────────────────┼───────────────────┼───────────┤
│ /dev/cu.usbmodem2121101        │ USB JTAG/serial debug unit │ Espressif        │ D8:3B:DA:70:69:7C │ 303A:1001 │
├────────────────────────────────┼────────────────────────────┼──────────────────┼───────────────────┼───────────┤
│ /dev/cu.usbmodemF078E4E385A03  │ Flexbar                    │ ENIAC            │ F078E4E385A0      │ 303A:82BF │
├────────────────────────────────┼────────────────────────────┼──────────────────┼───────────────────┼───────────┤
│ /dev/cu.usbserial-113010893810 │ OBDLink SX                 │ ScanTool.net LLC │ 113010893810      │ 0403:6015 │
├────────────────────────────────┼────────────────────────────┼──────────────────┼───────────────────┼───────────┤
│ /dev/cu.usbserial-ST8XVRNW     │ ElmScan 5 Compact          │ ScanTool.net LLC │ ST8XVRNW          │ 0403:6001 │
└────────────────────────────────┴────────────────────────────┴──────────────────┴───────────────────┴───────────┘

Installation

pip / pipx

pip install lsusd
# or
pipx install lsusd

Homebrew

brew tap mickeyl/formulae
brew install lsusd

From source

pip install -e .

Usage

lsusd
# or
python -m lsusd

Options

Flag	Description
-p, --plain	Tab-separated output, no headers — suitable for cut, awk, etc.
-c, --csv	CSV output with header row
-j, --json	JSON array output, or JSON Lines in watch mode
-n, --no-spinner	Disable the progress spinner
-w, --watch	Watch USB serial devices in a live table
--version	Print version and exit

Watch Mode

lsusd --watch
lsusd --watch --plain
lsusd --watch --json

--watch shows a live terminal table of connected USB serial devices and redraws it after add/remove events. The machine-readable formats still emit event streams: --plain and --csv use the columns action, device, product, vendor, serial, and vidpid; --json emits newline-delimited JSON objects. Initial devices use action present.

❯ lsusd --watch
lsusd watch  4 USB serial device(s)  2026-05-01T14:22:09
Press Ctrl-C to stop.

┌───────────────────────────────┬────────────────────────────┬────────────┬───────────────────┬───────────┐
│          Device Node          │        USB Product         │ USB Vendor │     USB Serial    │  VID:PID  │
├───────────────────────────────┼────────────────────────────┼────────────┼───────────────────┼───────────┤
│ /dev/cu.usbmodem2121101       │ USB JTAG/serial debug unit │ Espressif  │ D8:3B:DA:70:69:7C │ 303A:1001 │
└───────────────────────────────┴────────────────────────────┴────────────┴───────────────────┴───────────┘

The watch implementation is push-driven, not a polling loop. On macOS, lsusd subscribes to IOKit IOSerialBSDClient first-match and termination notifications. On Linux, lsusd listens to kernel uevents through the netlink socket. After an event arrives, lsusd takes a fresh snapshot only to compute the added or removed device rows.

Supported Platforms

• macOS — discovers devices via ioreg (/dev/cu.usbmodem*, /dev/cu.usbserial*)
• Linux — discovers devices via sysfs (any tty with a USB ancestor, including devices renamed via udev)

License

MIT