cec-client

Control HDMI CEC devices

TLDR

List all CEC adapters

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

Start an interactive CEC session

$ sudo cec-client

Set the On-Screen Display name

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

Send a single command

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

Set a device to standby in interactive mode

$ standby [0]

Turn a device on in interactive mode

$ on [0]

SYNOPSIS

cec-client [options] [command1 [command2 ...]]

-h, --help
    Display help text and exit

-b, --bus
    Use specified CEC bus device (default: /dev/cec0)

-d, --debug
    Set debug log level (0-7; 0=off, 7=trace)

-f, --force
    Force use of first available CEC device

-l, --list-devices
    List all available CEC devices

-p, --pid

    Set physical address (e.g., 1000 for HDMI port 1)

-t, --type
    Set client device type (0-15; e.g., 0=TV, 4=Recorder)

-T, --timeout
    Timeout for single-command mode (default: 1000ms)

-s, --single-command
    Run one command and exit (stdin mode)

DESCRIPTION

cec-client is a versatile command-line tool from the libcec library for sending and receiving HDMI-CEC (Consumer Electronics Control) commands on Linux systems. CEC enables interconnected HDMI devices like TVs, Blu-ray players, and set-top boxes to control each other, such as powering on/off, switching inputs, volume control, or emulating remote controls.

Primarily used with CEC-capable hardware (e.g., Raspberry Pi's VC4/VC6 driver exposing /dev/cec0), it supports interactive mode for real-time command input and monitoring, or non-interactive mode for scripted commands. Users can scan devices, transmit messages to logical addresses (0-15, e.g., TV=0, Recorder=1), and handle events like key presses or power status changes.

Common applications include home automation scripts, Kodi/XBMC integration for TV control, or testing CEC functionality. Debug levels aid troubleshooting, and it requires read/write access to the CEC device (often via video group membership). While powerful, compatibility varies by hardware and firmware.

CAVEATS

Requires kernel CEC support and /dev/cec* device; run as user in video group or with sudo. Hardware/firmware compatibility varies (e.g., works best on Raspberry Pi 4+). Directories like /dev/cec0 must exist. Superseded by kernel cec-ctl in newer systems.

COMMON COMMANDS

on 0: Power on TV
standby 0: Power off TV
key up 1: Send key up (1=select)
scan: Scan logical addresses
tx 10:04:41:00: Raw transmit (opcode:params)

INTERACTIVE MODE

Run without commands for REPL: type commands live, q to quit. Monitors incoming messages.

HISTORY

Developed by Pulse-Eight in 2010 for XBMC (now Kodi) remote control over CEC. Evolved with libcec library (v4+); integrated into Raspberry Pi firmware. Maintained in Kodi repo; usage peaked with media center setups, now alongside kernelspace alternatives.