% I3BLOCKS(1)

# NAME
i3blocks - A flexible scheduler for your i3bar blocks

# SYNOPSIS

i3blocks [*options*]

# DESCRIPTION

**i3blocks** allows one to easily describe blocks in a simple format, and
generate a status line for i3bar(1). It handles clicks, signals and time
interval for user scripts.

#OPTIONS
-c <configfile>
:   Specifies an alternate configuration file path. By default, i3blocks looks 
    for configuration files in the following order (note that /etc may be
    prefixed with /usr/local depending on the compilation flags):

        1. ~/.config/i3blocks/config (or $XDG_CONFIG_HOME/i3blocks/config if set)
        2. ~/.i3blocks.conf
        3. /etc/xdg/i3blocks/config (or $XDG_CONFIG_DIRS/i3blocks/config if set)
        4. /etc/i3blocks.conf

-v
:   Log level. This option is cumulative. By default, error messages are
    displayed on stderr. Passed once, a failure during an update is shown
    within the block. Passed twice enables the debug messages on stderr.

-V
:   Print the version and exit.

-h
:   Print the help message and exit.

# CONFIGURATION

The configuration file is an ini file. Each section describes a new block.
A line beginning with a `#` sign is a comment, and empty lines are ignored.
A property is a `key=value` pair per line, with no space around the equal sign.
Properties declared outside a block (i.e. at the beginning of the file)
describe global settings.

Here is an example config file:

    # This is a comment
    interval=5
    color=#00FF00

    [weather]
    command=~/bin/weather.pl
    interval=1800

    [time]
    command=date +%T

To use i3blocks as your status line, define it in a *bar* block of your
`~/i3/config` file:

    bar {
      status_command i3blocks
    }

# BLOCK

The properties used to describe a block are the keys specified in the i3bar
protocol http://i3wm.org/docs/i3bar-protocol.html , plus additional properties
used by **i3blocks** to describe when and how to update a block.
All the supported properties are described below.

The following keys are standard, see
http://i3wm.org/docs/i3bar-protocol.html
for details.

 - `full_text`

 - `short_text`

 - `color`

 - `min_width`

 - `align`

 - `name`

 - `instance`

 - `urgent`

 - `separator`

 - `separator_block_width`

 - `markup`

The following keys are specific to **i3blocks**.

`command`
:	 The command executed by a shell, used to update the block. The expected
	 behavior is described below, in the **COMMAND** section.

`interval`
:    If it is a positive integer, then the block is spawned on startup and the
	 value is used as a time interval in seconds to schedule future updates.
	 If unspecified or 0, the block won't be executed on startup (which is
	 useful to simulate buttons).

	 If "*once*" (or -1), the block will be executed only on startup (note that a
	 click or signal will still trigger an update).

	 If "*repeat*" (or -2), the block will be spawned on startup, and as soon as
	 it terminates (useful to repeat blocking commands). Use with caution!

	 If "*persist*" (or -3), the block will be executed only on startup, and
	 updated as soon as it outputs a line. Thus limited to single line updates.

`signal`
:	 The signal number used to update the block. All the real-time (think
     prioritized and queueable) signals are available to the user. The number is
     valid between 1 and N, where SIGRTMIN+N = SIGRTMAX. (Note: there are 31
     real-time signals in Linux.) For instance, `signal=10` means that this
     block will be updated when **i3blocks** receives SIGRTMIN+10.

`label`
: 	An optional label to preprend to the `full_text` after an update.

`format`
:    This property specifies the format of the output text. The default format
     is plain text, as described in the **COMMAND** section.
     If "json" (or 1) is used, the block output is parsed as JSON.

# COMMAND

The value of the `command` key will be passed and executed as is by a shell.

The standard output of the command line is used to update the block content.
Each non-empty line of the output will overwrite the corresponding property:

1. full_text
2. short_text
3. color

For example, this script sets the `full_text` in blue but no `short_text`:

    echo "Here's my label"
    echo
    echo \#0000FF

If the command line returns 0 or 33, the block is updated. Otherwise, it is
considered a failure and the first line (if any) is still displayed. Note that
stderr is ignored. A return code of 33 will set the `urgent` flag to true.

For example, this script prints the battery percentage and sets the urgent flag 
if it is below 10%:

    BAT=`acpi -b | grep -E -o '[0-9][0-9]?%'`
    echo "BAT: $BAT"
    test ${BAT%?} -le 10 && exit 33 || exit 0

When forking a block command, **i3blocks** will set the environment with some 
`BLOCK_*` variables. The following variables are always provided, with
eventually an empty string as the value.

`BLOCK_NAME`
:   The name of the block (usually the section name).

`BLOCK_INSTANCE`
:   An optional argument to the script.

`BLOCK_BUTTON`
:   Mouse button (1, 2 or 3) if the block was clicked.

`BLOCK_X` and `BLOCK_Y`
:   Coordinates where the click occurred, if the block was clicked.

Here is an example using the environment:

    [block]
    command=echo name=$BLOCK_NAME instance=$BLOCK_INSTANCE
    interval=1

    [clickme]
    full_text=Click me!
    command=echo button=$BLOCK_BUTTON x=$BLOCK_X y=$BLOCK_Y
    min_width=button=1 x=1366 y=768
    align=left

Note that **i3blocks** provides a set of optional scripts for convenience, such
as network status, battery check, cpu load, volume, etc.

# EXAMPLES

As an example, here is a close configuration to i3status(1) default settings:

**TODO**

    interval=5
    signal=10

	[ipv6]

    [free]

    [dhcp]

    [vpn]

    [wifi]

    [ethernet]
    min_width=E: 255.255.255.255 (1000 Mbit/s)

    [battery]

    [cpu]

    [datetime]

The following block shows the usage of `signal` with some i3(1) bindings
which adjust the volume, before issuing a `pkill -RTMIN+1 i3blocks`:

    [volume]
    command=echo -n 'Volume: '; amixer get Master | grep -E -o '[0-9][0-9]?%'
    interval=once
    signal=1
    # no interval, only check on SIGRTMIN+1

Here is an example of a very minimalist config, assuming you have a bunch of
scripts under `~/bin/blocks/` with the same name as the blocks:

    command=~/bin/blocks/$BLOCK_NAME
    interval=1

    [free]
    [wifi]
    [ethernet]
    [battery]
    [cpu]
    [datetime]

# SEE ALSO

The development of i3blocks takes place on [Github](https://github.com/vivien/i3blocks).

The [wiki](https://github.com/vivien/i3blocks/wiki) is a good
source of examples for blocks and screenshots.

`i3` (1), `i3bar` (1), `i3status` (1)

# Reporting Bugs

Please report bugs on the [issue tracker](https://github.com/vivien/i3blocks/issues).

# Known Bugs

None.

# AUTHOR

Written by Vivien Didelot <vivien.didelot@gmail.com>.

# COPYRIGHT

Copyright (C) 2014 Vivien Didelot <vivien.didelot@gmail.com>

License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.

This is free software: you are free to change and redistribute it. There is NO 
WARRANTY, to the extent permitted by law.