cec-client

List all CEC adapters

$ cec-client [[-l|--list-devices]]

$ sudo cec-client

$ sudo cec-client [[-o|--osd-name]] [name]

$ echo [on 0] | sudo cec-client [[-s|--single-command]]

$ standby [0]

$ on [0]

cec-client [options] [commands...]

-h, --help
    Displays a help message and exits.

-V, --version
    Shows the version information and exits.

-s, --scan
    Scans for available CEC adapters and devices on the bus.

-l, --list
    Lists all connected CEC devices and their logical addresses.

-d, --device
    Specifies the CEC adapter to use (e.g., 'RPI', 'Pulse8').

-p, --port
    Sets the serial port for USB CEC adapters (e.g., /dev/ttyACM0).

-t, --test
    Enters test mode, often used for sending raw commands or advanced debugging.

-r, --monitor-only
    Starts the client in monitor-only mode, showing all received CEC messages without sending any.

-m, --monitor
    Starts the client in monitor mode, allowing interactive command input while continuously monitoring CEC traffic.

-f, --force-open
    Forces the opening of the CEC adapter, even if it's reported as already in use.

-o, --osd-name
    Sets the On-Screen Display (OSD) name for this CEC client, visible to other CEC devices.

-P, --physical-address
    Manually sets the physical address of the client (e.g., 1.0.0.0 for HDMI port 1).

-L, --logical-address
    Specifies the logical address for the client (e.g., 0 for TV, 4 for Playback device).

-D, --daemon
    Runs the client as a daemon in the background, continuously processing commands or monitoring.

-v, --verbose
    Increases the verbosity level of output for debugging and detailed message logging.

-e, --event-timeout
    Sets a timeout for event processing in milliseconds.

-c, --cec-config
    Loads CEC configuration from a specified file instead of using default settings.

-T, --terminal
    Forces terminal interaction, even when stdout is not a TTY.

-i, --input-source
    Specifies the HDMI input port for commands like 'activate source'.

-U, --rc-command
    Sends a remote control command (e.g., 'power', 'menu', 'volume up') to a device.

-S, --standby-timeout
    Sets a timeout after which the device automatically enters standby if inactive.

-N, --no-wait
    Prevents waiting for a reply to a sent CEC command, useful for fire-and-forget scenarios.

-C, --connection-timeout
    Sets a timeout for establishing a connection to the CEC adapter.

-Z, --command
    Executes a single CEC command string non-interactively and then exits.

-j, --json
    Outputs results in JSON format, suitable for programmatic parsing (requires newer `libCEC` versions).

`cec-client` is a versatile command-line utility for interacting with devices connected via HDMI Consumer Electronics Control (CEC). It allows users to send various CEC commands to control compliant devices, such as TVs, Blu-ray players, and AV receivers, directly from the terminal. This tool is often used on systems like the Raspberry Pi, which typically have CEC support built into their HDMI hardware. Its functionalities include scanning for active CEC devices, turning devices on or off, switching HDMI inputs, and monitoring CEC traffic for debugging purposes. `cec-client` acts as an interface to the underlying libCEC library, providing a powerful way to automate home entertainment systems or troubleshoot CEC communication issues.

Requires compatible hardware with HDMI CEC support, such as a Raspberry Pi or a dedicated USB CEC adapter (e.g., Pulse-Eight CEC adapter).
CEC implementations can vary significantly between device manufacturers, leading to inconsistent behavior or compatibility issues across different brands.
Accessing the CEC device often requires appropriate user permissions, sometimes necessitating `sudo` or being part of a specific user group (e.g., `dialout`).
The `cec-client` command might not be present by default and may need to be installed via your distribution's package manager (e.g., `apt install cec-utils` on Debian/Ubuntu).

When run without a specific command (e.g., just `cec-client`), it enters an interactive prompt where users can type CEC commands directly. Common commands include:
on

`cec-client` is frequently used in shell scripts for home automation. For example, to turn on a TV when a media center starts, a script might execute:
`echo 'on 0' | cec-client -s -d 1`
(where '0' is the TV's logical address and '-d 1' selects the first adapter). The -Z/--command option provides a more direct way to execute single commands non-interactively, making it ideal for scripting:
`cec-client -s -d 1 -Z 'on 0'`

The `cec-client` utility has its roots in the libCEC library, developed primarily by Pulse-Eight. It gained significant traction with the rise of embedded systems like the Raspberry Pi, where it became a standard tool for enabling seamless integration of the mini-computer with HDMI-connected displays and other home theater equipment. Its development has focused on providing a robust command-line interface to the underlying CEC capabilities, evolving to support various CEC adapters and providing increasingly detailed control over CEC communication.

cec-ctl(1), tvservice(1), udev(7)