i3status-rs(1) General Commands Manual i3status-rs(1) NAME i3status-rs - A feature-rich and resource-friendly replacement for i3status, written in Rust. SYNOPSIS i3status-rs [--never-pause] [-j|--threads] [-h|--help] [-V|--version] [CONFIG] DESCRIPTION A feature-rich and resource-friendly replacement for i3status(1), written in Rust. The i3status-rs program writes a stream of configurable "blocks" of system information (time, battery status, volume, etc.) to standard output in the JSON format understood by i3bar(1) and sway-bar(5). OPTIONS --never-pause Ignore any attempts by i3 to pause the bar when hidden/fullscreen -j, --threads=BLOCKING_THREADS [default: 2] The maximum number of blocking threads spawned by tokio -h, --help Print help (see a summary with '-h') -V, --version Print version [CONFIG] [default: config.toml] Sets a TOML config file 1. If full absolute path given, then use it as is: `/home/foo/i3rs-config.toml` 2. If filename given, e.g. "custom_theme.toml", then first look in `$XDG_CONFIG_HOME/i3status-rust` 3. Then look for it in `$XDG_DATA_HOME/i3status-rust` 4. Otherwise look for it in `/usr/share/i3status-rust` BLOCKS amd_gpu Display the stats of your AMD GPU Configuration Key Values Default ----------------------------------------------------------------------------- device The device in Any AMD card /sys/class/drm/ to read from. format A string to customise the " $icon $utilization " output of this block. See below for available placeholders. format_alt If set, block will switch None between format and format_alt on every click interval Update interval in seconds 5 Placeholder Value Type Unit -------------------------------------------------------------------------------- icon A static icon Icon - utilization GPU utilization Number % vram_total Total VRAM Number Bytes vram_used Used VRAM Number Bytes vram_used_percents Used VRAM / Total VRAM Number % Action Description Default button ----------------------------------------------------------------------------- toggle_format Toggles between format and format_alt Left Example [[block]] block = "amd_gpu" format = " $icon $utilization " format_alt = " $icon MEM: $vram_used_percents ($vram_used/$vram_total) " interval = 1 Icons Used o gpu apt Pending updates available for your Debian/Ubuntu based system Behind the scenes this uses apt, and in order to run it without root privileges i3status-rust will create its own package database in /tmp/i3rs-apt/ which may take up several MB or more. If you have a custom apt config then this block may not work as expected - in that case please open an issue. Tip: You can grab the list of available updates using APT_CONFIG=/tmp/i3rs-apt/apt.conf apt list --upgradable Configuration Key Values Default ------------------------------------------------------------------------------------- interval Update interval in seconds. 600 format A string to customise the " $icon $count.eng(w:1) " output of this block. See below for available placeholders. format_singular Same as format, but for when " $icon $count.eng(w:1) " exactly one update is available. format_up_to_date Same as format, but for when " $icon $count.eng(w:1) " no updates are available. warning_updates_regex Display block as warning if None updates matching regex are available. critical_updates_regex Display block as critical if None updates matching regex are available. ignore_updates_regex Doesn't include updates None matching regex in the count. ignore_phased_updates Doesn't include potentially false held back phased updates in the count. Placeholder Value Type Unit -------------------------------------------- icon A static icon Icon - count Number of Number - updates available Example Update the list of pending updates every thirty minutes (1800 seconds): [[block]] block = "apt" interval = 1800 format = " $icon $count updates available " format_singular = " $icon One update available " format_up_to_date = " $icon system up to date " critical_updates_regex = "(linux|linux-lts|linux-zen)" [[block.click]] ### shows dmenu with cached available updates. Any dmenu alternative should also work. button = "left" cmd = "APT_CONFIG=/tmp/i3rs-apt/apt.conf apt list --upgradable | tail -n +2 | rofi -dmenu" [[block.click]] ### Updates the block on right click button = "right" update = true Icons Used o update backlight The brightness of a backlight device This block reads brightness information directly from the filesystem, so it works under both X11 and Wayland. The block uses inotify to listen for changes in the device's brightness directly, so there is no need to set an update interval. This block uses DBus to set brightness level using the mouse wheel, but will fallback to sysfs if systemd-logind is not used. Root scaling Some devices expose raw values that are best handled with nonlinear scaling. The human perception of lightness is close to the cube root of relative luminance, so settings for root_scaling between 2.4 and 3.0 are worth trying. For devices with few discrete steps this should be 1.0 (linear). More information: Configuration Key Values Default --------------------------------------------------------------------------------------------------------------------------------- device A regex to match against /sys/class/backlight devices to read Default device brightness information from (can match 1 or more devices). When there is no device specified, this block will display information for all devices found in the /sys/class/backlight directory. format A string to customise the output of this block. See below for " $icon $brightness " available placeholders. missing_format A string to customise the output of this block. No placeholders " no backlight devices " available step_width The brightness increment to use when scrolling, in percent 5 minimum The minimum brightness that can be scrolled down to 5 maximum The maximum brightness that can be scrolled up to 100 cycle The brightnesses to cycle through on each click [minimum, maximum] root_scaling Scaling exponent reciprocal (ie. root) 1.0 invert_icons Invert icons' ordering, useful if you have colorful emoji false ddcci_sleep_multiplier https://www.ddcutil.com/performance_options/#option-sleep-multiplier 1.0 See ddcutil documentation ddcci_max_tries_write_read The maximum number of times to attempt writing to or reading from a 10 ddcci monitor Placeholder Value Type Unit ------------------------------------------------------------------------------- icon Icon based on backlight's state Icon - brightness Current brightness Number % Action Default button --------------------------------- cycle Left brightness_up Wheel Up brightness_down Wheel Down Example [[block]] block = "backlight" device = "intel_backlight" Hide missing backlight: [[block]] block = "backlight" missing_format = "" calibright Additional display brightness calibration can be set in $XDG_CONFIG_HOME/calibright/config.toml See for more details. This block will override any global config set in $XDG_CONFIG_HOME/calibright/config.toml D-Bus Fallback If you don't use systemd-logind i3status-rust will attempt to set the brightness using sysfs. In order to do this you'll need to have write permission. You can do this by writing a udev rule for your system. First, check that your user is a member of the "video" group using the groups command. Then add a rule in the /etc/udev/rules.d/ directory containing the following, for example in backlight.rules: ACTION=="add", SUBSYSTEM=="backlight", GROUP="video", MODE="0664" This will allow the video group to modify all backlight devices. You will also need to restart for this rule to take effect. Icons Used o backlight (as a progression) battery Information about the internal power supply This block can display the current battery state (Full, Charging or Discharging), percentage charged and estimate time until (dis)charged for an internal power supply. Configuration Key Values Default -------------------------------------------------------------------------------------------- device sysfs/UPower: The device in sysfs: the first battery /sys/class/power_supply/ to read from device found in (can also be "DisplayDevice" for /sys/class/power_supply, UPower, which is a single logical with "BATx" or "CMBx" power source representing all physical entries taking precedence. power sources. This is for example apc_ups: "localhost:3551". useful if your system has multiple upower: DisplayDevice batteries, in which case the DisplayDevice behaves as if you had a single larger battery.). apc_ups: IPv4Address:port or hostname:port driver One of "sysfs", "apc_ups", or "upower" "sysfs" model If present, the contents of N/A /sys/class/power_supply/.../model_name must match this value. Typical use is to select by model name on devices that change their path. interval Update interval, in seconds. Only 10 relevant for driver = "sysfs" or "apc_ups". format A string to customise the output of " $icon $percentage " this block. See below for available placeholders. full_format Same as format but for when the " $icon " battery is full charging_format Same as format but for when the Links to format battery is charging empty_format Same as format but for when the " $icon " battery is empty not_charging_format Same as format but for when the " $icon " battery is not charging. Defaults to the full battery icon as many batteries report this status when they are full. missing_format Same as format if the battery cannot " $icon " be found. info Minimum battery level, where state is 60 set to info good Minimum battery level, where state is 60 set to good warning Minimum battery level, where state is 30 set to warning critical Minimum battery level, where state is 15 set to critical full_threshold Percentage above which the battery is 95 considered full (full_format shown) empty_threshold Percentage below which the battery is 7.5 considered empty Placeholder Value Type Unit ------------------------------------------------------------------------------------------ icon Icon based on battery's state Icon - percentage Battery level, in percent Number Percents time_remaining Time remaining until (dis)charge is complete. Duration - Presented only if battery's status is (dis)charging. time Time remaining until (dis)charge is complete. String - Presented only if battery's status is DEPRECATED (dis)charging. power Power consumption by the battery or from the String or Watts power supply when charging Float time has been deprecated in favor of time_remaining. Examples Basic usage: [[block]] block = "battery" format = " $icon $percentage " [[block]] block = "battery" format = " $percentage {$time_remaining.dur(hms:true, min_unit:m) |}" device = "DisplayDevice" driver = "upower" Hide missing battery: [[block]] block = "battery" missing_format = "" Icons Used o bat (as a progression) o bat_charging (as a progression) o bat_not_available bluetooth Monitor Bluetooth device This block displays the connectivity of a given Bluetooth device and the battery level if this is supported. Relies on the Bluez D-Bus API. When the device can be identified as an audio headset, a keyboard, joystick, or mouse, use the relevant icon. Otherwise, fall back on the generic Bluetooth symbol. Right-clicking the block will attempt to connect (or disconnect) the device. Note: battery level information is not reported for some devices. https://wiki.archlinux.org/title/bluetooth#Enabling_experimental_features Enabling experimental features of bluez <> may fix it. Configuration Key Values Default ---------------------------------------------------------------------------------- mac MAC address of the Bluetooth Required device adapter_mac MAC Address of the Bluetooth None adapter (in case your device was connected to multiple currently available adapters) format A string to customise the " $icon $name{ $percentage|} output of this block. See " below for available placeholders. disconnected_format A string to customise the " $icon{ $name|} " output of this block. See below for available placeholders. battery_state A mapping from battery 0..15 -> critical, 16..30 -> percentage to block's state warning, 31..60 -> info, (color). See example below. 61..100 -> good Placeholder Value Type Unit ---------------------------------------------------------------------------------- icon Icon based on what type of device is connected Icon - name Device's name Text - percentage Device's battery level (may be absent if the Number % device is not supported) battery_icon Battery icon (may be absent if the device is not Icon - supported) available Present if the device is available Flag - Action Default button ------------------------ toggle Right Examples This example just shows the icon when device is connected. [[block]] block = "bluetooth" mac = "00:18:09:92:1B:BA" disconnected_format = "" format = " $icon " [block.battery_state] "0..20" = "critical" "21..70" = "warning" "71..100" = "good" Icons Used o headphones for bluetooth devices identifying as "audio-card", "audio-headset" or "audio-headphones" o joystick for bluetooth devices identifying as "input-gaming" o keyboard for bluetooth devices identifying as "input-keyboard" o mouse for bluetooth devices identifying as "input-mouse" o bluetooth for all other devices calendar Calendar This block displays upcoming calendar events retrieved from a CalDav ICalendar server. Configuration Key Values Default ---------------------------------------------------------------------------------------- next_event_format A string to customize the " $icon output of this block when $start.datetime(f:`%a there is a next event in the %H:%M') $summary " calendar. See below for available placeholders. ongoing_event_format A string to customize the " $icon $summary (ends at output of this block when an $end.datetime(f:`%H:%M')) " event is ongoing. no_events_format A string to customize the " $icon " output of this block when there are no events redirect_format A string to customize the " $icon Check your web output of this block when browser " the authorization is asked fetch_interval Fetch events interval in 60 seconds alternate_events_interval Alternate overlapping events 10 interval in seconds events_within_hours Number of hours to look for 48 events in the future source Array of sources to pull [] calendars from warning_threshold Warning threshold in seconds 300 for the upcoming event browser_cmd Command to open event "xdg-open" details in a browser. The block passes the HTML link as an argument Source Configuration Key Values Default ----------------------------------------------------------------------------- url CalDav calendar server URL N/A auth Authentication configuration unauthenticated (unauthenticated, basic, or oauth2) calendars List of calendar names to [] monitor. If empty, all calendars will be fetched. Note: Currently only one source is supported Action Description Default button ----------------------------------------------------------------------------- open_link Opens the HTML link of the event Left Examples Unauthenticated [[block]] block = "calendar" next_event_format = " $icon $start.datetime(f:'%a %H:%M') $summary " ongoing_event_format = " $icon $summary (ends at $end.datetime(f:'%H:%M')) " no_events_format = " $icon no events " fetch_interval = 30 alternate_events_interval = 10 events_within_hours = 48 warning_threshold = 600 browser_cmd = "firefox" [[block.source]] url = "https://caldav.example.com/calendar/" calendars = ["user/calendar"] [block.source.auth] type = "unauthenticated" Basic Authentication [[block]] block = "calendar" next_event_format = " $icon $start.datetime(f:'%a %H:%M') $summary " ongoing_event_format = " $icon $summary (ends at $end.datetime(f:'%H:%M')) " no_events_format = " $icon no events " fetch_interval = 30 alternate_events_interval = 10 events_within_hours = 48 warning_threshold = 600 browser_cmd = "firefox" [[block.source]] url = "https://caldav.example.com/calendar/" calendars = [ "Holidays" ] [block.source.auth] type = "basic" username = "your_username" password = "your_password" Note: You can also configure the username and password in a separate TOML file. ~/.config/i3status-rust/example_credentials.toml username = "my-username" password = "my-password" Source auth configuration with credentials_path: [block.source.auth] type = "basic" credentials_path = "~/.config/i3status-rust/example_credentials.toml" OAuth2 Authentication (Google Calendar) To access the CalDav API of Google, follow these steps to enable the API and obtain the client_id and client_secret: 1. Go to the Google Cloud Console: Navigate to the Google Cloud Console . 2. Create a New Project: If you don't already have a project, click on the project dropdown and select "New Project". Give your project a name and click "Create". 3. Enable the CalDAV API: In the project dashboard, go to the "APIs & Services" > "Library". Search for "CalDAV API" and click on it, then click "Enable". 4. Set Up OAuth Consent Screen: Go to "APIs & Services" > "OAuth consent screen". Fill out the required information and save. 5. Create Credentials: - Navigate to "APIs & Services" > "Credentials". - Click "Create Credentials" and select "OAuth 2.0 Client IDs". - Configure the consent screen if you haven't already. - Set the application type to "Web application". - Add your authorized redirect URIs. For example, http://localhost:8080. - Click "Create" and note down the client_id and client_secret. 6. Download the Credentials: Click on the download icon next to your OAuth 2.0 Client ID to download the JSON file containing your client ID and client secret. Use these values in your configuration. [[block]] block = "calendar" next_event_format = " $icon $start.datetime(f:'%a %H:%M') $summary " ongoing_event_format = " $icon $summary (ends at $end.datetime(f:'%H:%M')) " no_events_format = " $icon no events " fetch_interval = 30 alternate_events_interval = 10 events_within_hours = 48 warning_threshold = 600 browser_cmd = "firefox" [[block.source]] url = "https://apidata.googleusercontent.com/caldav/v2/" calendars = ["primary"] [block.source.auth] type = "oauth2" client_id = "your_client_id" client_secret = "your_client_secret" auth_url = "https://accounts.google.com/o/oauth2/auth" token_url = "https://oauth2.googleapis.com/token" auth_token = "~/.config/i3status-rust/calendar.auth_token" redirect_port = 8080 scopes = ["https://www.googleapis.com/auth/calendar", "https://www.googleapis.com/auth/calendar.events"] Note: You can also configure the client_id and client_secret in a separate TOML file. ~/.config/i3status-rust/google_credentials.toml client_id = "my-client_id" client_secret = "my-client_secret" Source auth configuration with credentials_path: [block.source.auth] type = "oauth2" credentials_path = "~/.config/i3status-rust/google_credentials.toml" auth_url = "https://accounts.google.com/o/oauth2/auth" token_url = "https://oauth2.googleapis.com/token" auth_token = "~/.config/i3status-rust/calendar.auth_token" redirect_port = 8080 scopes = ["https://www.googleapis.com/auth/calendar", "https://www.googleapis.com/auth/calendar.events"] Format Configuration The format configuration is a string that can include placeholders to be replaced with dynamic content. Placeholders can be: - $summary: Summary of the event - $description: Description of the event - $url: Url of the event - $location: Location of the event - $start: Start time of the event - $end: End time of the event Icons Used o calendar cpu CPU statistics Configuration Key Values Default ----------------------------------------------------------------------------- format A string to customise the " $icon $utilization " output of this block. See below for available placeholders. format_alt If set, block will switch None between format and format_alt on every click interval Update interval in seconds 5 info_cpu Percentage of CPU usage, 30.0 where state is set to info warning_cpu Percentage of CPU usage, 60.0 where state is set to warning critical_cpu Percentage of CPU usage, 90.0 where state is set to critical Placeholder Value Type Unit ----------------------------------------------------------------------------------- icon An icon Icon - utilization Average CPU utilization Number % utilization Utilization of Nth logical CPU Number % barchart Utilization of all logical CPUs presented as Text - a barchart frequency Average CPU frequency (may be absent if CPU Number Hz is not supported) frequency Frequency of Nth logical CPU (may be absent Number Hz if CPU is not supported) max_frequency Max frequency of all logical CPUs Number Hz boost CPU turbo boost status (may be absent if CPU Text - is not supported) Action Description Default button ----------------------------------------------------------------------------- toggle_format Toggles between format and format_alt Left Example [[block]] block = "cpu" interval = 1 format = " $icon $barchart $utilization " format_alt = " $icon $frequency{ $boost|} " info_cpu = 20 warning_cpu = 50 critical_cpu = 90 Icons Used o cpu (as a progression) o cpu_boost_on o cpu_boost_off custom The output of a custom shell command For further customisation, use the json option and have the shell command output valid JSON in the schema below: {"icon": "...", "state": "...", "text": "...", "short_text": "..."} icon is optional (default "") state is optional, it may be Idle, Info, Good, Warning, Critical (default Idle) short_text is optional. Configuration Key Values Default ------------------------------------------------------------------------------ format A string to customise the "{ $icon|} $text.pango-str() output of this block. See " below for available placeholders. command Shell command to execute & None display persistent Run command in the false background; update display for each output line of the command cycle Commands to execute and None change when the button is clicked interval Update interval in seconds 10 (or "once" to update only once) json Use JSON from command output false to format the block. If the JSON is not valid, the block will error out. watch_files Watch files to trigger None update on file modification. Supports path expansions e.g. ~. hide_when_empty Hides the block when the false command output (or json text field) is empty shell Specify the shell to use $SHELL if set, otherwise when running commands fallback to sh Placeholder Value Type Unit -------------------------------------------------------------------------------- icon Value of icon field from JSON output when Icon - it's non-empty text Output of the script or text field from Text JSON output short_text short_text field from JSON output Text Action Default button ------------------------ cycle Left Examples Display temperature, update every 10 seconds: [[block]] block = "custom" command = ''' cat /sys/class/thermal/thermal_zone0/temp | awk '{printf("%.1f\n",$1/1000)}' ''' Cycle between "ON" and "OFF", update every 1 second, run next cycle command when block is clicked: [[block]] block = "custom" cycle = ["echo ON", "echo OFF"] interval = 1 [[block.click]] button = "left" action = "cycle" Use JSON output: [[block]] block = "custom" command = "echo '{\"icon\":\"weather_thunder\",\"state\":\"Critical\", \"text\": \"Danger!\"}'" json = true Display kernel, update the block only once: [[block]] block = "custom" command = "uname -r" interval = "once" Display the screen brightness on an intel machine and update this only when pkill -SIGRTMIN+4 i3status-rs is called: [[block]] block = "custom" command = ''' cat /sys/class/backlight/intel_backlight/brightness | awk '{print $1}' ''' signal = 4 interval = "once" Update block when one or more specified files are modified: [[block]] block = "custom" command = "cat custom_status" watch_files = ["custom_status"] interval = "once" TODO: o Use shellexpand custom_dbus A block controlled by the DBus This block creates a new DBus object in rs.i3status service. This object implements rs.i3status.custom interface which allows you to set block's icon, text and state. Output of busctl --user introspect rs.i3status / rs.i3status.custom: NAME TYPE SIGNATURE RESULT/VALUE FLAGS rs.i3status.custom interface - - - .SetIcon method s s - .SetState method s s - .SetText method ss s - Configuration Key Values Default ----------------------------------------------------------------------------- format A string to customise the "{ $icon|}{ output of this block. $text.pango-str()|} " Placeholder Value Type Unit --------------------------------------------------------------------------------- icon Value of icon set via SetIcon if the value is Icon - non-empty string. text Value of the first string from SetText Text - short_text Value of the second string from SetText Text - Example Config: [[block]] block = "custom_dbus" path = "/my_path" Usage: ### set full text to 'hello' and short text to 'hi' busctl --user call rs.i3status /my_path rs.i3status.custom SetText ss hello hi ### set icon to 'music' busctl --user call rs.i3status /my_path rs.i3status.custom SetIcon s music ### set state to 'good' busctl --user call rs.i3status /my_path rs.i3status.custom SetState s good Because it's impossible to publish objects to the same name from different processes, having multiple dbus blocks in different bars won't work. As a workaround, you can set the env var I3RS_DBUS_NAME to set the interface a bar works on to differentiate between different processes. For example, setting this to `top', will allow you to use rs.i3status.top. TODO o Send a signal on click? disk_space Disk usage statistics Configuration Key Values Default ----------------------------------------------------------------------------- path Path to collect information "/" from. Supports path expansions e.g. ~. interval Update time in seconds 20 format A string to customise the " $icon $available " output of this block. See below for available placeholders. format_alt If set, block will switch None between format and format_alt on every click warning A value which will trigger 20.0 warning block state alert A value which will trigger 10.0 critical block state info_type Determines which information "available" will affect the block state. Possible values are "available", "free" and "used" alert_unit The unit of alert and None warning options. If not set, percents are used. Possible values are "B", "KB", "KiB", "MB", "MiB", "GB", "Gib", "TB" and "TiB" Placeholder Value Type Unit ---------------------------------------------------------------------------------- icon A static icon Icon - path The value of path option Text - percentage Free or used percentage. Depends on info_type Number % total Total disk space Number Bytes used Used disk space Number Bytes free Free disk space Number Bytes available Available disk space (free disk space minus Number Bytes reserved system space) Action Description Default button ----------------------------------------------------------------------------- toggle_format Toggles between format and format_alt Left Examples [[block]] block = "disk_space" info_type = "available" alert_unit = "GB" alert = 10.0 warning = 15.0 format = " $icon $available " format_alt = " $icon $available / $total " Update block on right click: [[block]] block = "disk_space" [[block.click]] button = "right" update = true Show the block only if less than 10GB is available: [[block]] block = "disk_space" format = " $free.eng(range:..10e9) |" Icons Used o disk_drive dnf Pending updates available for your Fedora system Configuration Key Values Default ------------------------------------------------------------------------------------- interval Update interval in seconds. 600 format A string to customise the " $icon $count.eng(w:1) " output of this block. See below for available placeholders. format_singular Same as format, but for when " $icon $count.eng(w:1) " exactly one update is available. format_up_to_date Same as format, but for when " $icon $count.eng(w:1) " no updates are available. warning_updates_regex Display block as warning if None updates matching regex are available. critical_updates_regex Display block as critical if None updates matching regex are available. Placeholder Value Type Unit -------------------------------------------- icon A static icon Icon - count Number of Number - updates available Example Update the list of pending updates every thirty minutes (1800 seconds): [[block]] block = "dnf" interval = 1800 format = " $icon $count.eng(w:1) updates available " format_singular = " $icon One update available " format_up_to_date = " $icon system up to date " critical_updates_regex = "(linux|linux-lts|linux-zen)" [[block.click]] ### shows dmenu with cached available updates. Any dmenu alternative should also work. button = "left" cmd = "dnf list -q --upgrades | tail -n +2 | rofi -dmenu" Icons Used o update docker Local docker daemon status Configuration Key Values Default ----------------------------------------------------------------------------- interval Update interval, in seconds. 5 format A string to customise the " $icon $running.eng(w:1) " output of this block. See below for available placeholders. socket_path The path to the docker "/var/run/docker.sock" socket. Supports path expansions e.g. ~. Key Value Type Unit ------------------------------------------- icon A static icon Icon - total Total containers Number - on the host running Containers Number - running on the host stopped Containers Number - stopped on the host paused Containers Number - paused on the host images Total images on Number - the host Example [[block]] block = "docker" interval = 2 format = " $icon $running/$total " Icons Used o docker external_ip External IP address and various information about it Configuration Key Values Default ----------------------------------------------------------------------------------- format A string to customise the " $ip $country_flag " output of this block. See below for available placeholders. interval Interval in seconds for 300 automatic updates with_network_manager If `true', listen for true NetworkManager events and update the IP immediately if there was a change use_ipv4 If `true', use IPv4 for false obtaining all info Key Value Type Unit ------------------------------------------------------------------------------------ ip The external IP Text - address, as seen from a remote server version IPv4 or IPv6 Text - city City name, such as Text - "San Francisco" region Region name, such as Text - "California" region_code Region code, such as Text - "CA" for California country Country code (2 Text - letter, ISO 3166-1 alpha-2) country_name Short country name Text - country_code Country code (2 Text - letter, ISO 3166-1 alpha-2) country_code_iso3 Country code (3 Text - letter, ISO 3166-1 alpha-3) country_capital Capital of the Text - country country_tld Country specific TLD Text - (top-level domain) continent_code Continent code Text - in_eu Region code, such as Flag - "CA" postal ZIP / Postal code Text - latitude Latitude Number - (TODO: make degrees?) longitude Longitude Number - (TODO: make degrees?) timezone City Text - utc_offset UTC offset (with Text - daylight saving time) as +HHMM or -HHMM (HH is hours, MM is minutes) country_calling_code Country calling code Text - (dial in code, comma separated) currency Currency code (ISO Text - 4217) currency_name Currency name Text - languages Languages spoken Text - (comma separated 2 or 3 letter ISO 639 code with optional hyphen separated country suffix) country_area Area of the country Number - (in sq km) country_population Population of the Number - country timezone Time zone Text - org Organization Text - asn Autonomous system Text - (AS) country_flag Flag of the country Text (glyph) - Example [[block]] block = "external_ip" format = " $ip $country_code " Notes All the information comes from Check their documentation here: The IP is queried, 1) When i3status-rs starts, 2) When a signal is received on D-Bus about a network configuration change, 3) Every 5 minutes. This periodic refresh exists to catch IP updates that don't trigger a notification, for example due to a IP refresh at the router. Flags: They are not icons but unicode glyphs. You will need a font that includes them. Tested with: focused_window Currently focused window This block displays the title and/or the active marks (when used with sway/i3) of the currently focused window. Supported WMs are: sway, i3 and most wlroots-based compositors. See driver option for more info. Configuration Key Values Default ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- format A string to customise the output of this block. See below for available placeholders. " $title.str(max_w:21) |" driver Which driver to use. Available values: sway_ipc - for i3 and sway, wlr_toplevel_management - for Wayland compositors that "auto" implement https://gitlab.freedesktop.org/wlroots/wlr-protocols/-/blob/master/unstable/wlr-foreign-toplevel-management-unstable-v1.xml wlr-foreign-toplevel-management-unstable-v1 , auto - try to automatically guess which driver to use. Placeholder Value Type Unit ---------------------------------------------------------------------------------- title Window's title (may be absent) Text - marks Window's marks (present only with sway/i3) Text - visible_marks Window's marks that do not start with _ (present Text - only with sway/i3) Example [[block]] block = "focused_window" [block.format] full = " $title.str(max_w:15) |" short = " $title.str(max_w:10) |" This example instead of hiding block when the window's title is empty displays "Missing" [[block]] block = "focused_window" format = " $title.str(0,21) | Missing " github The number of GitHub notifications This block shows the unread notification count for a GitHub account. A GitHub personal access token with the "notifications" scope is required, and must be passed using the I3RS_GITHUB_TOKEN environment variable or token configuration option. Optionally the colour of the block is determined by the highest notification in the following lists from highest to lowest: critical,warning,info,good Configuration Key Values Default ------------------------------------------------------------------------------------ format A string to customise the " $icon $total.eng(w:1) " output of this block. See below for available placeholders. interval Update interval in seconds 30 token A GitHub personal access None token with the "notifications" scope hide_if_total_is_zero Hide this block if the total false count of notifications is zero critical List of notification types None that change the block to the critical colour warning List of notification types None that change the block to the warning colour info List of notification types None that change the block to the info colour good List of notification types None that change the block to the good colour All the placeholders are numbers without a unit. Placeholder Value -------------------------------------------------------------------------- icon A static icon total The total number of notifications assign You were assigned to the issue author You created the thread comment You commented on the thread ci_activity A GitHub Actions workflow run that you triggered was completed invitation You accepted an invitation to contribute to the repository manual You subscribed to the thread (via an issue or pull request) mention You were specifically @mentioned in the content review_requested You, or a team you're a member of, were requested to review a pull request security_alert GitHub discovered a security vulnerability in your repository state_change You changed the thread state (for example, closing an issue or merging a pull request) subscribed You're watching the repository team_mention You were on a team that was mentioned Examples [[block]] block = "github" format = " $icon $total.eng(w:1)|$mention.eng(w:1) " interval = 60 token = "..." [[block]] block = "github" token = "..." format = " $icon $total.eng(w:1) " info = ["total"] warning = ["mention","review_requested"] hide_if_total_is_zero = true Icons Used o github hueshift Manage display temperature This block displays the current color temperature in Kelvin. When scrolling upon the block the color temperature is changed. A left click on the block sets the color temperature to click_temp that is by default to 6500K. A right click completely resets the color temperature to its default value (6500K). Configuration Key Values Default ----------------------------------------------------------------------------- format A string to customise the " $temperature " output of this block. See below for available placeholders. step The step color temperature 100 is in/decreased in Kelvin. hue_shifter Program used to control Detect automatically screen color. max_temp Max color temperature in 10000 Kelvin. min_temp Min color temperature in 1000 Kelvin. click_temp Left click color temperature 6500 in Kelvin. Placeholder Value Type Unit ------------------------------------------------------------------------------- temperature Current temperature Number - Action Default button ---------------------------------- set_click_temp Left reset Right temperature_up Wheel Up temperature_down Wheel Down Available Hue Shifters Name Supports ------------------------------------- "redshift" X11 "sct" X11 "gammastep" X11 and Wayland "wl_gammarelay" Wayland "wl_gammarelay_rs" Wayland "wlsunset" Wayland Note that at the moment, only wl_gammarelay and wl_gammarelay_rs subscribe to the events and update the bar when the temperature is modified externally. Also, these are the only drivers at the moment that work under Wayland without flickering. Example [[block]] block = "hueshift" hue_shifter = "redshift" step = 50 click_temp = 3500 A hard limit is set for the max_temp to 10000K and the same for the min_temp which is 1000K. The step has a hard limit as well, defined to 500K to avoid too brutal changes. kdeconnect KDEConnect indicator Display info from the currently connected device in KDEConnect, updated asynchronously. Block colours are updated based on the battery level, unless all bat_* thresholds are set to 0, in which case the block colours will depend on the notification count instead. Configuration Key Values Default ---------------------------------------------------------------------------------- device_id Device ID as per the output Chooses the first found of kdeconnect device, if any. --list-devices. format A string to customise the " $icon $name{ $bat_icon output of this block. See $bat_charge|}{ $notif_icon|} below for available " placeholders. format_disconnected Same as format but when " $icon " device is disconnected format_missing Same as format but when " $icon x " device does not exist bat_info Min battery level below 60 which state is set to info. bat_good Min battery level below 60 which state is set to good. bat_warning Min battery level below 30 which state is set to warning. bat_critical Min battery level below 15 which state is set to critical. Placeholder Value Type Unit ------------------------------------------------------------------------------------- icon Icon based on connection's status Icon - bat_icon Battery level indicator (only when connected and Icon - if supported) bat_charge Battery charge level (only when connected and if Number % supported) network_icon Cell Network indicator (only when connected and Icon - if supported) network_type Cell Network type (only when connected and if Text - supported) network_strength Cell Network level (only when connected and if Number % supported) notif_icon Only when connected and there are notifications Icon - notif_count Number of notifications on your phone (only when Number - connected and non-zero) name Name of your device as reported by KDEConnect (if Text - available) Example Do not show the name, do not set the "good" state. [[block]] block = "kdeconnect" format = " $icon {$bat_icon $bat_charge |}{$notif_icon |}{$network_icon$network_strength $network_type |}" bat_good = 101 Icons Used o bat (as a progression) o bat_charging (as a progression) o net_cellular (as a progression) o notification o phone o phone_disconnected keyboard_layout Keyboard layout indicator Four drivers are available: - setxkbmap which polls setxkbmap to get the current layout - xkbswitch which utilizes XkbSwitch to monitor and retrieve the current layout and variant - localebus which can read asynchronous updates from the systemd org.freedesktop.locale1 D-Bus path - kbddbus which uses kbdd to monitor per-window layout changes via DBus - sway which can read asynchronous updates from the sway IPC Which of these methods is appropriate will depend on your system setup. Configuration Key Values Default ------------------------------------------------------------------------------- driver One of "setxkbmap", "xkbswitch", "localebus","kbddbus"or"sway", depending on your system. |"setxkbmap"interval| Update interval, in seconds. Only used by the"setxkbmap"driver. |60format| A string to customise the output of this block. See below for available placeholders. |" $layout "sway_kb_identifier| Identifier of the device you want to monitor, as found in the output ofswaymsg -t get_inputs. | Defaults to first input foundmappings| Maplayout (variant)to custom short name. |None` Key Value Type -------------------------------------- layout Keyboard layout String name variant Keyboard variant String name or N/A if not applicable Examples Check setxkbmap every 15 seconds: [[block]] block = "keyboard_layout" driver = "setxkbmap" interval = 15 Check xkbswitch every 15 seconds [[block]] block = "keyboard_layout" driver = "xkbswitch" interval = 15 Listen to D-Bus for changes: [[block]] block = "keyboard_layout" driver = "localebus" Listen to kbdd for changes, the text is in the following format: "English (US)" - {$layout ($variant)} use block.mappings to override with shorter names as shown below. Also use format = " $layout ($variant) " to see the full text to map, or you can use: dbus-monitor interface=ru.gentoo.kbdd to see the exact variant spelling [[block]] block = "keyboard_layout" driver = "kbddbus" [block.mappings] "English (US)" = "us" "Bulgarian (new phonetic)" = "bg" Listen to sway for changes: [[block]] block = "keyboard_layout" driver = "sway" sway_kb_identifier = "1133:49706:Gaming_Keyboard_G110" Listen to sway for changes and override mappings: [[block]] block = "keyboard_layout" driver = "sway" format = " $layout " [block.mappings] "English (Workman)" = "EN" "Russian (N/A)" = "RU" load System load average Configuration Key Values Default ------------------------------------------------------------------------------------ format A string to customise the output of this block. See below " $icon for available placeholders. $1m.eng(w:4) " interval Update interval in seconds 3 info Minimum load, where state is set to info 0.3 warning Minimum load, where state is set to warning 0.6 critical Minimum load, where state is set to critical 0.9 Placeholder Value Type Unit --------------------------------------------- icon A static icon Icon - 1m 1 minute load Number - average 5m 5 minute load Number - average 15m 15 minute load Number - average Example [[block]] block = "load" format = " $icon 1min avg: $1m.eng(w:4) " interval = 1 Icons Used o cogs maildir Unread mail. Only supports maildir format. Note that you need to enable maildir feature to use this block: cargo build --release --features maildir Configuration Key Values Default --------------------------------------------------------------------------------- format A string to customise the " $icon $status " output of this block. See below for available placeholders. inboxes List of maildir inboxes to Required look for mails in. Supports path/glob expansions (e.g. ~ and *). threshold_warning Number of unread mails where 1 state is set to warning. threshold_critical Number of unread mails where 10 state is set to critical. interval Update interval, in seconds. 5 display_type Which part of the maildir to "new" count: "new", "cur", or "all". Placeholder Value Type Unit ----------------------------------------------- icon A static icon Icon - status Number of emails Number - Examples [[block]] block = "maildir" interval = 60 inboxes = ["~/mail/local", "~/maildir/account1/*"] threshold_warning = 1 threshold_critical = 10 display_type = "new" Icons Used o mail memory Memory and swap usage Configuration Key Values Default -------------------------------------------------------------------------------------------------------------------------------- format A string to customise the " $icon output of this block when in $mem_used.eng(prefix:Mi)/$mem_total.eng(prefix:Mi)($mem_used_percents.eng(w:2)) "Memory" view. See below for " available placeholders. format_alt If set, block will switch None between format and format_alt on every click interval Update interval in seconds 5 warning_mem Percentage of memory usage, 80.0 where state is set to warning warning_swap Percentage of swap usage, 80.0 where state is set to warning critical_mem Percentage of memory usage, 95.0 where state is set to critical critical_swap Percentage of swap usage, 95.0 where state is set to critical Placeholder Value Type Unit ------------------------------------------------------------------------------------------------- icon Memory icon Icon - icon_swap Swap icon Icon - mem_total Total physical ram available Number Bytes mem_free Free memory not yet used by the kernel or Number Bytes userspace (in general you should use mem_avail) mem_free_percents as above but as a percentage of total memory Number Percents mem_avail Kernel estimate of usable free memory which Number Bytes includes cached memory and buffers mem_avail_percents as above but as a percentage of total memory Number Percents mem_total_used mem_total - mem_free Number Bytes mem_total_used_percents as above but as a percentage of total memory Number Percents mem_used Memory used, excluding cached memory and Number Bytes buffers; same as htop's green bar mem_used_percents as above but as a percentage of total memory Number Percents buffers Buffers, similar to htop's blue bar Number Bytes buffers_percent as above but as a percentage of total memory Number Percents cached Cached memory (taking into account ZFS ARC Number Bytes cache), similar to htop's yellow bar cached_percent as above but as a percentage of total memory Number Percents swap_total Swap total Number Bytes swap_free Swap free Number Bytes swap_free_percents as above but as a percentage of total memory Number Percents swap_used Swap used Number Bytes swap_used_percents as above but as a percentage of total memory Number Percents zram_compressed Compressed zram memory usage Number Bytes zram_decompressed Decompressed zram memory usage Number Bytes `zram_comp_ratio' Ratio of the decompressed/compressed zram Number - memory zswap_compressed Compressed zswap memory usage (>=Linux 5.19) Number Bytes zswap_decompressed Decompressed zswap memory usage (>=Linux 5.19) Number Bytes zswap_decompressed_percents as above but as a percentage of total zswap Number Percents memory (>=Linux 5.19) `zswap_comp_ratio' Ratio of the decompressed/compressed zswap Number - memory (>=Linux 5.19) Action Description Default button ----------------------------------------------------------------------------- toggle_format Toggles between format and format_alt Left Examples [[block]] block = "memory" format = " $icon $mem_used_percents.eng(w:1) " format_alt = " $icon_swap $swap_free.eng(w:3,u:B,p:Mi)/$swap_total.eng(w:3,u:B,p:Mi)($swap_used_percents.eng(w:2)) " interval = 30 warning_mem = 70 critical_mem = 90 Show swap and hide if it is zero: [[block]] block = "memory" format = " $icon $swap_used.eng(range:1..) |" Icons Used o memory_mem o memory_swap menu A custom menu This block allows you to quickly run a custom shell command. Left-click on this block to activate it, then scroll through configured items. Left-click on the item to run it and optionally confirm your action by left-clicking again. Right-click any time to deactivate this block. Configuration Key Values Default ----------------------------------------------------------------------------- text Text that will be displayed Required when the block is inactive. items A list of "items". See Required examples below. Example [[block]] block = "menu" text = "\uf011" [[block.items]] display = " -> Sleep <-" cmd = "systemctl suspend" [[block.items]] display = " -> Power Off <-" cmd = "poweroff" confirm_msg = "Are you sure you want to power off?" [[block.items]] display = " -> Reboot <-" cmd = "reboot" confirm_msg = "Are you sure you want to reboot?" music The current song title and artist Also provides buttons for play/pause, previous and next. Supports all music players that implement the https://specifications.freedesktop.org/mpris- spec/latest/Player_Interface.html MediaPlayer2 Interface <>. This includes: o Spotify o VLC o mpd (via mpDris2 ) and many others. By default the block tracks all players available on the MPRIS bus. Right clicking on the block will cycle it to the next player. You can pin the widget to a given player via the "player" setting. Configuration Key Values Default ------------------------------------------------------------------------------------------------ format A string to customise the " $icon output of this block. See {$combo.str(max_w:25,rot_interval:0.5) below for available $play |}" placeholders. format_alt If set, block will switch None between format and format_alt on every click player Name(s) of the music None player(s) MPRIS interface. This can be either a music player name or an array of music player names. Run busctl --user list | grep "org.mpris.MediaPlayer2." | cut -d' ' -f1 and the name is the part after "org.mpris.MediaPlayer2.". interface_name_exclude A list of regex patterns for ["playerctld"] player MPRIS interface names to ignore. separator String to insert between " - " artist and title. seek_step_secs Positive number of seconds 1 to seek forward/backward when scrolling on the bar. Does not need to be an integer. seek_forward_step_secs Positive number of seconds seek_step_secs to seek forward when scrolling on the bar. Does not need to be an integer. seek_backward_step_secs Positive number of seconds seek_step_secs to seek backward when scrolling on the bar. Does not need to be an integer. volume_step The percent volume level is 5 increased/decreased for the selected audio device when scrolling. Capped automatically at 50. Note: All placeholders except icon can be absent. See the examples below to learn how to handle this. Placeholder Value Type ----------------------------------------------------------------------------- icon A static icon Icon artist Current artist Text title Current title Text url Current song url Text combo Resolves to Text "$artist[sep]$title", "$artist", "$title", or "$url" depending on what information is available. [sep] is set by separator option. player Name of the current player Text (taken from the last part of its MPRIS bus name) avail Total number of players Number available to switch between cur The current player index of the Number available players play Play/Pause button Clickable icon next Next button Clickable icon prev Previous button Clickable icon volume_icon Icon based on volume. Missing Icon if unsupported. volume Current volume. Missing if Number muted or unsupported. Action Default button ------------------------------- play_pause Left on $play next Left on $next prev Left on $prev next_player Right seek_forward Wheel Up seek_backward Wheel Down volume_up - volume_down - toggle_format Left Examples Show the currently playing song on Spotify only, with play & next buttons and limit the width to 20 characters: [[block]] block = "music" format = " $icon {$combo.str(max_w:20) $play $next |}" player = "spotify" Same thing for any compatible player, takes the first active on the bus, but ignores "mpd" or anything with "kdeconnect" in the name: [[block]] block = "music" format = " $icon {$combo.str(max_w:20) $play $next |}" interface_name_exclude = [".*kdeconnect.*", "mpd"] Same as above, but displays with rotating text [[block]] block = "music" format = " $icon {$combo.str(max_w:20,rot_interval:0.5) $play $next |}" interface_name_exclude = [".*kdeconnect.*", "mpd"] Click anywhere to play/pause, middle click to toggle format: [[block]] block = "music" format = " format 1 " format_alt = " format 2 " [[block.click]] button = "left" action = "play_pause" [[block.click]] button = "middle" widget = "." action = "toggle_format" Scroll to change the player volume, use the forward and back buttons to seek: [[block]] block = "music" format = " $icon $volume_icon $combo $play $next| " seek_step_secs = 10 [[block.click]] button = "up" action = "volume_up" [[block.click]] button = "down" action = "volume_down" [[block.click]] button = "forward" action = "seek_forward" [[block.click]] button = "back" action = "seek_backward" Icons Used o music o music_next o music_play o music_prev o volume_muted o volume (as a progression) net Network information This block uses sysfs and netlink and thus does not require any external dependencies. Configuration Key Values Default ------------------------------------------------------------------------------ device Network interface to monitor If not set, device will be (as specified in automatically selected every /sys/class/net/). Supports interval regex. interval Update interval in seconds 2 format A string to customise the " $icon ^icon_net_down output of this block. See $speed_down.eng(prefix:K) below for available ^icon_net_up placeholders. $speed_up.eng(prefix:K) " format_alt If set, block will switch None between format and format_alt on every click inactive_format Same as format but for when " $icon Down " the interface is inactive missing_format Same as format but for when " x " the device is missing Action Description Default button ----------------------------------------------------------------------------- toggle_format Toggles between format and format_alt Left Placeholder Value Type Unit -------------------------------------------------------------------------------- icon Icon based on device's type Icon - speed_down Download speed Number Bytes per second speed_up Upload speed Number Bytes per second graph_down Download speed graph Text - graph_up Upload speed graph Text - device The name of device Text - ssid Netfork SSID (WiFi only) Text - frequency WiFi frequency Number Hz signal_strength WiFi signal Number % bitrate WiFi connection bitrate Number Bits per second ip IPv4 address of the iface Text - ipv6 IPv6 address of the iface Text - nameserver Nameserver Text - Example Display WiFi info if available [[block]] block = "net" format = " $icon {$signal_strength $ssid $frequency|Wired connection} via $device " Display exact device [[block]] block = "net" device = "^wlo0$" Icons Used o net_loopback o net_vpn o net_wired o net_wireless (as a progression) o net_up o net_down notify Display and toggle the state of notifications daemon Left-clicking on this block will enable/disable notifications. Configuration Key Values Default ----------------------------------------------------------------------------- driver Which notifications daemon "dunst" is running. Available drivers are: "dunst" and "swaync" format A string to customise the " $icon " output of this block. See below for available placeholders. Placeholder Value Type Unit --------------------------------------------------------------------------------- icon Icon based on notification's Icon - state notification_count[1] The number of notification Number - (omitted if 0) paused Present only if notifications Flag - are disabled Action Default button ------------------------------- toggle_paused Left show - Examples How to use paused flag [[block]] block = "notify" format = " $icon {$paused{Off}|On} " How to use notification_count [[block]] block = "notify" format = " $icon {($notification_count.eng(w:1)) |}" How to remap actions [[block]] block = "notify" driver = "swaync" [[block.click]] button = "left" action = "show" [[block.click]] button = "right" action = "toggle_paused" Icons Used o bell o bell-slash notmuch Count of notmuch messages This block queries a notmuch database and displays the count of messages. The simplest configuration will return the total count of messages in the notmuch database stored at $HOME/.mail Note that you need to enable notmuch feature to use this block: cargo build --release --features notmuch Configuration Key Values Default --------------------------------------------------------------------------------- format A string to customise the " $icon $count " output of this block. See below for available placeholders. maildir Path to the directory ~/.mail containing the notmuch database. Supports path expansions e.g. ~. query Query to run on the "" database. threshold_critical Mail count that triggers 99999 critical state. threshold_warning Mail count that triggers 99999 warning state. threshold_good Mail count that triggers 99999 good state. threshold_info Mail count that triggers 99999 info state. interval Update interval in seconds. 10 Placeholder Value Type Unit -------------------------------------------------------------------------------- icon A static icon Icon - count Number of messages for the query Number - Example [[block]] block = "notmuch" query = "tag:alert and not tag:trash" threshold_warning = 1 threshold_critical = 10 [[block.click]] button = "left" update = true Icons Used o mail nvidia_gpu Display the stats of your NVidia GPU By default show_temperature shows the used memory. Clicking the left mouse on the "temperature" part of the block will alternate it between showing used or total available memory. Clicking the left mouse button on the "fan speed" part of the block will cause it to enter into a fan speed setting mode. In this mode you can scroll the mouse wheel over the block to change the fan speeds, and left click to exit the mode. Requires nvidia-smi for displaying info and nvidia_settings for setting fan speed. Configuration Key Values Default ----------------------------------------------------------------------------- gpu_id GPU id in system. 0 format A string to customise the " $icon $utilization $memory output of this block. See $temperature " below for available placeholders. interval Update interval in seconds. 1 idle Maximum temperature, below 50 which state is set to idle good Maximum temperature, below 70 which state is set to good info Maximum temperature, below 75 which state is set to info warning Maximum temperature, below 80 which state is set to warning Placeholder Type Unit -------------------------------- icon Icon - name Text - utilization Number Percents memory Number Bytes temperature Number Degrees fan_speed Number Percents clocks Number Hertz power Number Watts Action Default button ------------------------------------------------- toggle_mem_total Left on $memory toggle_fan_controlled Left on $fan_speed fan_speed_up Wheel Up on $fan_speed fan_speed_down Wheel Down on $fan_speed Example [[block]] block = "nvidia_gpu" interval = 1 format = " $icon GT 1030 $utilization $temperature $clocks " Icons Used o gpu TODO o Provide a mappings option similar to keyboard_layout's to map GPU names to labels? packages Pending updates for different package manager like apt, pacman, etc. Currently these package managers are available: - apt for Debian/Ubuntu based system - pacman for Arch based system - aur for Arch based system - dnf for Fedora based system Configuration Key Values Default ------------------------------------------------------------------------------------- interval Update interval in seconds. 600 package_manager Package manager to check for Automatically derived from updates format templates, but can be used to influence the $total value format A string to customise the " $icon $total.eng(w:1) " output of this block. See below for available placeholders. format_singular Same as format, but for when " $icon $total.eng(w:1) " exactly one update is available. format_up_to_date Same as format, but for when " $icon $total.eng(w:1) " no updates are available. warning_updates_regex Display block as warning if None updates matching regex are available. critical_updates_regex Display block as critical if None updates matching regex are available. ignore_updates_regex Doesn't include updates None matching regex in the count. ignore_phased_updates Doesn't include potentially false held back phased updates in the count. (For Debian/Ubuntu based system) aur_command AUR command to check Required if $aur are used available updates, which outputs in the same format as pacman. e.g. yay -Qua (For Arch based system) Placeholder Value Type Unit ------------------------------------------------------------------------------------ icon A static icon Icon - apt Number of updates available in Debian/Ubuntu based Number - system pacman Number of updates available in Arch based system Number - aur Number of updates available in Arch based system Number - dnf Number of updates available in Fedora based system Number - total Number of updates available in all package manager Number - listed Apt Behind the scenes this uses apt, and in order to run it without root privileges i3status-rust will create its own package database in /tmp/i3rs-apt/ which may take up several MB or more. If you have a custom apt config then this block may not work as expected - in that case please open an issue. Tip: You can grab the list of available updates using APT_CONFIG=/tmp/i3rs-apt/apt.conf apt list --upgradable Pacman Requires fakeroot to be installed (only required for pacman). Tip: You can grab the list of available updates using fakeroot pacman -Qu --dbpath /tmp/checkup-db-i3statusrs-$USER/. If you have the CHECKUPDATES_DB env var set on your system then substitute that dir instead. Note: pikaur may hang the whole block if there is no internet connectivity reference . In that case, try a different AUR helper. Pacman hook Tip: On Arch Linux you can setup a pacman hook to signal i3status-rs to update after packages have been upgraded, so you won't have stale info in your pacman block. In the block configuration, set signal = 1 (or other number if 1 is being used by some other block): [[block]] block = "packages" signal = 1 Create /etc/pacman.d/hooks/i3status-rust.hook with the below contents: [Trigger] Operation = Upgrade Type = Package Target = * [Action] When = PostTransaction Exec = /usr/bin/pkill -SIGRTMIN+1 i3status-rs Example Apt only config [[block]] block = "packages" interval = 1800 package_manager = ["apt"] format = " $icon $apt updates available" format_singular = " $icon One update available " format_up_to_date = " $icon system up to date " [[block.click]] ### shows dmenu with cached available updates. Any dmenu alternative should also work. button = "left" cmd = "APT_CONFIG=/tmp/i3rs-apt/apt.conf apt list --upgradable | tail -n +2 | rofi -dmenu" [[block.click]] ### Updates the block on right click button = "right" update = true Pacman only config: [[block]] block = "packages" package_manager = ["pacman"] interval = 600 format = " $icon $pacman updates available " format_singular = " $icon $pacman update available " format_up_to_date = " $icon system up to date " [[block.click]] ### pop-up a menu showing the available updates. Replace wofi with your favourite menu command. button = "left" cmd = "fakeroot pacman -Qu --dbpath /tmp/checkup-db-i3statusrs-$USER/ | wofi --show dmenu" [[block.click]] ### Updates the block on right click button = "right" update = true Pacman and AUR helper config: [[block]] block = "packages" package_manager = ["pacman", "aur"] interval = 600 error_interval = 300 format = " $icon $pacman + $aur = $total updates available " format_singular = " $icon $total update available " format_up_to_date = " $icon system up to date " ### aur_command should output available updates to stdout (ie behave as echo -ne "update\n") aur_command = "yay -Qua" Dnf only config: [[block]] block = "packages" package_manager = ["dnf"] interval = 1800 format = " $icon $dnf.eng(w:1) updates available " format_singular = " $icon One update available " format_up_to_date = " $icon system up to date " [[block.click]] ### shows dmenu with cached available updates. Any dmenu alternative should also work. button = "left" cmd = "dnf list -q --upgrades | tail -n +2 | rofi -dmenu" Multiple package managers config: Update the list of pending updates every thirty minutes (1800 seconds): [[block]] block = "packages" package_manager = ["apt", "pacman", "aur","dnf"] interval = 1800 format = " $icon $apt + $pacman + $aur + $dnf = $total updates available " format_singular = " $icon One update available " format_up_to_date = " $icon system up to date " ### If a linux update is available, but no ZFS package, it won't be possible to ### actually perform a system upgrade, so we show a warning. warning_updates_regex = "(linux|linux-lts|linux-zen)" ### If ZFS is available, we know that we can and should do an upgrade, so we show ### the status as critical. critical_updates_regex = "(zfs|zfs-lts)" Icons Used o update pacman Pending updates available on pacman or an AUR helper. Requires fakeroot to be installed (only required for pacman). Tip: You can grab the list of available updates using fakeroot pacman -Qu --dbpath /tmp/checkup-db-i3statusrs-$USER/. If you have the CHECKUPDATES_DB env var set on your system then substitute that dir instead. Note: pikaur may hang the whole block if there is no internet connectivity reference . In that case, try a different AUR helper. Pacman hook Tip: On Arch Linux you can setup a pacman hook to signal i3status-rs to update after packages have been upgraded, so you won't have stale info in your pacman block. In the block configuration, set signal = 1 (or other number if 1 is being used by some other block): [[block]] block = "pacman" signal = 1 Create /etc/pacman.d/hooks/i3status-rust.hook with the below contents: [Trigger] Operation = Upgrade Type = Package Target = * [Action] When = PostTransaction Exec = /usr/bin/pkill -SIGRTMIN+1 i3status-rs Configuration Key Values Default -------------------------------------------------------------------------------------- interval Update interval, in 600 seconds. If setting aur_command then set interval appropriately as to not exceed the AUR's daily rate limit. format A string to customise the " $icon $pacman.eng(w:1) " output of this block. See below for available placeholders. format_singular Same as format but for when " $icon $pacman.eng(w:1) " exactly one update is available. format_up_to_date Same as format but for when " $icon $pacman.eng(w:1) " no updates are available. warning_updates_regex Display block as warning if None updates matching regex are available. critical_updates_regex Display block as critical None if updates matching regex are available. aur_command AUR command to check Required if $both or $aur are available updates, which used outputs in the same format as pacman. e.g. yay -Qua Placeholder Value Type Unit ------------------------------------------------------------------------------------ icon A static icon Icon - pacman Number of updates available according to pacman Number - aur Number of updates available according to Number - both Cumulative number of updates available according to Number - pacman and Examples pacman only config: [[block]] block = "pacman" interval = 600 format = " $icon $pacman updates available " format_singular = " $icon $pacman update available " format_up_to_date = " $icon system up to date " critical_updates_regex = "(linux|linux-lts|linux-zen)" [[block.click]] ### pop-up a menu showing the available updates. Replace wofi with your favourite menu command. button = "left" cmd = "fakeroot pacman -Qu --dbpath /tmp/checkup-db-i3statusrs-$USER/ | wofi --show dmenu" [[block.click]] ### Updates the block on right click button = "right" update = true pacman only config using warnings with ZFS modules: [[block]] block = "pacman" interval = 600 format = " $icon $pacman updates available " format_singular = " $icon $pacman update available " format_up_to_date = " $icon system up to date " ### If a linux update is available, but no ZFS package, it won't be possible to ### actually perform a system upgrade, so we show a warning. warning_updates_regex = "(linux|linux-lts|linux-zen)" ### If ZFS is available, we know that we can and should do an upgrade, so we show ### the status as critical. critical_updates_regex = "(zfs|zfs-lts)" pacman and AUR helper config: [[block]] block = "pacman" interval = 600 error_interval = 300 format = " $icon $pacman + $aur = $both updates available " format_singular = " $icon $both update available " format_up_to_date = " $icon system up to date " critical_updates_regex = "(linux|linux-lts|linux-zen)" ### aur_command should output available updates to stdout (ie behave as echo -ne "update\n") aur_command = "yay -Qua" Icons Used o update pomodoro A pomodoro timer Technique There are six steps in the original technique: 1) Decide on the task to be done. 2) Set the pomodoro timer (traditionally to 25 minutes). 3) Work on the task. 4) End work when the timer rings and put a checkmark on a piece of paper. 5) If you have fewer than four checkmarks, take a short break (3-5 minutes) and then return to step 2. 6) After four pomodoros, take a longer break (15-30 minutes), reset your checkmark count to zero, then go to step 1. Configuration Key Values Default ----------------------------------------------------------------------------- format A string to customise the " $icon{ $message|} " output of this block. message Message when timer expires "Pomodoro over! Take a break!" break_message Message when break is over "Break over! Time to work!" notify_cmd A shell command to run as a None notifier. {msg} will be substituted with either message or break_message. blocking_cmd Is notify_cmd blocking? If false it is, then pomodoro block will wait until the command finishes before proceeding. Otherwise, you will have to click on the block in order to proceed. Placeholder Value Type ------------------------------------- icon A static icon Icon message Current message Text Example Use swaynag as a notifier: [[block]] block = "pomodoro" notify_cmd = "swaynag -m '{msg}'" blocking_cmd = true Use notify-send as a notifier: [[block]] block = "pomodoro" notify_cmd = "notify-send '{msg}'" blocking_cmd = false Icons Used o pomodoro o pomodoro_started o pomodoro_stopped o pomodoro_paused o pomodoro_break TODO o Use different icons. o Use format strings. privacy Privacy Monitor Configuration Key Values Default ----------------------------------------------------------------------------- driver The configuration of Required a driver (see below). format Format string. "{ $icon_audio |}{ $icon_audio_sink |}{ $icon_video |}{ $icon_webcam |}{ $icon_unknown |}" format_alt Format string. "{ $icon_audio $info_audio |}{ $icon_audio_sink $info_audio_sink |}{ $icon_video $info_video |}{ $icon_webcam $info_webcam |}{ $icon_unknown $info_unknown |}" pipewire Options (requires the pipewire feature to be enabled) Key Values Required Default ------------------------------------------------------------------------------------- name pipewire Yes None exclude_output An output node to No [] ignore, example: ["HD Pro Webcam C920"] exclude_input An input node to No [] ignore, example: ["openrgb"] display Which node field No name should be used as a display name, options: name, description, nickname vl4 Options Key Values Required Default --------------------------------------------------------------------------------------- name vl4 Yes None exclude_device A device to ignore, No [] example: ["/dev/video5"] exclude_consumer Processes to ignore No ["pipewire", "wireplumber"] Available Format Keys Placeholder Value Type Unit ---------------------------------------------------------------------------------------------- icon_{audio,audio_sink,video,webcam,unknown} A static icon Icon - info_{audio,audio_sink,video,webcam,unknown} The mapping of which source Text - are being consumed You can use the suffixes noted above to get the following: Suffix Description ---------------------------------------- audio Captured audio (ex. Mic) audio_sink Audio captured from a sink (ex. openrgb) video Video capture (ex. screen capture) webcam Webcam capture unknown Anything else Available Actions Action Description Default button ----------------------------------------------------------------------------- toggle_format Toggles between format and format_alt Left Example [[block]] block = "privacy" [[block.driver]] name = "v4l" [[block.driver]] name = "pipewire" exclude_input = ["openrgb"] display = "nickname" Icons Used o microphone o volume o xrandr o webcam o unknown rofication The number of pending notifications in rofication-daemon A different color is used if there are critical notifications. Configuration Key Values Default -------------------------------------------------------------------------------- interval Refresh rate in seconds. 1 format A string to customise the " $icon $num.eng(w:1) " output of this block. See below for placeholders. socket_path Socket path for the "/tmp/rofi_notification_daemon" rofication daemon. Supports path expansions e.g. ~. Placeholder Value Type Unit -------------------------------------------- icon A static icon Icon - num Number of Number - pending notifications Example [[block]] block = "rofication" interval = 1 socket_path = "/tmp/rofi_notification_daemon" [[block.click]] button = "left" cmd = "rofication-gui" Icons Used o bell scratchpad Scratchpad indicator Configuration Key Values Default ----------------------------------------------------------------------------- format A string to customise the $icon $count.eng(range:1..) output of this block | Placeholder Value Type Unit -------------------------------------------------------------------------------- icon A static icon Icon - count Number of windows in scratchpad Number - Example [[block]] block = "scratchpad" Icons Used o scratchpad service_status Display the status of a service Right now only systemd is supported. Configuration Key Values Default ------------------------------------------------------------------------------ driver Which init system is running "systemd" the service. Available drivers are: "systemd" service The name of the service Required active_format A string to customise the " $service active " output of this block. See below for available placeholders. inactive_format A string to customise the " $service inactive " output of this block. See below for available placeholders. active_state A valid [State] [State::Idle] inactive_state A valid [State] [State::Critical] Placeholder Value Type Unit -------------------------------------------- service The name of the Text - service Example Example using an icon: [[block]] block = "service_status" service = "cups" active_format = " ^icon_tea " inactive_format = " no ^icon_tea " Example overriding the default inactive_state: [[block]] block = "service_status" service = "shadow" active_format = "" inactive_format = " Integrity of password and group files failed " inactive_state = "Warning" sound Volume level This block displays the volume level (according to PulseAudio or ALSA). Right click to toggle mute, scroll to adjust volume. Requires a PulseAudio installation or alsa-utils for ALSA. Note that if you are using PulseAudio commands (such as pactl) to control your volume, you should select the "pulseaudio" (or "auto") driver to see volume changes that exceed 100%. Configuration Key Values Default ------------------------------------------------------------------------------------- driver "auto", "pulseaudio", "auto" (Pulseaudio with ALSA "alsa". fallback) format A string to customise the " $icon {$volume.eng(w:2) output of this block. See |}" below for available placeholders. format_alt If set, block will switch None between format and format_alt on every click. name PulseAudio device name, or PulseAudio: @DEFAULT_SINK@ / the ALSA control name as ALSA: Master found in the output of amixer -D yourdevice scontrols. device ALSA device name, usually in default the form "hw:X" or "hw:X,Y" where X is the card number and Y is the device number as found in the output of aplay -l. device_kind PulseAudio device kind: "sink" source or sink. natural_mapping When using the ALSA driver, false display the "mapped volume" as given by alsamixer/amixer -M, which represents the volume level more naturally with respect for the human ear. step_width The percent volume level is 5 increased/decreased for the selected audio device when scrolling. Capped automatically at 50. max_vol Max volume in percent that None can be set via scrolling. Note it can still be set above this value if changed by another application. show_volume_when_muted Show the volume even if it false is currently muted. headphones_indicator Change icon when headphones false are plugged in (pulseaudio only) mappings Map output_name to a custom None name. mappings_use_regex Let mappings match using true regex instead of string equality. The replacement will be regex aware and can contain capture groups. active_port_mappings Map active_port to a custom None name. The replacement will be regex aware and can contain capture groups. Placeholder Value Type Unit -------------------------------------------------------------------------------- icon Icon based on volume Icon - volume Current volume. Missing if Number % muted. output_name PulseAudio or ALSA device name Text - output_description PulseAudio device description, Text - will fallback to output_name if no description is available and will be overwritten by mappings (mappings will still use output_name) active_port Active port (same as Text - information in Ports section of pactl list cards). Will be absent if not supported by driver or if mapped to "" in active_port_mappings. Action Default button ------------------------------- toggle_format Left toggle_mute Right volume_down Wheel Down volume_up Wheel Up Examples Change the default scrolling step width to 3 percent: [[block]] block = "sound" step_width = 3 Change the output name shown: [[block]] block = "sound" format = " $icon $output_name{ $volume|} " [block.mappings] "alsa_output.usb-Harman_Multimedia_JBL_Pebbles_1.0.0-00.analog-stereo" = "Speakers" "alsa_output.pci-0000_00_1b.0.analog-stereo" = "Headset" Since the default value for the device_kind key is sink, to display microphone block you have to use the source value: [[block]] block = "sound" driver = "pulseaudio" device_kind = "source" Display warning in block if microphone if using the wrong port: [[block]] block = "sound" driver = "pulseaudio" device_kind = "source" format = " $icon { $volume|} {$active_port |}" [block.active_port_mappings] "analog-input-rear-mic" = "" # Mapping to an empty string makes `$active_port` absent "analog-input-front-mic" = "ERR!" Icons Used o microphone_muted (as a progression) o microphone (as a progression) o volume_muted (as a progression) o volume (as a progression) o headphones speedtest Ping, download, and upload speeds This block which requires speedtest-cli . Configuration Key Values Default ----------------------------------------------------------------------------- format A string to customise the " ^icon_ping $ping output of this block. See ^icon_net_down $speed_down below for available ^icon_net_up $speed_up " placeholders. interval Update interval in seconds 1800 Placeholder Value Type Unit -------------------------------------------------------- ping Ping delay Number Seconds speed_down Download speed Number Bits per second speed_up Upload speed Number Bits per second Example Show only ping (with an icon) [[block]] block = "speedtest" interval = 1800 format = " ^icon_ping $ping " Hide ping and display speed in bytes per second each using 4 characters (without icons) [[block]] block = "speedtest" interval = 1800 format = " $speed_down.eng(w:4,u:B) $speed_up(w:4,u:B) " Icons Used o ping o net_down o net_up taskwarrior The number of tasks from the taskwarrior list Clicking the right mouse button on the icon cycles the view of the block through the user's filters. Configuration Key Values Default ------------------------------------------------------------------------------------- interval Update interval in seconds 600 (10min) warning_threshold The threshold of pending (or 10 started) tasks when the block turns into a warning state critical_threshold The threshold of pending (or 20 started) tasks when the block turns into a critical state filters A list of tables with the [{name = "pending", filter = keys name and filter. filter "-COMPLETED -DELETED"}] specifies the criteria that must be met for a task to be counted towards this filter. format A string to customise the " $icon $count.eng(w:1) " output of this block. See below for available placeholders. format_singular Same as format but for when " $icon $count.eng(w:1) " exactly one task is pending. format_everything_done Same as format but for when " $icon $count.eng(w:1) " all tasks are completed. data_location Directory in which "~/.task" taskwarrior stores its data files. Supports path expansions e.g. ~. Placeholder Value Type Unit --------------------------------------------------------------------------------- icon A static icon Icon - count The number of tasks matching current filter Number - filter_name The name of current filter Text - Action Default button ----------------------------- next_filter Right Example In this example, block will be hidden if count is zero. [[block]] block = "taskwarrior" interval = 60 format = " $icon count.eng(w:1) tasks " format_singular = " $icon 1 task " format_everything_done = "" warning_threshold = 10 critical_threshold = 20 [[block.filters]] name = "today" filter = "+PENDING +OVERDUE or +DUETODAY" [[block.filters]] name = "some-project" filter = "project:some-project +PENDING" Icons Used o tasks tea_timer Timer Configuration Key Values Default ----------------------------------------------------------------------------- format A string to customise the " $icon output of this block. See {$time.duration(hms:true) below for available |}" placeholders. increment The numbers of seconds to 30 add each time the block is clicked. done_cmd A command to run in sh when None timer finishes. Placeholder Value Type Unit --------------------------------------------------------------------------------- icon A static icon Icon - time The time remaining on the timer Duration - hours The hours remaining on the timer Text h DEPRECATED minutes The minutes remaining on the timer Text mn DEPRECATED seconds The seconds remaining on the timer Text s DEPRECATED time, hours, minutes, and seconds are unset when the timer is inactive. hours, minutes, and seconds have been deprecated in favor of time. Action Default button ---------------------------- increment Left / Wheel Up decrement Wheel Down reset Right Example [[block]] block = "tea_timer" format = " $icon {$minutes:$seconds |}" done_cmd = "notify-send 'Timer Finished'" Icons Used o tea temperature The system temperature This block displays the system temperature, based on libsensors library. This block has two modes: "collapsed", which uses only color as an indicator, and "expanded", which shows the content of a format string. The average, minimum, and maximum temperatures are computed using all sensors displayed by sensors, or optionally filtered by chip and inputs. Requires libsensors and appropriate kernel modules for your hardware. Run sensors command to list available chips and inputs. Note that the colour of the block is always determined by the maximum temperature across all sensors, not the average. You may need to keep this in mind if you have a misbehaving sensor. Configuration Key Values Default ----------------------------------------------------------------------------- format A string to customise the " $icon $average avg, $max output of this block. See max " below for available placeholders format_alt If set, block will switch None between format and format_alt on every click interval Update interval in seconds 5 scale Either "celsius" or "celsius" "fahrenheit" good Maximum temperature to set 20 C (68 F) state to good idle Maximum temperature to set 45 C (113 F) state to idle info Maximum temperature to set 60 C (140 F) state to info warning Maximum temperature to set 80 C (176 F) state to warning. Beyond this temperature, state is set to critical chip Narrows the results to a None given chip name. * may be used as a wildcard. inputs Narrows the results to None individual inputs reported by each chip. Action Description Default button ----------------------------------------------------------------------------- toggle_format Toggles between format and format_alt Left Placeholder Value Type Unit -------------------------------------------------- min Minimum Number Degrees temperature among all inputs average Average Number Degrees temperature among all inputs max Maximum Number Degrees temperature among all inputs Note that when block is collapsed, no placeholders are provided. Example [[block]] block = "temperature" format = " $icon $max max " format_alt = " $icon $min min, $max max, $average avg " interval = 10 chip = "*-isa-*" Icons Used o thermometer time The current time. Configuration Key Values Default --------------------------------------------------------------------------------------------------------------------------------- format Format string. See " $icon https://docs.rs/chrono/0.3.0/chrono/format/strftime/index.html#specifiers $timestamp.datetime() chrono docs for all options. " interval Update interval in seconds 10 timezone A timezone specifier (e.g. "Europe/Lisbon") Local timezone Placeholder Value Type Unit -------------------------------------------------------------------------------- icon A static icon Icon - timestamp The current time Datetime - Action Default button ------------------------------- next_timezone Left prev_timezone Right Example [[block]] block = "time" interval = 60 [block.format] full = " $icon $timestamp.datetime(f:'%a %Y-%m-%d %R %Z', l:fr_BE) " short = " $icon $timestamp.datetime(f:%R) " Non Gregorian calendars You can use calendars other than the Gregorian calendar by adding the calendar specifier in the locale string. When using this feature you can't use chrono style format string, and you should use one of the options provided by the icu4x crate: short, medium, long, full. ** Only available using feature icu_calendar. ** Example [[block]] block = "time" interval = 60 format = "$timestamp.datetime(locale:'fa_IR-u-ca-persian', f:'full')" Icons Used o time toggle A Toggle block You can add commands to be executed to disable the toggle (command_off), and to enable it (command_on). If these command exit with a non-zero status, the block will not be toggled and the block state will be changed to critical to give a visual warning of the failure. You also need to specify a command to determine the state of the toggle (command_state). When the command outputs nothing, the toggle is disabled, otherwise enabled. By specifying the interval property you can let the command_state be executed continuously. To run those commands, the shell form $SHELL environment variable is used. If such variable is not presented, sh is used. Configuration Key Values Default ----------------------------------------------------------------------------- format A string to customise the " $icon " output of this block. See below for available placeholders command_on Shell command to enable the Required toggle command_off Shell command to disable the Required toggle command_state Shell command to determine Required the state. Empty output => No, otherwise => Yes. icon_on Icon override for the toggle "toggle_on" button while on icon_off Icon override for the toggle "toggle_off" button while off interval Update interval in seconds. None If not set, command_state will run only on click. state_on [State] (color) of this [idle][State::Idle] block while on state_off [State] (color) of this [idle][State::Idle] block while off Placeholder Value Type Unit --------------------------------------------------------------------------------- icon Icon based on toggle's state Icon - Action Default button ------------------------ toggle Left Examples This is what can be used to toggle an external monitor configuration: [[block]] block = "toggle" format = " $icon 4k " command_state = "xrandr | grep 'DP1 connected 38' | grep -v eDP1" command_on = "~/.screenlayout/4kmon_default.sh" command_off = "~/.screenlayout/builtin.sh" interval = 5 state_on = "good" state_off = "warning" Icons Used o toggle_off o toggle_on uptime System's uptime This block displays system uptime in terms of two biggest units, so minutes and seconds, or hours and minutes or days and hours or weeks and days. Configuration Key Values Default ----------------------------------------------------------------------------- format A string to customise the output of this " $icon block. See below for available $uptime " placeholders interval Update interval in seconds 60 Placeholder Value Type Unit --------------------------------------------------- icon A static icon Icon - text DEPRECATED Current uptime Text - uptime Current uptime Duration - text has been deprecated in favor of uptime. Example [[block]] block = "uptime" interval = 3600 # update every hour Used Icons o uptime vpn Shows the current connection status for VPN networks This widget toggles the connection on left click. Configuration Key Values Default ---------------------------------------------------------------------------------- driver Which vpn should be used . "nordvpn" Available drivers are: "nordvpn" and "mullvad" interval Update interval in seconds. 10 format_connected A string to customise the " VPN: $icon " output in case the network is connected. See below for available placeholders. format_disconnected A string to customise the " VPN: $icon " output in case the network is disconnected. See below for available placeholders. state_connected The widgets state if the vpn info network is connected. state_disconnected The widgets state if the vpn idle network is disconnected Placeholder Value Type Unit ---------------------------------------------------------------------------------- icon A static icon Icon - country Country currently connected to Text - flag Country specific flag (depends on a font Text - supporting them) Action Default button Description --------------------------------------------- toggle Left toggles the vpn network connection Drivers nordvpn Behind the scenes the nordvpn driver uses the nordvpn command line binary. In order for this to work properly the binary should be executable without root privileges. Mullvad Behind the scenes the mullvad driver uses the mullvad command line binary. In order for this to work properly the binary should be executable and mullvad daemon should be running. Example Shows the current vpn network state: [[block]] block = "vpn" driver = "nordvpn" interval = 10 format_connected = "VPN: $icon " format_disconnected = "VPN: $icon " state_connected = "good" state_disconnected = "warning" Possible values for state_connected and state_disconnected: warning critical good info idle Icons Used o net_vpn o net_wired o net_down o country code flags (if supported by font) Flags: They are not icons but unicode glyphs. You will need a font that includes them. Tested with: watson Watson statistics Watson is a simple CLI time tracking application. This block will show the name of your current active project, tags and optionally recorded time. Clicking the widget will toggle the show_time variable dynamically. Configuration Key Values Default ------------------------------------------------------------------------------ format A string to customise the " $text |" output of this block. See below for available placeholders show_time Whether to show recorded false time. state_path Path to the Watson state $XDG_CONFIG_HOME/watson/state file. Supports path expansions e.g. ~. interval Update interval, in seconds. 60 Placeholder Value Type Unit --------------------------------------------- text Current activity Text - Action Description Default button -------------------------------------------------------- toggle_show_time Toggle the value of Left show_time Example [[block]] block = "watson" show_time = true state_path = "~/.config/watson/state" TODO o Extend functionality: start / stop watson using this block weather Current weather This block displays local weather and temperature information. In order to use this block, you will need access to a supported weather API service. At the time of writing, OpenWeatherMap, met.no, and the US National Weather Service are supported. Configuring this block requires configuring a weather service, which may require API keys and other parameters. If using the autolocate feature, set the autolocate update interval such that you do not exceed ipapi.co's free daily limit of 1000 hits. Or use autolocate_interval = "once" to only run on initialization. Configuration Key Values Default ---------------------------------------------------------------------------------- service The configuration of a Required weather service (see below). format A string to customise the " $icon $weather $temp " output of this block. See below for available placeholders. Text may need to be escaped, refer to Escaping Text. format_alt If set, block will switch None between format and format_alt on every click interval Update interval, in seconds. 600 autolocate Gets your location using the false ipapi.co IP location service (no API key required). If the API call fails then the block will fallback to service specific location config. autolocate_interval Update interval for interval autolocate in seconds or "once" OpenWeatherMap Options To use the service you will need a (free) API key. Key Values Required Default -------------------------------------------------------------------------------------------------------------------------- name openweathermap. Yes None api_key Your OpenWeatherMap API key. Yes None coordinates GPS latitude longitude coordinates as a tuple, example: Yes* None ["39.2362","9.3317"] city_id OpenWeatherMap's ID for the city. (Deprecated) Yes* None place OpenWeatherMap `By {city name},{state code},{country Yes* None code}' search query. See https://openweathermap.org/api/geocoding-api#direct_name here . Consumes an additional API call zip OpenWeatherMap `By {zip code},{country code}' search Yes* None query. See https://openweathermap.org/api/geocoding-api#direct_zip here . Consumes an additional API call units Either "metric" or "imperial". No "metric" lang Language code. See No "en" https://openweathermap.org/current#multi here . Currently only affects weather_verbose key. forecast_hours How many hours should be forecast (must be increments of No 12 3 hours, max 120 hours) One of coordinates, city_id, place, or zip is required. If more than one are supplied, coordinates takes precedence over city_id which takes precedence over place which takes precedence over zip. The options api_key, city_id, place, zip, can be omitted from configuration, in which case they must be provided in the environment variables OPENWEATHERMAP_API_KEY, OPENWEATHERMAP_CITY_ID, OPENWEATHERMAP_PLACE, OPENWEATHERMAP_ZIP. Forecasts are only fetched if forecast_hours > 0 and the format has keys related to forecast. met.no Options Key Values Required Default -------------------------------------------------------------------------------------- name metno. Yes None coordinates GPS latitude Required if autolocate None longitude = false coordinates as a tuple, example: ["39.2362","9.3317"] lang Language code: en, No en nn or nb altitude Meters above sea No Approximated by level of the ground server forecast_hours How many hours No 12 should be forecast Met.no does not support location name, but if autolocate is enabled then autolocate's city value is used. US National Weather Service Options Key Values Required Default -------------------------------------------------------------------------------------- name nws. Yes None coordinates GPS latitude Required if autolocate None longitude = false coordinates as a tuple, example: ["39.2362","9.3317"] forecast_hours How many hours No 12 should be forecast units Either "metric" or No "metric" "imperial". Forecasts gather statistics from each hour between now and the forecast_hours value, and provide predicted weather at the set number of hours into the future. Available Format Keys Key Value Type Unit ------------------------------------------------------------------------------------------------- location Location name (exact format depends on Text - the service) icon{,_ffin} Icon representing the weather Icon - weather{,_ffin} Textual brief description of the Text - weather, e.g. "Raining" weather_verbose{,_ffin} Textual verbose description of the Text - weather, e.g. "overcast clouds" temp{,_{favg,fmin,fmax,ffin}} Temperature Number degrees apparent{,_{favg,fmin,fmax,ffin}} Australian Apparent Temperature Number degrees humidity{,_{favg,fmin,fmax,ffin}} Humidity Number % wind{,_{favg,fmin,fmax,ffin}} Wind speed Number - wind_kmh{,_{favg,fmin,fmax,ffin}} Wind speed. The wind speed in km/h Number - direction{,_{favg,fmin,fmax,ffin}} Wind direction, e.g. "NE" Text - You can use the suffixes noted above to get the following: Suffix Description -------------------------------- None Current weather _favg Average forecast value _fmin Minimum forecast value _fmax Maximum forecast value _ffin Final forecast value Action Description Default button ----------------------------------------------------------------------------- toggle_format Toggles between format and format_alt Left Example Show detailed weather in San Francisco through the OpenWeatherMap service: [[block]] block = "weather" format = " $icon $weather ($location) $temp, $wind m/s $direction " format_alt = " $icon_ffin Forecast (9 hour avg) {$temp_favg ({$temp_fmin}-{$temp_fmax})|Unavailable} " [block.service] name = "openweathermap" api_key = "XXX" city_id = "5398563" units = "metric" forecast_hours = 9 Used Icons o weather_sun (when weather is reported as "Clear" during the day) o weather_moon (when weather is reported as "Clear" at night) o weather_clouds (when weather is reported as "Clouds" during the day) o weather_clouds_night (when weather is reported as "Clouds" at night) o weather_fog (when weather is reported as "Fog" or "Mist" during the day) o weather_fog_night (when weather is reported as "Fog" or "Mist" at night) o weather_rain (when weather is reported as "Rain" or "Drizzle" during the day) o weather_rain_night (when weather is reported as "Rain" or "Drizzle" at night) o weather_snow (when weather is reported as "Snow") o weather_thunder (when weather is reported as "Thunderstorm" during the day) o weather_thunder_night (when weather is reported as "Thunderstorm" at night) xrandr X11 screen information X11 screen information (name, brightness, resolution). With a click you can toggle through your active screens and with wheel up and down you can adjust the selected screens brightness. Regarding brightness control, xrandr changes the brightness of the display using gamma rather than changing the brightness in hardware, so if that is not desirable then consider using the backlight block instead. NOTE: Some users report issues (e.g. here and here when using this block. The cause is currently unknown, however setting a higher update interval may help. Configuration Key Values Default ----------------------------------------------------------------------------- format A string to customise the " $icon $display output of this block. See $brightness_icon $brightness below for available " placeholders. step_width The steps brightness is 5 in/decreased for the selected screen (When greater than 50 it gets limited to 50). interval Update interval in seconds. 5 Placeholder Value Type Unit --------------------------------------------------------------------------------- icon A static icon Icon - display The name of a monitor Text - brightness The brightness of a monitor Number % brightness_icon A static icon Icon - resolution The resolution of a monitor Text - res_icon A static icon Icon - Action Default button --------------------------------- cycle_outputs Left brightness_up Wheel Up brightness_down Wheel Down Example [[block]] block = "xrandr" format = " $icon $brightness $resolution " Used Icons o xrandr o backlight o resolution NOTES [1] when using notification_count with the dunst driver use dunst > 1.9.0 THEMES Choosing your theme and icon set To use a theme or icon set other than the default, add them to your configuration file like so: [theme] theme = "solarized-dark" [icons] icons = "awesome6" Both the theme and icon set can be loaded from a separate file. [theme] theme = "" [icons] icons = "" where can be either a filename or a full path and will be checked in this order: 1. If full absolute path given, then use it as is: /home/foo/custom_theme.toml 2. If filename given, e.g. "custom_theme.toml", then first check $XDG_CONFIG_HOME/i3status-rust/themes 3. Then look for it in $XDG_DATA_HOME/i3status-rust/themes 4. Otherwise look for it in /usr/share/i3status-rust/themes Notes: - In case with icon sets, the file should be in the icons subdirectory instead of themes. - You can omit the .toml extension while specifying file parameters. - All the predefined themes are provided as files, so you use them as examples of how to write your own themes/icon sets. Available themes Note: screenshots were generated using this config with this swaybar config. o plain (default) [IMAGE: plain] o solarized-dark [IMAGE: solarized-dark] o solarized-light [IMAGE: solarized-light] o slick [IMAGE: slick] o modern [IMAGE: modern] o bad-wolf [IMAGE: bad-wolf] o gruvbox-light [IMAGE: gruvbox-light] o gruvbox-dark [IMAGE: gruvbox-dark] o space-villain [IMAGE: space-villain] o native (like plain with no background and native separators) [IMAGE: native] o semi-native (like native but with background) [IMAGE: semi-native] o nord-dark (polar night) [IMAGE: nord-dark] o dracula [IMAGE: dracula] o srcery [IMAGE: srcery] o ctp-frappe [IMAGE: ctp-frappe] o ctp-latte [IMAGE: ctp-latte] o ctp-macchiato [IMAGE: ctp-macchiato] o ctp-mocha [IMAGE: ctp-mocha] Available icon sets o none (default. Uses text labels instead of icons) o awesome4 (Font Awesome 4.x) o awesome5 (Font Awesome 5.x) o awesome6 (Font Awesome 6.x) o emoji o material o material-nf (Any font from Nerd Fonts collection) Note: In order to use the material icon set, you need a patched material icons font which can be found https://gist.github.com/draoncc/3c20d8d4262892ccd2e227eefeafa8ef/raw/3e6e12c213fba1ec28aaa26430c3606874754c30/MaterialIcons- Regular-for-inline.ttf here <>. Make sure to pass it in your i3 configuration bar block. Overriding themes and icon sets Create a block in the configuration called theme or icons like so: [theme] theme = "solarized-dark" [theme.overrides] # Example: redefine `idle` colors idle_bg = "#123456" idle_fg = "#abcdef" # Example: swap `good` and `warning` colors good_fg = { link = "warning_fg" } good_bg = { link = "warning_bg" } warning_fg = { link = "good_fg" } warning_bg = { link = "good_bg" } [icons] icons = "awesome6" [icons.overrides] bat = [ "| |", "|1/4|", "|1/2|", "|3/4|", "|X|", ] bat_charging = "|^|" Besides global overrides you may also use per-block overrides using the theme_overrides, icons_overrides and icons_format options available for all blocks. For example: [[block]] block = "cpu" icons_format = "{icon}" [block.theme_overrides] idle_bg = "#123456" idle_fg = "#abcdef" [block.icons_overrides] cpu_boost_on = "ON" cpu_boost_off = "OFF" Available theme overrides All bg and fg overrides are html hex color codes like #000000 or #789ABC. A fourth byte for alpha (like #acbdef42) works on some systems. 00 is transparent, FF is opaque. The tints are added to every second block counting from the right. They will therefore always brighten the block and never darken it. The alpha channel, if it works, can also be alternated in the same way. Feel free to take a look at the provided color schemes for reference. o idle_bg o idle_fg o good_bg o good_fg o warning_bg o warning_fg o critical_bg o critical_fg o info_bg o info_fg o alternating_tint_bg o alternating_tint_fg o separator_bg o separator_fg o separator o end_separator Available icon overrides These can be directly set to a string containing the desired unicode codepoint(s) or use a TOML escape sequence like "\uf0f3" for up to 4-nibble codepoints and "\U0001f312" for up to 8-nibble codepoints. You can find the codepoints in the documentation of the icon font you're using. Refer to individual block's documentation for a list of used icons or provided icon sets for a complete list of icons. VERSION v0.33.2 AUTHORS Kai Greshake , Contributors on GitHub (https, //github.com/greshake/i3status-rust/graphs/contributors) i3status-rs 0.33.2 i3status-rs(1)