The hacker-friendly status_command for Sway and i3

i3blocks is a feed generator for text based status bars. It executes your command lines and generates a status line from their output. Commands are scheduled at configured time intervals, upon signal reception or on clicks.

The generated line is meant to be displayed by the i3 window manager through its i3bar component, as an alternative to i3status. This program naturally works out of the box with the sway Wayland compositor since it is a drop-in replacement for i3.

i3blocks is meant to be highly flexible but intuitive. No library package is required, just output what your status bar expects, from your favorite programming language and your preferred format.

i3blocks is already packaged for:

• Archlinux: i3blocks in the community repository and i3blocks-git in the AUR

• Gentoo: x11-misc/i3blocks

• Debian: i3blocks

• Ubuntu: i3blocks

• Fedora (COPR): i3blocks

• Void Linux: i3blocks

Or can be installed from source with:

In your i3 configuration file, define i3blocks as the status line command of a new bar block:

For the lazy, you can start from our collection of scripts:

For the picky, you can start a configuration file in one of the following preferred paths:

• $XDG_CONFIG_HOME/i3blocks/config (or ~/.config/i3blocks/config);

• ~/.i3blocks.conf;

• $XDG_CONFIG_DIRS/i3blocks/config (or /etc/xdg/i3blocks/config);

• /etc/i3blocks.conf;

• or any other path that you will specify using the -c option.

Use the example above or dig in the configuration details below.

Now restart i3 with i3-msg restart to apply your changes.

The configuration file uses a simplified INI file format:

In this example, block2 contains a foo property equal to "bar" and a quux property equal to " quuz" (including the leading space). Everything after the equal sign will be part of the value, thus inline comments won’t be stripped out.

At runtime, these properties are simply variables, that are passed along to the status bar program when printing is necessary. However on startup, i3blocks checks some optional properties to eventually setup the scheduling of a command.

If a block specifies a command, then all of its properties are passed as environment variables at execution, which means that the foo=bar property will be available from a shell script with $foo. The output of the command is used to update the values of these variables. The values are reset to default (as defined in the configuration file) before the update, so that blocks get a consistent behavior at each execution.

In order to use i3blocks with i3, its status bar command i3bar expects specific keys. To know how to customize the blocks of your status line, you must refer to the i3bar protocol.

Unless overriden, the section name of the block defines the name key.

Below are examples of static blocks interacting with i3bar.

These are some special properties checked by i3blocks on startup. These will be considered as simple variables at runtime.

command

[pacman]
full_text=c ·
command=echo "· ${full_text~~}"
color=#FFFF00

interval

# Print seconds since 1970-01-01
[epoch]
command=date +%s
interval=1

# Restart i3 on click
[restart]
full_text=Restart
command=i3-msg -q restart
#interval=0

# Fetch the public IP address only on startup
[public-ip]
command=wget -qO - icanhazip.com
interval=once

# Print the last command entered in Bash
[history]
command=inotifywait -qq -e close_write ~/.bash_history; tail -1 ~/.bash_history
interval=repeat

[window]
command=xtitle -s
interval=persist

signal

[caps-lock]
command=xset -q | grep Caps | awk '{ print $2, $3, $4 }'
interval=once
signal=10

bindsym --release Caps_Lock exec pkill -SIGRTMIN+10 i3blocks

format

#!/bin/bash

BAT=$(acpi -b | grep -E -o '[0-9][0-9]?%')

# Full and short texts
echo "Battery: $BAT"
echo "BAT: $BAT"

# Set urgent flag below 5% or use orange below 20%
[ ${BAT%?} -le 5 ] && exit 33
[ ${BAT%?} -le 20 ] && echo "#FF8000"

exit 0

[battery]
command=battery.sh
interval=10

[counter]
_count=0
command=printf '{"full_text":"Counter: %s", "_count":%d}\n' $_count $((_count + 1))
format=json
interval=1

When you click on a block, data such as the button number and coordinates are merged into the block variables.

The data sent on click is detailed in the i3bar protocol.

If the block command isn’t already spawned, it is executed again.

If the value of the block’s interval is persist, then the data is written on the command standard input, one line per click. What gets written depends on the block’s format. The raw format only gets the click button. The JSON format gets all block variables.

Frequently Asked Questions and Troubleshooting.

1. What is a blocklet?

   A blocklet is the configuration of a single block, part of the status line. There are plenty listed in the blocklets page.

2. Can I use my own variables?

   Yes, any variable defined in the block is exported as is to the environment of its command. The foo=bar property can be accessed with $foo from a shell script, ENV["foo"] from Ruby, and so on.

   The IEEE and The Open Group state that "The name space of environment variable names containing lowercase letters is reserved for applications.". i3bar suggests to prefix your own keys with an underscore (_), but it might be more intuitive to use uppercase environment variables, so it is your call to define your own naming convention.

3. Why $foo doesn’t work from the configuration file?

   i3blocks does not do string interpolation of any sort. The definitions found in the configuration file are just raw strings, this means that bar=$baz defines a bar variable equal to literally $baz (a dollar sign followed by "baz").

   String interpolation does work in the command property though, since it is interpreted by a shell which has access to the environment variables.

4. How can I simulate a button?

   This is pretty straightforward actually. Just make sure not to override the full_text, for example:

   [calc-button]
   full_text=Calculator
   command=gnome-calculator >/dev/null

5. Can a block start a GUI application?

   Sure. And if you do not wish your command to block until the application is closed, ask i3 to start it for you with i3-msg -q exec myapp.

6. Why Pango isn’t working?

   The Pango markup requires a Pango font. Make sure you configured i3bar to use a Pango font. For example:

   font pango:Inconsolata, Icons 12

7. Why is printf not working?

   As of i3blocks 1.5, each line from a block output are expected to be terminated with a newline, e.g. with printf "…​\n" from a shell script.

8. Why is the output from my persistent block not displayed?

   Make sure to flush stdout, for example:

   [ruby-loop]
   full_text=Click me
   command=ruby -p -e '$_.prepend("Got button ")' -e 'STDOUT.flush'
   interval=persist

9. Can I use a time interval below 1 second?

   No, the time unit for interval is the second.

   But even though I wouldn’t recommend it, you can still update faster than that with loops:

   [nano1]
   command=sleep .5; date +%N
   interval=repeat
   
   [nano2]
   command=while sleep .5; do date +%N; done
   interval=persist

10. Can I change the block separator?

    Not with i3blocks itself, separators are drawn by i3bar. You can change the separator_symbol in the i3bar configuration.

    Alternatively, you can define static blocks as custom separators in your i3blocks configuration. In the example below, we use the "\xe3\x80\x89" UTF-8 character:

    # Define the custom separator in global properties for boilerplate
    full_text=〉
    align=center
    color=#666666
    separator=false
    separator_block_width=7
    
    [time]
    instance=la
    TZ=America/Los_Angeles
    command=date +%T
    interval=5
    
    [separator]
    
    [time]
    instance=nc
    TZ=Pacific/Noumea
    command=date +%T
    interval=5
    
    [separator]
    
    [time]
    instance=mtl
    TZ=America/Montreal
    command=date +%T
    interval=5

The log level can be increased with the -v option.

If your window manager (and thus this program) is run via systemd, you can inspect the program outputs with journalctl -t <identifier> -f. You may also use this in conjonction with running the program manually with systemd-cat -t <identifier> ./i3blocks.

Alternatively you can redirect the standard output and error streams from the program invokation with:

And inspect the log with tail -f /tmp/i3blocks.err.

See the manpage for details about the command line options and i3blocks usage.

i3blocks is Copyright © Vivien Didelot

See the file COPYING for information of licensing and distribution.