Need help with admiral?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

130 Stars 3 Forks BSD 2-Clause "Simplified" License 44 Commits 4 Opened issues


Executes multiple programs concurrently to generate output for bars

Services available


Need anything else?

Contributors list

# 72,245
37 commits
# 313,108
3 commits
# 276,078
2 commits


Executes multiple programs concurrently to generate output for bars

Table of Contents


If you just want to get Admiral running, skip to the next section.

Programs like lemonbar and i3bar have become popular in recent years, and with good reason. For those of you who are unfamiliar with them, these programs read from standard input and then output what they receive on a bar. For the most part, their output is identical to their input, but they accept some format strings which allow the user to specify things like colors, justification, and clickable areas.

The advantage of this system is that it is very powerful. The disadvantage is that it can be rather difficult to configure.

A typical bar script looks something like this: a shell script, probably bash, is used to collect and format the output of various commands. This is done in an infinite loop, probably ending with

sleep 0.1
or something similar. The output of this script is then piped into the bar program, which receives a new line (which may be identical to its previous line) ten times per second.

The main problem with this method is that it's rather difficult to handle timing correctly. A counter showing the number of outdated programs on the system can be updated less frequently than a clock.

Actually, a previous bar script I had contained both of the aforementioned items. One day, I noticed the clock on my bar had stopped working. The cause? The internet had died. This prevented the package counter command (

checkupdates | wc -l
) from ever finishing, which caused the entire bar to stop working.

Another major problem is that shell scripts of these types are bug-prone and tend to become very bloated. Admiral has a declarative style which allows you to configure your bar with ease and avoid pesky bugs.

What Admiral Does

Admiral runs programs specified by the user and prints their output. It allows for a clear separation of different sections, which simplifies configuration.

The best part? Each program is run in its own thread. This means that each section is updated independently of the other sections. It also means that if something fails, it fails independently of the other sections. That example where the clock stopped? This would never happen with Admiral. Sure,

would still hang indefinitely and prevent that number from changing. But the clock (and the rest of the bar) would be unaffected.

Admiral also limits its output. Whenever one of its programs updates, it checks to see if anything has actually changed since it last printed a message. If nothing has changed, Admiral prints nothing—this limits the amount of refreshing that your bar program has to do.

Getting Started


  • rustc
    — the Rust compiler
  • cargo
    — the Rust package manager
  • git
    (optional but recommended)

These can probably be installed via your distribution's package manager. If the Rust compiler and Cargo are not packaged for your distro, you can download them here.


  1. Clone this repository with
    git clone
    • Alternatively, a .zip file of the master branch can be downloaded here
  2. cd
    into the newly-created
  3. Run
    cargo build --release

This will create an

excutable in the
directory. You may want to copy this to somewhere in your
, like

You may then copy the provided

directory to
(or your
directory, if you have that environment variable set).


Configuration is done with an

file. This file is looked for in
, if that environment variable is set). Alternatively, a configuration file may be specified with the
flag, e.g.
admiral -c /path/to/file.toml

An example

(complete with the
) is included in this repository.


is the section where Admiral's output is configured. It has one required entry:
. Here is an example
items = ["music", "workspaces", "clock"]

Each entry in the

table specifies a section of the config file that will be run. Note that the order specified here is the order that Admiral will use for the scripts' output.

Sections of the admiral.toml

Each section of the

contains a command that produces some output; you can use shell scripts, python scripts, executable binaries, etc.

Here is an example script section:

path = "date '+%I:%M %p'"
reload = 1


is the only required entry for a script. The specified command is executed by a shell running in the same directory as the
. So,
path = "./"
will run the
in the same directory as the
, and
path = "echo 'Hello, world!'"
will output "Hello, world!" using your shell. Note that the shell is determined via the
environment variable.


is an optional variable that specifies an alternate shell to execute commands with. The default shell is your
environment variable. Using an alternate shell may be useful if you wish to leverage features of a specific shell for a certain command. An example use is
shell = "/usr/bin/fish"



value is the optional duration in seconds between each execution of the script. It may be either an integer such as
or a float such as

If no

value is specified, and
is not set to
, this indicates that the script should never exit. It will be run, and each line it outputs will be used separately. This is for commands such as
xtitle -s
, which handle polling themselves and output new information on a new line. If the process is killed, it will automatically be restarted.


is an optional boolean variable. It is set to false by default. It is for scripts that only need to be run once. Here is an example:
path = "echo '%{c}'"
static = true

This script is used to add a format sequence for

. It only needs to be run once, and its output will never change.


Bars expect newline characters to be used only at the end of each full line of input; Admiral tries to respect this by trimming newline characters from the output of scripts. Users should be aware of how this is handled:

  • Both

    characters are removed from the start and end of a script's output
  • If no

    value is specified and
    is false, Admiral uses each line produced by the script. This means that each line meant to be displayed must end in either
    . However, these characters will still be stripped from Admiral's output so as to keep its complete output on a single line.


An example

directory is included with admiral. The example is designed for use with bspwm, and also relies on xtitle to get the window title. Its output is designed to be piped to
. The command
admiral | lemonbar -g x30 | sh
should work for a demonstration, although a greater number of clickable areas may need to be specified with
lemonbar -a
if you have more than 8 desktops.

The example bar has three sections: BSPWM workspace information, the current window title, and the current time. The workspace section uses the letters

, and
to represent free (empty), occupied, and urgent desktops, respectively. Lowercase letters represent unfocused desktops, and an uppercase letter represents the focused desktop.

This workspace section is clickable. Left-clicking on a letter will switch to the corresponding desktop. Scrolling up with the mouse wheel while the cursor is over the workspace section will switch to the previous desktop, and scrolling down with the mouse wheel will switch to the next desktop.

This directory contains two files: an

file and
. Let's look at the example


This is the provided

items = ["left", "workspaces",
         "center", "title",
         "right", "clock"]

Six scripts are listed. Three are used to provide information, and the other three are used for formatting the output.


These are the first three scripts listed in the example

path = "./"

[title] path = "xtitle -s -t 100"

[clock] path = "date '+%-I:%M %p '" reload = 1
is a Bash script that parses the output of
bspc subscribe report
and converts it into a clickable, human-readable format for
. Because
bspc subscribe report
(and therefore
) never exits, no reload value is specified.


These are the last three scripts:

path = "echo '%{l}'"
static = true

[center] path = "echo '%{c}'" static = true

[right] path = "echo '%{r}'" static = true

These output format strings to be interpreted by

. As their output only needs to be captured once,
is set to
. Remember that
removes trailing newline characters; this means that using
rather than
echo -n
will still work here.

Keeping the format strings outside of the main scripts allows for quicker, easier formatting.


  • Specifying a toml file in the current directory as
    admiral -c admiral.toml
    causes scripts with relative paths to fail.
    • Workaround: Give the "directory name" as well, i.e.
      admiral -c ./admiral.toml

Any bugs that are found should be reported here.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.