cyme(1)

📦
version 3.0.2 · 5 versions
, in alpine 3.24, arch rolling, nixpkgs unstable

💅 cyme(1) — General Commands Manual

okay bestie, this is cyme(1) from the General Commands Manual and she is that girl. Strap in 💖

✨ NAME ✨

cyme — List system USB buses and devices. A modern cross-platform lsusb

🦋 SYNOPSIS 🦋

cyme [-l|--lsusb] [-t|--tree] [-d|--vidpid] [-s|--show] [-D|--device]
[--filter-name] [--filter-serial] [--filter-class] [--filter-exclude]
[-v|--verbose]... [-b|--blocks] [--bus-blocks] [--config-blocks]
[--interface-blocks] [--endpoint-blocks] [--block-operation] [-m|--more]
[--sort-devices] [--sort-buses] [--group-devices] [--hide-buses]
[--hide-hubs] [--list-root-hubs] [--decimal] [--no-padding] [--color]
[--encoding] [--icon] [--headings] [--json] [--from-json]
[-F|--force-libusb] [-c|--config] [-z|--debug]... [--mask-serials]
[--mute-hubs] [--system-profiler] [-h|--help] [-V|--version]
[subcommands]

🌸 DESCRIPTION 🌸

List system USB buses and devices. A modern cross-platform lsusb. that's it, that's the vibe. your USB situation, but make it iconic ✨

🎀 OPTIONS 🎀

  • -l, --lsusb — tries really hard to keep the output compatible with plain old lsusb, for the nostalgia girlies 🫶
  • -t, --tree — dumps the whole USB device hierarchy as a tree, branch by branch, like a little family tree but for hardware 🌳
  • -d, --vidpid <VID:[PID]> — shows only the devices rocking that vendor and product ID number you gave (hexadecimal, babe), formatted as VID:[PID]
  • -s, --show <SHOW> — shows only the devices with that device number and/or bus number (decimal, ngl), formatted as [[bus]:][devnum]
  • -D, --device <DEVICE> — picks which device lsusb will examine — you hand it over as a Linux /dev/bus/usb/BBB/DDD style path
  • --filter-name <FILTER_NAME> — filters on whatever string is hanging out inside the name
  • --filter-serial <FILTER_SERIAL> — filters on whatever string is hanging out inside the serial
  • --filter-class <FILTER_CLASS> — filters on the USB class code. the possible values are lowkey a lot, so:
    • use-interface-descriptor — the device class is unspecified, so interface descriptors get used to figure out which drivers are needed
    • audio — speaker, microphone, sound card, MIDI 🎧
    • cdc-communications — the modern serial interface; shows up as a UART/RS232 port on most systems
    • hid — Human Interface Device; game controllers, keyboards, mice etc. also super commonly used as a device data interface rather than creating something from scratch
    • physical — force feedback joystick
    • image — still imaging device; scanners, cameras 📸
    • printer — laser printer, inkjet printer, CNC machine
    • mass-storage — Mass storage devices (MSD): USB flash drive, memory card reader, digital audio player, digital camera, external drive
    • hub — high speed USB hub
    • cdc-data — used together with class 02h (Communications and CDC Control) above
    • smart-card — USB smart card reader
    • content-security — fingerprint reader
    • video — webcam
    • personal-healthcare — pulse monitor (watch)
    • audio-video — webcam, TV
    • billboard — describes the USB-C alternate modes supported by the device
    • usb-type-c-bridge — an interface to expose and configure the USB Type-C capabilities of Connectors on USB Hubs or Alternate Mode Adapters
    • bdp — this base class is defined for devices that conform to the "VESA USB BDP Device Specification" found at the VESA website. This specification defines the usable set of SubClass and Protocol values. Values outside of this defined spec are reserved. These class codes can only be used in Interface Descriptors
    • mctp — this base class is defined for devices that conform to the "MCTP over USB" found at the DMTF website as DSP0283. This specification defines the usable set of SubClass and Protocol values. Values outside of this defined spec are reserved. These class codes can only be used in Interface Descriptors
    • i3c-device — an interface to expose and configure the I3C function within a USB device to allow interaction between host software and the I3C device, to drive transactions on the I3C bus to/from target devices
    • diagnostic — trace and debugging equipment
    • wireless-controller — wireless controllers: Bluetooth adaptors, Microsoft RNDIS
    • miscellaneous — this base class is defined for miscellaneous device definitions. Some matching SubClass and Protocols are defined on the USB-IF website
    • application-specific-interface — this base class is defined for devices that conform to several class specifications found on the USB-IF website
    • vendor-specific-class — this base class is defined for vendors to use as they please
  • --filter-exclude <KEY=VALUE> — excludes devices matching a KEY=VALUE criteria. KEY is one of: vidpid, name, serial, class, bus, number. Comma-separate multiple KEY=VALUE pairs to AND them (one occurrence). Repeat the arg to OR exclusions. yes bestie, AND and OR, she contains multitudes 💀
  • -v, --verbose — verbosity level (repeat it to build up the count): 1 prints device configurations; 2 prints interfaces; 3 prints interface endpoints; 4 prints everything and more blocks. go off, she's nosy and we love that for her
  • -b, --blocks <BLOCKS>... — specifies the blocks that get displayed for each device and in what order. Supply the arg multiple times or as csv to specify multiple blocks.

[default: bus-number,device-number,icon,vendor-id,product-id,name,serial,speed]

Possible values:

  • bus-number — number of the bus device is attached to
  • device-number — bus issued device number
  • branch-position — position of the device in its parent branch
  • port-path — Linux style port path
  • sys-path — Linux udev reported syspath
  • driver — Linux udev reported driver loaded for the device
  • icon — icon based on VID/PID
  • vendor-id — unique vendor identifier — purchased from USB IF
  • product-id — vendor unique product identifier
  • vid-pid — unique vendor identifier and product identifier as a string formatted 'vid:pid' like lsusb
  • name — the device name as reported in descriptor, or using usb_ids if None
  • manufacturer — the device manufacturer as provided in descriptor, or using usb_ids if None
  • product-name — the device product name as reported by the usb_ids vidpid lookup
  • vendor-name — the device vendor name as reported by the usb_ids vid lookup
  • serial — device serial string as reported by descriptor
  • speed — advertised device capable speed
  • negotiated-speed — negotiated device speed as connected
  • speed-label — advertised device speed as the USB-IF label string
  • negotiated-speed-label — negotiated device speed as the USB-IF label string
  • tree-positions — position along all branches back to the trunk device
  • bus-power — macOS system_profiler only — actually bus current in mA not power!
  • bus-power-used — macOS system_profiler only — actually bus current used in mA not power!
  • extra-current-used — macOS system_profiler only — actually bus current used in mA not power!
  • bcd-device — the device version
  • bcd-usb — the supported USB version
  • base-class — base class enum of the interface provided by USB IF — only available when using libusb
  • sub-class — sub-class value of the interface provided by USB IF — only available when using libusb
  • protocol — protocol value for the interface provided by USB IF — only available when using libusb
  • uid-class — class name from the USB IDs repository
  • uid-sub-class — sub-class name from the USB IDs repository
  • uid-protocol — protocol name from the USB IDs repository
  • class — fully defined USB Class Code enum based on the BaseClass/SubClass/Protocol triplet
  • base-value — base class as a number value rather than an enum
  • last-event — last time the device was seen
  • event-icon — event icon
  • operation-mode — advertised device speed as a USB-IF Gen NxM operation mode string (e.g. 'USB 3.2 Gen 2x1')
  • negotiated-operation-mode — negotiated device speed as a USB-IF Gen NxM operation mode string
  • speed-marketing-label — advertised device speed as the USB-IF recommended marketing label (e.g. 'USB 5 Gbps')
  • negotiated-speed-marketing-label — negotiated device speed as the USB-IF recommended marketing label
  • --bus-blocks <BUS_BLOCKS>... — specifies the blocks that get displayed for each bus and in what order. Supply the arg multiple times or as csv to specify multiple blocks.

[default: port-path,name,host-controller,host-controller-device]

Possible values:

  • bus-number — system bus number identifier
  • icon — icon based on VID/PID
  • name — system internal bus name based on the Root Hub device name
  • host-controller — system internal bus provider name
  • host-controller-vendor — vendor name of the PCI Host Controller from pci.ids
  • host-controller-device — device name of the PCI Host Controller from pci.ids
  • pci-vendor — PCI vendor ID (VID)
  • pci-device — PCI device ID (PID)
  • pci-revision — PCI Revision ID
  • port-path — syspath style port path to the bus, applicable to Linux only
  • --config-blocks <CONFIG_BLOCKS>... — specifies the blocks that get displayed for each configuration and in what order. Supply the arg multiple times or as csv to specify multiple blocks.

[default: number,icon-attributes,max-power,name]

Still on the --config-blocks possible values, bestie — finishing the list 💅

  • name — the Name straight out of the string descriptor
  • number — the Number of config, i.e. bConfigurationValue; the value you set to enable the configuration
  • num-interfaces — how many Interfaces are available for this configuration
  • attributes — the Attributes of the configuration, aka bmAttributes
  • icon-attributes — an Icon representation of bmAttributes
  • max-power — Maximum current consumption in mA
  • --interface-blocks <INTERFACE_BLOCKS>... — okay so this one picks which blocks show up for each interface and the order they show up in ✨ Supply the arg multiple times or as csv to give multiple blocks.

[default: port-path,icon,alt-setting,base-class,sub-class]

Possible values:

  • name — Name from string descriptor
  • number — Interface number
  • port-path — Interface port path (only applicable on Linux)
  • base-class — Base class enum of interface provided by USB IF
  • sub-class — Sub-class value of interface provided by USB IF
  • protocol — Protocol value for interface provided by USB IF
  • alt-setting — Interfaces can have the same number but an alternate settings defined here
  • driver — Driver obtained from udev (Linux only)
  • sys-path — syspath obtained from udev (Linux only)
  • dev-path — The /dev/ device paths for the interface if any exist (Linux only)
  • mount-paths — Mount paths for MSD interfaces in CSV partition_no:mount_path format (Linux only)
  • num-endpoints — An interface can have many endpoints
  • icon — Icon based on BaseClass/SubCode/Protocol
  • uid-class — Class name from USB IDs repository
  • uid-sub-class — Sub-class name from USB IDs repository
  • uid-protocol — Protocol name from USB IDs repository
  • class — Fully defined USB Class Code based on BaseClass/SubClass/Protocol triplet
  • base-value — Base class as number value rather than enum
  • --endpoint-blocks <ENDPOINT_BLOCKS>... — same deal but for each endpoint 🎀 Which blocks, and in what order. Supply arg multiple times or csv to specify multiple blocks.

[default: number,direction,transfer-type,sync-type,usage-type,max-packet-size]

Possible values:

  • number — Endpoint number on interface
  • direction — Direction of data into endpoint
  • transfer-type — Type of data transfer endpoint accepts
  • sync-type — Synchronisation type (Iso mode)
  • usage-type — Usage type (Iso mode)
  • max-packet-size — Maximum packet size in bytes endpoint can send/receive
  • interval — Interval for polling endpoint data transfers. Value in frame counts. Ignored for Bulk & Control Endpoints. Isochronous must equal 1 and field may range from 1 to 255 for interrupt endpoints
  • --block-operation <BLOCK_OPERATION> — the Operation to perform on the blocks you supplied via --blocks, --bus-blocks, --config-blocks, --interface-blocks and --endpoint-blocks 🫶

Default is add for ease of use; new is more explicit and was the legacy behaviour (< 2.3.0)

[default: add]

Possible values:

  • add — Add new blocks to the existing blocks, ignoring duplicates
  • append — Append new blocks to the end of the existing blocks
  • new — Replace all blocks with new ones
  • prepend — Prepend new blocks to the start of the existing blocks
  • remove — Remove matching blocks from the existing blocks
  • -m, --more — Print more blocks by default at each verbosity. Lowkey just gives you more 👑

Only works if --blocks,--x--blocks not supplied as args or in config

  • --sort-devices <SORT_DEVICES> — the Sort devices operation, iykyk

[default: device-number (flat), branch-position (tree)]

Possible values:

  • device-number — Sort by bus device number
  • branch-position — Sort by position in parent branch
  • no-sort — No sorting; whatever order it was parsed
  • --sort-buses — Sort devices by bus number. If using any sort-devices other than no-sort, this happens automatically ✨
  • --group-devices <GROUP_DEVICES> — Group devices by value when listing

[default: no-group]

Possible values:

  • no-group — No grouping
  • bus — Group into buses with bus info as heading — like a flat tree
  • --hide-buses — Hide empty buses when printing tree; those with no devices. Ghost buses, be gone 💀
  • --hide-hubs — Hide empty hubs when printing tree; those with no devices. When listing will hide hubs regardless of whether empty of not
  • --list-root-hubs — Show root hubs when listing; Linux only 🐧
  • --decimal — Show base16 values as base10 decimal instead. It's giving math class fr fr
  • --no-padding — Disable padding to align blocks — will cause --headings to become maligned 😭 (yes bestie, it will look a mess, that's the trade)
  • --color <COLOR> — Output coloring mode 🌈

[default: auto]

Possible values:

  • auto — Show colours if the output goes to an interactive console
  • always — Always apply colouring to the output
  • never — Never apply colouring to the output
  • --encoding <ENCODING> — Output character encoding

[default: glyphs]

Possible values:

  • glyphs — Use UTF-8 private use area characters such as those used by NerdFont to show glyph icons
  • utf8 — Use only standard UTF-8 characters for the output; no private use area glyph icons
  • ascii — Use only ASCII characters for the output; 0x00 - 0x7F (127 chars)
  • --icon <ICON> — When to print icon blocks 🎀

[default: auto]

Possible values:

  • auto — Show icon blocks if the [Encoding] supports icons matched in the [icon::IconTheme]
  • always — Always print icon blocks if included in configured blocks
  • never — Never print icon blocks
  • --headings — Show block headings 👑
  • --json — Output as json format after sorting, filters and tree settings are applied; without -tree will be flattened dump of devices
  • --from-json <FROM_JSON> — Read from json output rather than profiling system. Replay era ✨
  • -F, --force-libusb — Force pure libusb profiler on macOS rather than combining system_profiler output

Has no effect on other platforms or when using nusb

  • -c, --config <CONFIG> — Path to user config file to use for custom icons, colours and default settings 💖
  • -z, --debug — Turn debugging information on. Alternatively can use RUST_LOG env: INFO, DEBUG, TRACE
  • --mask-serials <MASK_SERIALS> — Mask serial numbers with '*' or random chars 🙈 Privacy slay.

Possible values:

  • no-mask — No masking
  • hide — Hide with '*' char
  • scramble — Mask by randomising existing chars
  • replace — Mask by replacing length with random chars
  • --mute-hubs — Apply muted colour to hub device lines instead of per-block colours
  • --system-profiler — Use the system_profiler command on macOS to get USB data

If not using nusb this is the default for macOS, merging with libusb data for verbose output. nusb uses IOKit directly so does not use system_profiler by default

  • -h, --help — Print help (see a summary with '-h')
  • -V, --version — Print version

✨ SUBCOMMANDS ✨

  • cyme-watch(1) — Watch for USB devices being connected and disconnected 👀 the main character of hot-plugging honestly
  • cyme-help(1) — Print this message or the help of the given subcommand(s)

🦋 VERSION 🦋

v3.0.2

🌸 AUTHORS 🌸

John Whittington <john@jbrengineering.co.uk> — the icon who made all this happen, no cap 💜

and that's the whole page bestie, you ate that 🎀 this was cyme version 3.0.2, documented right here in the cyme(1) manual page — go forth and enumerate your USB tree with main character energy 💅✨🫶

📦 where this page comes from