Shellbase

              ,,                 ,,    ,,  ,,
            `7MM               `7MM  `7MM *MM
              MM                 MM    MM  MM
     ,pP"Ybd  MMpMMMb.  .gP"Ya   MM    MM  MM,dMMb.   ,6"Yb.  ,pP"Ybd  .gP"Ya
     8I   `"  MM    MM ,M'   Yb  MM    MM  MM    `Mb 8)   MM  8I   `" ,M'   Yb
     `YMMMa.  MM    MM 8M""""""  MM    MM  MM     M8  ,pm9MM  `YMMMa. 8M""""""
     L.   I8  MM    MM YM.    ,  MM    MM  MM.   ,M9 8M   MM  L.   I8 YM.    ,
     M9mmmP'.JMML  JMML.`Mbmmd'.JMML..JMML.P^YbmdP'  `Moo9^Yo.M9mmmP'  `Mbmmd'

About
Install
Using
Test
Links
License

About

The shellbase framework serves as a foundation for Unix shell scripts. It follows POSIX, the Portable Operating System Interface standard, and runs on any Unix-like system. The framework provides logging, validation helpers, signal handling, garbage collection, and support for concurrent instances.

shellbase defines global variables and functions. Clients may call any function without the base_ prefix. The public functions are, in alphabetical order: aud_only, beroot, beuser, cheat, chrono_get, chrono_sta, chrono_sto, cmd_exists, cmd_run, cmd_runif, cya, die, dng2jpg, echo, ellipsize, file_exists, gitfix, gitlog, handle_pipefails, heic2jpg, inside, isempty, isfunc, isnumber, isreadable, isroot, issolid, iswritable, log, loge, logw, map_del, map_get, map_put, nmea2gpx, pdf2jpg, pdf2png, prettytable, prettyuptime, realdir, realpath, retry, rev, semver, should_continue, timestamp, tolog, tologe, tolower, totsout, tsout, url_exists, user_exists, var_exists, ver_ge, vid2aud, ytda.

Global variables carry the BASE_ prefix. Clients may use them and should place temporary files under $BASE_WIP. Functions with the base_ prefix stay internal. Clients shouldn’t call them.

See dotfiles, gento, pulse, and toolbox for example projects built on the framework.

Install

The framework is a single POSIX shell script, base.sh, that your scripts source. It needs no build step. Install it in one of three ways.

Clone the repository and run the installer:

git clone https://github.com/rdavid/shellbase.git &&
  ./shellbase/app/install

Use Homebrew with the tap:

brew install rdavid/tap/shellbase

Extract base.sh from a release archive. Some operating systems require administrative rights to write to /usr/local/bin, so prefix tar with sudo or doas when needed:

REL=0.9.20261010
SRC=https://github.com/rdavid/shellbase/archive/refs/tags/v$REL.tar.gz
curl --location --silent $SRC |
  tar \
    --directory /usr/local/bin \
    --extract \
    --gzip \
    --strip-components=2 \
    shellbase-$REL/lib/base.sh

Using

Make sure base.sh is in a PATH directory. Then source the framework in your script:

#!/bin/sh
# File not following:
#  shellcheck disable=SC1091
. base.sh
log I\'m using the shellbase.

The framework provides three loggers: log for information, loge for errors, and logw for warnings. Each logger writes to standard error. In non-interactive mode, it also appends the message to the log file with a one-letter level tag: i for information, e for errors, and w for warnings.

To try shellbase without installing it, source it straight from a release:

#!/bin/sh
REL=0.9.20261010
SRC=https://github.com/rdavid/shellbase/archive/refs/tags/v$REL.tar.gz
eval "$(
  curl --location --silent $SRC |
    tar \
      --extract \
      --gzip \
      --to-stdout \
      shellbase-$REL/lib/base.sh
)"
log I\'m using the shellbase.

prettytable example:

. base.sh
{
  printf 'ID\tNAME\tTITLE\n'
  printf '123456789\tJohn Foo\tDirector\n'
  printf '12\tMike Bar\tEngineer\n'
} | prettytable

Output:

+-----------+----------+----------+
|ID         |NAME      |TITLE     |
+-----------+----------+----------+
|123456789  |John Foo  |Director  |
|12         |Mike Bar  |Engineer  |
+-----------+----------+----------+

Test

The project uses Daniel J. Bernstein’s build system, redo. You can install Sergey Matveev’s goredo implementation. redo lint applies the following linters to the source files: actionlint, checkmake, conform, gitleaks, hadolint, reuse, shellcheck, shfmt, typos, vale, yamllint, zizmor. redo test runs the unit tests against each installed shell. redo test-container repeats the tests inside the supported container images. The project uses David Rabkin's goredoer to build goredo.

A run of redo lint shows the conventions in practice: commands echo before they run, missing linters stay silent instead of warning, a failure doesn’t stop the rest, and the script’s only line of stdout is the bare OK that redo reads as the target.

lint.do — redo lint

1 $ redo lint

2 20260727-14:02:01 » dash -n ./lint.do

20260727-14:02:01 » mksh -n ./lint.do

20260727-14:02:02 » shellcheck ./*.do ./app/* ./lib/*

3 actionlint, checkmake, hadolint — not installed, nothing logged

4 20260727-14:02:04 shfmt failed, err=1.

20260727-14:02:05 » yamllint ./.github/*.yml ./.github/workflows/*.yml

5 OK

What the numbers point at

1
No shellbase-specific CLI to learn — redo lint is a plain redo target running a POSIX .do script.
2
cmd_run echoes the exact command it's about to run, in the same green as every other info-level log line, before any output appears.
3
cmd_runif skips missing tools without a warning. Silence is the signal that a linter isn't installed, not a yellow line asking you to fix it.
4
A genuine failure, printed in red by loge. One bad linter doesn't stop the rest — lint.do keeps going.
5
The only line on stdout. redo reads it as the target's content; every line above it went to stderr.

License

shellbase belongs to David Rabkin and uses a Zero-Clause BSD license.