barem

Real-world Linux command examples, right in your terminal.

barem prints practical, copy-paste-ready examples for everyday Linux, networking and DevOps commands. Instead of scrolling through a long man page to remember how to exclude a folder in find, follow a service log in journalctl or forward a port with ssh, you ask:

$ barem find size

find - Search for files and directories by name, type, size, time and permissions

# Files bigger than 100 MB anywhere, hide permission errors
find / -type f -size +100M 2>/dev/null

# Files between 10 MB and 50 MB
find . -type f -size +10M -size -50M

# Stay on one filesystem (skip /proc, mounted disks)
find / -xdev -type f -size +500M 2>/dev/null

It currently ships 157 commands and 5,314 examples — about 30 per command, covering the options and flags you actually use at work.

Features

• Real-world examples: realistic file names, paths and hosts instead of <placeholder> soup, ordered from the most common to the more advanced.
• Description first, command second: every example is a # description line followed by the command, so it reads like a well-commented script.
• Keyword filtering: barem tar extract shows only the examples that mention "extract".
• Search everything: barem -s port searches the examples of every command at once.
• Tab completion: bash and zsh completion for command names, keywords and options, built from the example files that are installed.
• Table mode: pipe a command into barem and it formats the output — bordered, aligned columns, usage bars, and a layout that adapts to your terminal width. df -h | barem
• One-command triage: barem help runs 35 read-only checks across storage, memory, cpu, network, system and security, reports only what is actually wrong, and names what the failures add up to rather than leaving you a list.
• Grep-friendly: --oneline prints command # description on one line, and colors switch off automatically when output goes to a pipe or file.
• Zero dependencies: standard library only, Python 3.9+.
• Easy to extend: adding a command means adding one plain text file.

Installation

You need Python 3.9+ and pipx. On Ubuntu/Debian:

sudo apt install pipx
pipx ensurepath        # then open a new terminal

Then:

pipx install barem

pipx creates an isolated virtual environment for the tool and puts the barem command on your PATH, so it cannot collide with anything else you have installed.

pipx upgrade barem             # update
pipx install barem==1.1.0     # a specific version
pipx uninstall barem           # remove

pip install barem works too, inside a virtual environment.

From the repository

To run the unreleased main, or to try a change of your own:

pipx install git+https://github.com/Merab25/Barem.git

Note that pipx upgrade does not re-fetch a git install, so to move such an install forward you reinstall it:

pipx uninstall barem && pipx install git+https://github.com/Merab25/Barem.git

Usage

Keywords are case-insensitive and match the start of a word: port finds "port", "ports" and --port, but not "export" or "report".

Using it with grep

The built-in keyword filter covers most cases, but the output is designed to work with standard tools too:

barem find -1 | grep perm          # one line per example, grep sees command + description
barem find | grep -A1 -i "delete"  # match a description, also print the command below it
barem find | grep -B1 "exec"       # match a command, also print its description above it
barem -s docker -1 | less          # page through a search
barem curl json -1 > curl-json.sh  # save examples as a commented script

Exit codes make it usable in scripts: 0 when examples were printed, 1 for an unknown command or no matches.

barem help

When something is off on a machine, the first few minutes are always the same handful of commands: is the disk full, has memory gone, did a unit fail, is there a default route, does DNS answer. barem help runs 35 checks across six areas, reports only what is actually wrong, and then says what the failures add up to.

$ barem help

+--------------------+-----------+----------+----------------------------------------------+
|       CHECK        |   AREA    |  STATUS  |                    DETAIL                    |
+--------------------+-----------+----------+----------------------------------------------+
|  hypervisor steal  |    cpu    |   bad    |  12.4% of cpu time taken by the hypervisor   |
|                    |           |          |                  since boot                  |
+--------------------+-----------+----------+----------------------------------------------+
|       memory       |  memory   |   bad    |          1.2G of 32G available (4%)          |
+--------------------+-----------+----------+----------------------------------------------+
|  memory pressure   |  memory   |   bad    |  38% of the last minute waiting on memory,   |
|                    |           |          |                    rising                    |
+--------------------+-----------+----------+----------------------------------------------+
|   out of memory    |  memory   |   bad    |      OOM killer hit: postgres, python3       |
+--------------------+-----------+----------+----------------------------------------------+
|     disk space     |  storage  |   bad    |                   /var 94%                   |
+--------------------+-----------+----------+----------------------------------------------+
|    failed units    |  system   |   bad    |             myapp-worker.service             |
+--------------------+-----------+----------+----------------------------------------------+
|        swap        |  memory   |   warn   |           7.9G of 8.0G used (99%)            |
+--------------------+-----------+----------+----------------------------------------------+

 6 critical · 1 to watch · 28 passed · barem help --all shows every check
 likely: the machine is running out of memory (memory, oom, psi_memory, swap)
 -> find the process: ps aux | barem --sort -%mem --top 10
 likely: memory has spilled into swap and the machine is thrashing (swap, psi_memory)
 -> this is slower than being out of memory outright; free some
 next: vmstat 2 5
 next: journalctl -k -b --grep='out of memory'
 next: df -h | barem --sort -use%
 ...and 2 more to look at

The table is the evidence. The likely: lines under it are the point: six red rows there are not six problems, they are one machine running out of memory, and saying so is the difference between a list and a diagnosis.

On a healthy machine it says so in one line and shows nothing else:

$ barem help
 nothing wrong found · 35 passed · barem help --all shows every check

barem check and barem doctor do the same thing. Note that barem --help still prints the usage text — the diagnosis is the bare word, the usage is the flag.

What it checks

Three of those deserve a word, because they are the ones people do not think to run:

• Pressure (/proc/pressure/*) is the kernel saying how much time tasks spent waiting for cpu, memory or disk. It answers "is this machine slow" far better than a utilisation figure does — a disk can be 100% busy and fine, or 20% busy with everything stuck behind it. barem also compares the 10-second and 5-minute windows, so it can tell you whether a problem is rising or easing.
• Hypervisor steal separates "my application is slow" from "the host is oversubscribed and there is nothing in this machine to fix". When steal is high, barem deliberately does not tell you the machine is busy, because it isn't — somebody else is.
• Listen-queue overflows are connections your server refused while looking perfectly healthy from the outside. Nothing else on the machine shows it.

To see every check with its thresholds and the command behind it:

barem help --explain                 # all of them
barem help --explain --area memory   # just one area

Reading it

barem help                      # only what is wrong
barem help --all                # every check, including the ones that passed
barem help --area storage       # one area at a time
barem help --explain            # what each check measures and where the line is

The analysis always reads every result, even when the report is narrowed — memory exhaustion is told by the disk and the journal too, so --area memory still gets the whole picture.

Using it in a script

The exit code says what was found, so it drops into a cron job or a CI step:

barem help || echo "check the machine"
barem help --format json        # the whole diagnosis, machine-readable

The JSON carries more than the table does — every check with its area and status, the analysis, and a one-word verdict of healthy, degraded or critical:

{
  "verdict": "critical",
  "exit_code": 2,
  "counts": { "bad": 6, "warn": 1, "ok": 28, "skipped": 0 },
  "checks": [
    { "key": "memory", "area": "memory", "status": "bad",
      "detail": "1.2G of 32G available (4%)" }
  ],
  "insights": [
    { "headline": "the machine is running out of memory",
      "severity": "bad",
      "evidence": ["memory", "oom", "psi_memory", "swap"],
      "advice": "find the process: ps aux | barem --sort -%mem --top 10" }
  ]
}

What it will not do

Every check is read-only, needs no root, and is given a four-second timeout, so running it can never make a bad situation worse — a hung NFS mount cannot hang the diagnosis. A check whose command is missing reports skipped rather than failing, which is what you get on a container without systemctl or a system without journalctl.

The analysis never invents a finding: a pattern can only fire on checks that already failed on their own, and an empty analysis means the failures do not form a shape anybody has named — which is not the same as the machine being healthy, and is why it never replaces the table.

Table mode

Pipe a command into barem and it formats the output instead of looking anything up:

$ df -h | barem

+----------------+------+------+-------+-------------------------+------------+
|   FILESYSTEM   | SIZE | USED | AVAIL |                   USE%  | MOUNTED ON |
+----------------+------+------+-------+-------------------------+------------+
| /dev/nvme0n1p2 | 468G | 112G |  332G | ||||               25%  |     /      |
+----------------+------+------+-------+-------------------------+------------+
|   /dev/sdb1    | 1.8T | 1.7T |   43G | |||||||||||||||    95%! |   /data    |
+----------------+------+------+-------+-------------------------+------------+
| /dev/nvme0n1p1 | 512M |  62M |  450M | ||                 12%  | /boot/efi  |
+----------------+------+------+-------+-------------------------+------------+
|     tmpfs      |  16G | 2.1M |   16G | |                   1%  |    /run    |
+----------------+------+------+-------+-------------------------+------------+

 4 filesystems · 2.3T total · 1.8T used (80%)

It works out which command produced the text, splits it into columns, decides what each column means — a size, a percentage, a status, a path — and lays it out to the width of your terminal. The commands stay the source of truth; this is only a nicer view of them.

df -i | barem                            # inode usage, with bars
ps aux | barem --sort -%mem --top 10     # replaces an awk and sort pipeline
ss -tlnp | barem                         # listening sockets, aligned
docker ps | barem --symbols              # ● up, ✖ exited
kubectl get pods | barem --where 'status ~ Crash'
free -h | barem --style rounded          # pick a border style
df -h | barem --pct dots --pad 2         # pick a percentage style and more spacing
mount | barem --format md                # a Markdown table
barem run --watch 2 df -h                # re-run and redraw every 2 seconds

Options

Picking a look

barem --styles renders the same table in every style so you can choose by eye. Nine border styles:

And eight ways to draw a percentage:

--pct pipes    |||||                  25%      upright pipes with nothing behind them   (the default)
--pct blocks   █████░░░░░░░░░░░░░░░   25%      solid blocks, accurate to an eighth of a cell
--pct shade    ▓▓▓▓▓░░░░░░░░░░░░░░░   25%      a shaded track, quieter than solid blocks
--pct bracket  [#####...............]   25%    a bracketed meter, [####....]
--pct dots     ●●●●●○○○○○○○○○○○○○○○   25%      filled and hollow dots
--pct line     ━━━━━┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄   25%      a simple rule, drawn and undrawn
--pct ticks    |||||...............   25%      as pipes, on a dotted track
--pct number   25%                             the number on its own, no bar

A percentage is drawn as 20 upright pipes by default, with nothing behind them, so a glance down the column shows which rows are full. --pct picks another of the eight looks. The bar is 20 cells long; --bar-width N changes it, --pad N the spacing inside every cell, --row-gap N blank lines between rows, and --left turns off the centring.

A long bar and a roomy cell are the first things given up when the window is narrow: at 80 columns the bar shortens and the padding tightens by itself rather than a column being dropped, so you still see everything.

How it adapts

Nothing in the output is fixed to 80 columns, and nothing is thrown away. As the window narrows the table gives things up in the order that keeps the most useful information longest: text columns shrink (wrapping, never cutting), then the bars go, then whole columns are dropped — and dropped ones are named under the table so you know to ask for them with --cols. Below about 50 columns a table cannot work at all, so each row becomes a small block instead:

 /dev/sdb1
   Size        1.8T
   Used        1.7T
   Avail       43G
   Use%        95%!  █████████▌
   Mounted On  /data

The column that names the row is never dropped, and it keeps its full width until the layout has run out of columns it could drop instead — giving up a column you can ask back with --cols beats wrapping every name across two lines. Numbers are never wrapped or cut either.

Reading the output

• Borders by default, because they make the columns unmissable: a +---+ frame with a rule between every row, padded so the rows have room to breathe, and the whole table sits in the middle of the window. --style picks another of the nine looks, --styles shows them all, --pad N and --row-gap N change the spacing, and --left puts the table back on the margin.
• Column names are bold and bright while the frame stays dim, so the names and the numbers are what your eye lands on rather than the grid around them.
• Nothing is cropped. A value too wide for its column is wrapped onto as many lines as it needs, breaking at spaces first and then after / , ; : = so a path still reads as a path. --no-wrap goes back to cutting with an ….
• The row's name stands out: the identifying column is emphasised, and it is the last thing the layout narrows, so a name is not wrapped to save a cell somewhere less important.
• Text is centred, numbers right-aligned, so digits still line up where the eye expects them.
• Colour is never the only signal. A critical value is also marked ! whenever colour is off, so the output reads the same in a log file, under NO_COLOR, and for a colourblind reader.
• Values above 100% keep their real number (ps reports 340% for a multi-threaded process) while the bar clamps at full.
• If anything cannot be parsed, the input is printed unchanged. A formatting tool must never be the reason you cannot read your disk usage.

Known commands

Profiles give correct column types without --as: df, df -i, lsblk, lsblk -f, findmnt, ps aux, ps -ef, free, ss, netstat, ip -br a, docker ps, docker images, kubectl get pods, kubectl get nodes, systemctl list-units, systemctl list-unit-files and systemctl list-timers.

Anything else still works: column types are inferred from the data, which is the path that runs for every command nobody wrote a profile for. JSON, JSON lines, CSV, TSV and key=value input are detected automatically, so ip -j addr | barem and cat /etc/os-release | barem both do something sensible.

Add your own profiles as small Python modules in ~/.config/barem/profiles/, each exposing a PROFILE.

Shell completion

barem --completion bash and barem --completion zsh print a completion script. Install it once:

# bash
mkdir -p ~/.local/share/bash-completion/completions
barem --completion bash > ~/.local/share/bash-completion/completions/barem

# zsh, into any directory on your $fpath
barem --completion zsh > "${fpath[1]}/_barem"
rm -f ~/.zcompdump && compinit

Open a new terminal, and TAB completes command names, keywords and options:

$ barem doc<TAB>        # docker
$ barem git reb<TAB>    # rebase
$ barem tar extr<TAB>   # extract  extracting
$ barem --no<TAB>       # --no-color

Candidates come from the example files that are installed rather than from a list baked into the script, so a command or keyword you add is completed without regenerating anything. A keyword already on the line is not offered again.

To try it in the current shell only, without installing:

source <(barem --completion bash)

Available commands

Files and directories

Text processing

Archives and compression

Processes and system

Shell and environment

Users and permissions

Packages

Editors

Disks and filesystems

Networking

Security

DevOps and cloud

Languages and package tools

Databases

Run barem -l for the live list.

Example file format

Each command is one text file in src/barem/examples/, named after the command (find.txt, docker.txt, ...):

## Search for files and directories by name, type, size, time and permissions

# Find files by exact name in the current directory tree
find . -name "config.yaml"

# Web permissions: 755 for directories, 644 for files
find /var/www -type d -exec chmod 755 {} +
find /var/www -type f -exec chmod 644 {} +

• ## ... on the first line is the one-line summary shown by barem -l.
• # ... starts a new example with its description.
• The following line(s) are the command. Several lines under one description belong to the same example.
• Blank lines are ignored.

Adding a command

1. Create src/barem/examples/<command>.txt using the format above.
2. Aim for about 30 examples: the most common use first, then the important options, then advanced and combined usage.
3. Use realistic values (/var/log/nginx/access.log, user@server, 192.168.1.10) instead of <file> placeholders, so examples can be copied and edited quickly.
4. Keep each command on one line.
5. Run the tests. They check that every file has a summary, at least 20 examples, and that every command is valid shell syntax (bash -n).

pytest

The new command shows up automatically in --list, --help, --search and tab completion; no code changes are needed.

Project structure

barem/
├── .github/
│   ├── workflows/ci.yml       # CI: lint, then build + install the wheel and test on 3.9-3.13
│   └── dependabot.yml         # keeps the pinned GitHub Actions current
├── src/barem/
│   ├── __init__.py            # package version (single source of truth)
│   ├── __main__.py            # enables `python -m barem`
│   ├── cli.py                 # argument parsing, file parsing, filtering, output, completion
│   ├── diagnose.py            # `barem help`: the first-try checks and how they are judged
│   ├── completions/           # the bash and zsh completion scripts, shipped too
│   ├── examples/              # one .txt file per command, shipped inside the package
│   └── table/                 # table mode, described in table-mode.md
│       ├── __init__.py        # format_text(text, options), the only public entry point
│       ├── width.py           # display_width, truncation, sanitizing: no other imports
│       ├── model.py           # Column, Kind, Align, Table, Profile
│       ├── humanize.py        # sizes, durations, and the parsers that let them sort
│       ├── styles.py          # the border and percentage style registries
│       ├── theme.py           # colours, thresholds, bars, the ASCII fallback
│       ├── detect.py          # input format detection and profile fingerprinting
│       ├── parse/             # columnar (by position), structured (json/csv), infer
│       ├── layout.py          # the fit / shrink / drop / cards algorithm
│       ├── render.py          # one bordered engine, plus cards, markdown, csv, json
│       ├── runner.py          # `barem run` and --watch
│       └── profiles/          # df, ps, ss, docker, kubectl, systemctl, ...
├── tests/
│   ├── test_cli.py            # parser, example files, CLI behaviour and completion
│   ├── test_docs.py           # the README's tables must match the example files
│   ├── test_table_*.py        # width, parsing, layout, rendering, CLI and golden files
│   ├── test_diagnose.py       # every check judged against real command output
│   ├── fixtures/              # real command output, so tests never run df or ps
│   └── golden/                # each fixture rendered at 40, 60, 80 and 120 columns
├── pyproject.toml             # package metadata, build backend, entry point, ruff config
├── .gitattributes             # keep the tree LF: the examples are read on Linux
├── .editorconfig
├── CHANGELOG.md
├── CONTRIBUTING.md
├── LICENSE
└── README.md

How it works

• Entry point: pyproject.toml declares barem = "barem.cli:main" under [project.scripts]. When the package is installed, pip/pipx generate a small barem executable that calls main().
• Bundled data: the example files live inside the package, so they are included in the wheel. At runtime importlib.resources finds them wherever the package was installed, instead of relying on hard-coded paths.
• Parsing: each file is read line by line into Example(description, commands) objects; filtering is a case-insensitive word-start match against the description and the commands.
• Output: colors are ANSI escape codes, enabled only when stdout is a terminal (sys.stdout.isatty()), so pipes, files and grep always get plain text.
• Completion: the script printed by --completion is a real file in the package, not a string built in Python. On every TAB it calls the hidden barem --complete <words>, which prints one candidate per line. That call is handled before argparse runs, because the words arrive half-typed (--no-c, -) and argparse would try to read them as options.
• Table mode: a command name always means the example lookup, so table mode starts only when standard input is a pipe, or when a table flag says so. Columns are found by character position rather than by split(), because real output defeats splitting — df has a Mounted on header, ps aux holds a whole command line in one column, and docker ps has both. Everything is measured in terminal cells, never characters, and colour is applied last so padding is never wrong by the length of an escape sequence. The design is written up in table-mode.md.
• Isolation: pipx installs the tool in its own virtual environment, so it never conflicts with system Python packages.
• Versioning: the version is defined once in src/barem/__init__.py and read by the build backend (hatchling). A test checks that CHANGELOG.md has a section for it and that the README's install line names the matching tag.

Development

git clone https://github.com/Merab25/Barem.git
cd Barem
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"    # editable install: code and example changes apply immediately

barem find             # try it
pytest                     # run the tests
ruff check .               # lint
ruff format .              # format
python -m build            # build the wheel and sdist into dist/

CI runs those same checks on Python 3.9 through 3.13, then installs the built wheel and smoke-tests the CLI and the generated bash completion script.

To use your local copy as your everyday command, install it with pipx in editable mode:

pipx install -e . --force

See CONTRIBUTING.md before opening a pull request, and CHANGELOG.md for what changed in each release.

Roadmap

• Publish to PyPI (pipx install barem)
• More commands: go, cargo, node, gdb, lvm, iperf3, ethtool, az
• Table profiles for the headerless commands: du -sh *, last, lsof
• Table mode: highlight cells that changed since the last --watch refresh
• Georgian descriptions

Safety note

Some examples change or delete things (rm, find -delete, iptables -F, docker system prune, terraform destroy). Read a command before you run it. Only scan or capture traffic (nmap, tcpdump) on networks you own or have permission to test.

License

MIT