shstatus manual

NAME

shstatus - a simple statusline generator for i3bar and swaybar

SYNOPSIS

shstatus [-h | --help] [-v | --version] [path/to/config.sh]

OPTIONS

-h, --help: Print a help message.

-v, --version: Print version information.

USAGE

To use shstatus in your statusbar, add this to your i3 or sway config file:

bar {
    status_command shstatus
}

CONFIGURATION

shstatus looks for configuration files in the following order:: 1. $XDG_CONFIG_HOME/shstatus/config.sh

2. $HOME/.config/shstatus/config.sh

3. /etc/shstatus/config.sh

Specifying an alternate config file overrides the default paths.

In the config file, you have to define:

1. A variable 'interval'

2. An array 'blocks'

Every element in the blocks array must be a function name. All of these functions should be defined in your config.sh. Each function must set the full_text variable - this is the text that will be displayed in the status bar. There are a lot more variables available - see swaybar-protocol(7) or https://i3wm.org/docs/i3bar-protocol.html for the full list. shstatus will run all functions in the specified order, and then print all set variables as JSON in order to display the information in the bar. This is done every interval seconds.

Inside the config, you can use some of the functions provided by shstatus to insert information into full_text and short_text. These functions replace variables (denoted %var_name) inside the bash variables full_text and short_text with some information. For example, %date will be replaced with the current date and time if you run 'block_datetime "%c" "printf"' in your function.
See the next section for a detailed description of every function.

There is an example config file in /etc/shstatus/config.sh. It contains usage examples of every block function. Copy it to your home directory and edit it from there.

BLOCK FUNCTIONS

block_datetime <date-formatstring> <program>: Shows the date and time.

<program> can be either 'printf' or 'date'. See strftime(3) for how to use printf, or date(1) for how to use date.

Available variables:
%date - current date

block_pwvol <pipewire-sink> <mute-string>: Shows the current volume. This is done using wpctl.

Available variables:
%vol - current volume
%mutestatus - if volume is muted, this variable contains <mute-string>. Otherwise it is empty.

block_pavol <pulseaudio-sink> <mute-string>: Same as block_pwvol, but for pulseaudio (using pactl(1)).

block_disk <device or mountpoint>: Shows disk usage. This is done using df(1).

Available variables:
%disk - device
%size - disk size
%used - used disk space
%avail - available disk space
%usepercent - percentage of used disk space
%mountpoint - device mountpoint

block_mem: Shows memory and swap usage. This is done using free(1).

Available variables:
%memtotal - total memory
%memused - used memory
%memavail - available memory
%swaptotal - total swap
%swapused - used swap
%swapavail - available swap

block_uptime <label_days> <label_hours> <label_minutes> <label_seconds> <separator>: Shows the uptime. This is done by reading /proc/uptime. If <label_seconds> is set to DISABLE, the number of seconds will not be shown.

Available variables:
%uptime - system uptime in the following format: <number><label><separator><number><label> ...

block_cpu: Shows the CPU usage. This is done by reading /proc/stat.

Available variables:
%usage - CPU usage

block_loadavg: Shows the load average. This is done by reading /proc/loadavg.

Available variables:
%load1 - load average during the last 1 minute
%load5 - load average during the last 5 minutes
%load15 - load average during the last 15 minutes

block_battery <battery-name> <charging-label> <discharging-label> <full-label>: Shows battery information. This is done by reading the files in /sys/class/power_supply.

To list available batteries, run 'ls /sys/class/power_supply'

Available variables:
%percentage - battery percentage
%status - depending on the current battery status, this contains either <charging-label>, <discharging-label> or <full-label>.