BEVELBAR(1)

📦 version 25.08, in nixos 26.05, nixpkgs unstable

💅 NAME 💅

okay bestie, this is bevelbar(1) from the General Commands Manual. The command is bevelbar — an X11 status bar with beveled borders. It’s giving classic pseudo-3D glam, no cap. 💅✨

✨ SYNOPSIS ✨

bevelbar [OPTION ...] widget ...

🌸 DESCRIPTION 🌸

bevelbar draws an X11 status bar using classic pseudo-3D beveled borders. Iconic retro desktop energy, fr fr. 🎀

🎀 OPTIONS 🎀

Colors are specified as strings that can be understood by XftColorAllocName(3), e.g. #112233 or red.

💖 Basic properties and colors 💖

-d — use vertical layout. (The mnemonic is “d” for “downwards”, because -v was already taken.) iykyk
-h horizontal_position — specify the horizontal position of the bar. horizontal_position must be one of left, center or right. Defaults to center.
-v vertical_position — specify the vertical position of the bar. vertical_position must be one of top, center or bottom. Defaults to bottom.
-H horizontal_margin — the windows' minimum distance to the screen edge in number of pixels. This option is an integer. Both default values are 5.
-V vertical_margin — the windows' minimum distance to the screen edge in number of pixels. This option is an integer. Both default values are 5.
-b outer_bevel — size in pixels of the bevel to draw. This option is an integer. Can be 0 to not draw any bevel at all. Both default values are 2.
-B inner_bevel — size in pixels of the bevel to draw. This option is an integer. Can be 0 to not draw any bevel at all. inner_bevel refers to the bevel of individual segments. Both default values are 2.
-m seg_margin — segments can have a margin (both horizontally and vertically) around them, which is set by this option. This option is an integer value and measured in pixels. Defaults to 1.
-e seg_size_empty — defines the size of empty segments. This option is an integer value and measured in pixels. The seg_margin value of adjacent segments will be set to 0, i.e. if you draw an empty segment, you really get a space of seg_size_empty pixels. Defaults to 7.
-f font — Xft font descriptor. Defaults to Misc Fixed:pixelsize=13:style=bold.
-p col_plateau — color of the plateau. This is the space between and around segments. Defaults to #a0a0a0.
-o col_outer_bright — bright color of the global outer border. The bright color will be used on the left and top. Defaults to #d6d6d6.
-O col_outer_dark — dark color of the global outer border. The dark color will be used at the bottom and on the right. Defaults to #535353.
-C — this makes bevelbar print its “runtime configuration” and then quit. Currently, this only prints the height of the drawable area, which depends on the font size. If you want to display images, this option can be used to determine an appropriate image size.

🦋 Styles 🦋

Following these basic options, you can define different styles. Throughout your input data, you can switch styles. Ten styles are available, six of which have default values (see below).

-s index — select a style to change. Style indexes range from 0 to 9, inclusively.
-c color — use up to four times to change the colors of the selected style. The colors are used like this (and in this order):
col_segment_background
col_segment_foreground — background color and text color.
col_segment_bright
col_segment_dark — similar to the colors of the global outer border, these options set the colors of the borders of individual segments.

For example, to set style 7 to a background color of red, a text color of green, a bright segment color of yellow, and a dark segment color of black, you would have to use:

-s 7 -c red -c green -c yellow -c black

As mentioned above, there are six predefined styles. They have the following values:

-s 0 -c "#cbaa94" -c "#000000" -c "#d6d6d6" -c "#535353"
-s 1 -c "#a68b79" -c "#000000" -c "#535353" -c "#d6d6d6"
-s 2 -c "#a0a0a0" -c "#000000" -c "#d6d6d6" -c "#535353"
-s 3 -c "#828282" -c "#000000" -c "#535353" -c "#d6d6d6"
-s 4 -c "#ff0000" -c "#ffffff" -c "#d6d6d6" -c "#535353"
-s 5 -c "#ff0000" -c "#ffffff" -c "#535353" -c "#d6d6d6"

🧚 WIDGETS AND DATA FORMAT 🧚

bevelbar will launch each widget in a new process. These are scripts or programs that the user has to provide. They appear in the same order as they are specified on the command line. Their stdout will be a pipe back to bevelbar. bevelbar will restart them when they quit. A widget can draw several segments.

Each widget can request drawing for its own area at any time. This means that, if you have several widgets and want them to update in unison, you must implement this synchronization yourself. An easy way to do this is to have each widget wait for the start of the next second (wallclock).

bevelbar will not try to propagate SIGTERM or other signals to its child processes, because that is a bit fragile. Instead, when bevelbar exits, the pipe (i.e., the child's stdout) will become invalid. Children can detect this situation and exit cleanly, and they usually do so naturally due to their main loop which regularly writes to stdout.

As soon as input is available for a widget, bevelbar will read one complete input block and then draw it. This means that it will block/freeze until the block is complete. Each of the following commands must be terminated by a newline character and must not contain any leading or trailing white space.

An input block starts with an integer which designates the desired monitor to draw the following sub-block on. You can also use a to draw the same input on all monitors.
You can now define multiple segments. Each segment will have its own border. A segment has the format <style><text> (of course, this command has to be terminated by a newline). <style> is an integer to select one of the styles defined by your command line arguments. Style indexes start at 0, so the highest usable style index is 9.
Instead of actual text, you can also request an empty segment using a simple dash: -.
Alternatively, you can begin the line with i, followed by a style as described above. After these two characters, a path to a farbfeld image is expected. For image format and tools please refer to http://tools.suckless.org/farbfeld/.
Lines beginning with I denote inline images. The character after I selects the style, same as for i, then you terminate this sequence with one newline character. After that, the binary farbfeld data must follow. Do not terminate the binary data with another newline.
Multiple segments or empty segments can follow. To designate the end of input for this monitor, you must send an e.
You can now either select another monitor and supply more input, or you can terminate the input by sending an f. This final f causes the bar to be redrawn.

Here's an example:

#!/bin/sh

while sleep 1
do
    echo '0'
    echo "0$(date), current date using style 0"
    echo '1Using style 1 to draw this text'
    echo '0Back to style 0'
    echo '-'
    echo '0We have just drawn an empty segment'
    echo 'e'
    echo '1'
    echo '0Now we are on monitor number 1, drawing with style 0'
    echo 'e'
    echo 'f'
done

Using image files:

#!/bin/sh

while sleep 1
do
    echo 'a'
    echo '0This text appears on all monitors'
    echo 'i2/tmp/some_image.ff'
    echo 'e'
    echo 'f'
done

Inline images:

#!/bin/sh

while sleep 1
do
    echo 'a'
    echo '0This text appears on all monitors'
    echo 'I2'
    cat some_image.ff
    echo 'e'
    echo 'f'
done

🦋 IMAGE FILES 🦋

As described above, you can instruct bevelbar to read a farbfeld image file. It is important to understand that bevelbar will probably read this file multiple times and you, as a client, do not know when this is going to happen. This means that you should not delete the file after you “sent” it to bevelbar. Furthermore, any updates to the image should be done atomically.

A clean way to handle these issues is this:

#!/bin/sh

while sleep 10
do
    create_new_image >/tmp/my_image.new
    mv /tmp/my_image.{new,ff}

    echo a
    echo i0/tmp/my_image.ff
    echo e
    echo f
done

Here, the image will be updated every 10 seconds. Between that, the file will still be available. When it does get updated, the new image will first be written to a temporary file and then renamed to the actual file name. This is an atomic operation.

Image files that do not exist will not be shown and will not create a segment in bevelbar (not even an empty one). This allows you to feed a static list of i items and bevelbar will only show those images that are actually available.

🌈 ENVIRONMENT 🌈

DISPLAY — X11 display to connect to.

👑 LICENSE 👑

bevelbar is released under the MIT license. See the accompanying LICENSE file.

💜 HISTORY 💜

bevelbar was originally written by Peter Hofmann. The project was started in January 2016.

💖 that’s the whole page, bestie — source/version vibe: Debian, dated 2025-08-04. go make that status bar iconic. 🫶✨

📦 where this page comes from

nixos 26.05: bevelbar 25.08
nixpkgs unstable: bevelbar 25.08
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms