The hacker-friendlystatus_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 thei3 window manager through its i3bar component, as an alternative to i3status.This program naturally works out of the box with thesway 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 andi3blocks-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 thestatus line command of a new bar block:

For the lazy, you can start fromour 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 withi3-msg restart to apply your changes.

The configuration file uses a simplified INI file format:

In this example,block2 contains afoo property equal to"bar" and aquux 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 thefoo=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 commandi3bar expects specific keys.To know how to customize the blocks of your status line, you must refer to thei3bar protocol.

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

Below are examples of static blocks interacting withi3bar.

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

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 thei3bar protocol.

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

If the value of the block’s interval ispersist, 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 theblocklets 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.Thefoo=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 thatbar=$baz defines abar variable equal to literally$baz (a dollar sign followed by "baz").

   String interpolation does work in thecommand 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 thefull_text, for example:

   [calc-button]full_text=Calculatorcommand=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 withi3-msg -q exec myapp.

6. Why Pango isn’t working?

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

   font pango:Inconsolata, Icons 12

7. Why isprintf not working?

   As of i3blocks 1.5, each line from a block output are expected to be terminated with a newline, e.g. withprintf "…​\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 mecommand=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 +%Ninterval=repeat[nano2]command=while sleep .5; do date +%N; doneinterval=persist

10. Can I change the block separator?

    Not with i3blocks itself, separators are drawn by i3bar.You can change theseparator_symbol in thei3bar 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 boilerplatefull_text=〉align=centercolor=#666666separator=falseseparator_block_width=7[time]instance=laTZ=America/Los_Angelescommand=date +%Tinterval=5[separator][time]instance=ncTZ=Pacific/Noumeacommand=date +%Tinterval=5[separator][time]instance=mtlTZ=America/Montrealcommand=date +%Tinterval=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 withjournalctl -t <identifier> -f.You may also use this in conjonction with running the program manually withsystemd-cat -t <identifier> ./i3blocks.

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

And inspect the log withtail -f /tmp/i3blocks.err.

See themanpage 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.