cbatticon

Show the battery icon in the system tray

$ cbatticon

$ cbatticon [[-u|--update-interval]] [20]

$ cbatticon [[-t|--list-icon-types]]

$ cbatticon [[-i|--icon-type]] [standard|notification|symbolic]

$ cbatticon [[-p|--list-power-supplies]]

$ cbatticon [BAT0]

$ cbatticon [[-r|--critical-level]] [5] [[-c|--command-critical-level]] [poweroff]

cbatticon [-c] [-d] [-f format] [-t low:high] [-p] [-u]

-c
    Displays the charging icon when the battery is currently charging.

-d
    Displays the discharging icon when the battery is currently discharging.

-f format
    Specifies a custom output format string. This string can contain placeholders for battery percentage, various icons, and other status information. The exact placeholders depend on the specific cbatticon version.

-t low:high
    Sets battery percentage thresholds for changing icon representations. For example, '20:80' might mean one icon below 20%, another between 20-80%, and a third above 80%.

-p
    Displays the battery percentage alongside the icon or as the primary output, depending on other options and default behavior.

-u
    Displays an 'unknown' or 'full' icon when the battery status is not clearly charging or discharging, or when fully charged and not connected to power.

cbatticon is a lightweight and minimalist utility designed to display current battery status. It is predominantly used within window managers such as dwm to provide a compact visual representation of battery charge, often integrated directly into the status bar. The command typically outputs a string comprising an icon (indicating charging, discharging, or full) and/or the percentage of remaining battery life. It retrieves battery information directly from the system's power supply interface, usually through the /sys/class/power_supply/ directory. Its design philosophy emphasizes simplicity and efficiency, making it an ideal choice for users seeking a clean and unobtrusive battery indicator without the overhead of more complex graphical tools.

The exact behavior and available options of cbatticon can vary significantly between different versions or user-compiled instances, as it is often patched or customized by users of suckless tools. Users should consult their specific installation's documentation or source code for precise details. It primarily relies on battery information exposed through the /sys/class/power_supply/ interface; systems that do not expose this information or use a different mechanism may not be compatible.

cbatticon is not a standalone graphical application. Instead, it is typically used in conjunction with status bar utilities (like xsetroot or direct manipulation of /proc/self/fd/0 in dwm's status bar scripts) to periodically update and display battery information. Users often write small shell scripts that call cbatticon, format its output, and then push that output to their status bar. An example of such a script snippet might be:

while true; do
  xsetroot -name "$(cbatticon -p)"
  sleep 60
done

cbatticon emerges from the suckless.org community, known for developing minimalist and highly customizable software like dwm and st. Its development aligns with the suckless philosophy of creating simple, efficient, and single-purpose tools that do one thing well. It's not a standalone project with a long release history but rather a small utility often included or adapted as a patch within users' dwm configurations. Its history is therefore less about formal releases and more about community contribution and adaptation to specific user needs within the suckless ecosystem.

acpi(1), upower(7), dwm(1)