cyme(1)

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]

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

OPTIONS

-l, --lsusb
    Attempt to maintain compatibility with lsusb output

-t, --tree
    Dump USB device hierarchy as a tree

-d, --vidpid <VID:[PID]>
    Show only devices with the specified vendor and product ID numbers (in hexadecimal) in format VID:[PID]

-s, --show <SHOW>
    Show only devices with specified device and/or bus numbers (in decimal) in format [[bus]:][devnum]

-D, --device <DEVICE>
    Selects which device lsusb will examine - supplied as Linux /dev/bus/usb/BBB/DDD style path

--filter-name <FILTER_NAME>
    Filter on string contained in name

--filter-serial <FILTER_SERIAL>
    Filter on string contained in serial

--filter-class <FILTER_CLASS>
    Filter on USB class code

    Possible values:

    •   use-interface-descriptor: Device class is unspecified, interface descriptors are used to determine needed drivers

    •   audio: Speaker, microphone, sound card, MIDI

    •   cdc-communications: The modern serial interface; appears as a UART/RS232 port on most systems

    •   hid: Human Interface Device; game controllers, keyboards, mice etc. Also commonly used as a device data interface rather then 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 USB-C alternate modes supported by 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 I3C function within a USB device to allow interaction between host software and the I3C device, to drive transaction 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>
    Exclude devices matching 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

-v, --verbose
    Verbosity level (repeat provides count): 1 prints device configurations; 2 prints interfaces; 3 prints interface endpoints; 4 prints everything and more blocks

-b, --blocks <BLOCKS>...
    Specify the blocks which will be displayed for each device and in what order. Supply arg multiple times or csv to specify multiple blocks.

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

    Possible values:

    •   bus-number: Number of bus device is attached

    •   device-number: Bus issued device number

    •   branch-position: Position of device in parent branch

    •   port-path: Linux style port path

    •   sys-path: Linux udev reported syspath

    •   driver: Linux udev reported driver loaded for 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 usb_ids vidpid lookup

    •   vendor-name: The device vendor name as reported by 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 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 interface provided by USB IF - only available when using libusb

    •   sub-class: Sub-class value of interface provided by USB IF - only available when using libusb

    •   protocol: Prototol value for interface provided by USB IF - only available when using libusb

    •   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 enum based on BaseClass/SubClass/Protocol triplet

    •   base-value: Base class as number value rather than enum

    •   last-event: Last time device was seen

    •   event-icon: Event icon

    •   operation-mode: Advertised device speed as USB-IF Gen NxM operation mode string (e.g. 'USB 3.2 Gen 2x1')

    •   negotiated-operation-mode: Negotiated device speed as USB-IF Gen NxM operation mode string

    •   speed-marketing-label: Advertised device speed as USB-IF recommended marketing label (e.g. 'USB 5 Gbps')

    •   negotiated-speed-marketing-label: Negotiated device speed as USB-IF recommended marketing label

--bus-blocks <BUS_BLOCKS>...
    Specify the blocks which will be displayed for each bus and in what order. Supply arg multiple times or 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 Root Hub device name

    •   host-controller: System internal bus provider name

    •   host-controller-vendor: Vendor name of PCI Host Controller from pci.ids

    •   host-controller-device: Device name of PCI Host Controller from pci.ids

    •   pci-vendor: PCI vendor ID (VID)

    •   pci-device: PCI device ID (PID)

    •   pci-revision: PCI Revsision ID

    •   port-path: syspath style port path to bus, applicable to Linux only

--config-blocks <CONFIG_BLOCKS>...
    Specify the blocks which will be displayed for each configuration and in what order. Supply arg multiple times or csv to specify multiple blocks.

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

    Possible values:

    •   name: Name from string descriptor

    •   number: Number of config, bConfigurationValue; value to set to enable to configuration

    •   num-interfaces: Interfaces available for this configuruation

    •   attributes: Attributes of configuration, bmAttributes

    •   icon-attributes: Icon representation of bmAttributes

    •   max-power: Maximum current consumption in mA

--interface-blocks <INTERFACE_BLOCKS>...
    Specify the blocks which will be displayed for each interface and in what order. Supply arg multiple times or csv to specify 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: Prototol 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>...
    Specify the blocks which will be displayed for each endpoint 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>
    Operation to perform on the blocks 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 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

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

--sort-devices <SORT_DEVICES>
    Sort devices operation

    [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

--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

--no-padding
    Disable padding to align blocks - will cause --headings to become maligned

--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

-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

    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

VERSION
v3.0.1

AUTHORS
John Whittington <john@jbrengineering.co.uk>