toolbelt

Small Bash commands for the Linux jobs you do every week and never remember the flags for.

New here? Getting started walks through install, the health check and the shell settings.

$ curl -fsSL https://raw.githubusercontent.com/khadirullah/toolbelt/main/install.sh | bash

$ git clone https://github.com/khadirullah/toolbelt.git
$ cd toolbelt
$ ./install.sh

$ mkdir -p ~/restore
$ cat backup.tar.gz.a* | tar -xzf - -C ~/restore

$ unpack -o ~/restore backup.tar.gz.aa
backup.tar.gz (4 parts) -> ~/restore/backup/ (31MB, 201 files, 3.4s)

$ ss -tlnp 'sport = :8000'
$ ps -o user=,args= -p 4121

$ port 8000
8000/tcp  0.0.0.0  pid 4121  me  python3 -m http.server 8000

$ kubectl get pods
$ kubectl describe pod NAME
$ kubectl get events --sort-by=.lastTimestamp

$ kwhy
context kind-kind, namespace shop, 3 of 4 pods not Ready
cart-7d9f8c6b54-q2lzx    ImagePullBackOff   restarts 0
  image  registry.example.com/cart:1.4.3
  event  Failed to pull image "registry.example.com/cart:1.4.3": rpc error: code = NotFound desc = failed to pull and unpack image "registry.example.com/cart:1.4.3": manifest unknown
  hint   the tag does not exist, or the pull secret is wrong
api-5b8c9d7f6-mk4tn      CrashLoopBackOff   restarts 9
  event  Back-off restarting failed container api
  exit   1, 5h ago, last 20 lines of the crashed container
    2026/09/29 10:31:58 loading config from /etc/api/config.yaml
    2026/09/29 10:31:58 connecting to postgres at db:5432
    panic: dial tcp 10.96.12.4:5432: connect: connection refused
  hint   the app stops on start, read the log lines above
worker-6c7b9f5d8-8vhwp   Pending            restarts 0
  event  0/1 nodes are available: 1 Insufficient cpu.
  asks   cpu 2, memory 1Gi
  hint   no node has cpu 2, memory 1Gi free, see kres
$ echo $?
1

$ shuf -n 5 /usr/share/dict/words | paste -sd-

$ genpass -v -w 5
blot-geriatric-robin-germinate-undated
genpass: 5 words from 7776, about 64 bits

How every command works

Learn this once and it holds for every command.

Three layers of options

1. Common options. -h, -q, -v and -y mean the same in every command. squash -l 9 is the smallest level for gzip and for zstd alike, mapped onto each tool's own scale.
2. Pass-through. Anything after -- goes to the tool underneath, so its own options stay yours, as in squash photos/ -- --long=27 or unpack photos.7z -- -mmt=4.
3. -v shows the real command. It prints every step, and each real command as a line starting with +. Copy that line and change any flag you like.

$ squash -v -l 9 -o v.tar.zst site/
squash: site/: 3 files, 60KB
squash: format: tar.zst, from the name v.tar.zst
squash: level: -l 9 is zstd -19
squash: threads: 4, zstd -T4
+ tar -cf - site | zstd -c -q --size-hint=61465 -19 -T4 > v.tar.zst
site/ -> v.tar.zst (60KB to 25KB, 3 files, 0.0s)

Common options

Exit codes

A command may give a code a meaning of its own, such as certcheck exiting 1 when a certificate expires soon. Its page says so under Exit status.

Six rules

1. It points you to good tools it does not replace. toolbelt doctor recommends btop, ncdu, fzf, tldr and dive when they are missing.
2. -h and --help always mean help. Every help page has the same layout. Usage, one line on what the command does, options, pass-through, examples, then what it needs and its exit codes. toolbelt help unpack prints the same page as unpack --help, and man unpack has the full manual.
3. A missing tool comes with the install line for your distro. It knows apt, dnf, yum, pacman, zypper and apk, and one table in lib/pkgmap holds the package name for each. 7-Zip is 7zip on Debian 13, Fedora and Arch, and p7zip-full on older Ubuntu releases.
4. Nothing destructive happens without asking. Deletes go to the trash in ~/.local/share/Trash, so you can restore them. After unpack or squash checks its result, it asks whether to delete the archive or the source. --rm deletes without asking and -k keeps without asking. In a script there is nobody to ask, so the file stays unless you pass --rm. No command writes over a file of yours. It picks a free name such as backup-1.
5. Scripts stay clean. Results go to stdout and everything meant for a person goes to stderr. Colour and progress bars appear only in a terminal, and NO_COLOR turns colour off. The exit codes are the same in every command.
6. It is small on memory. Commands stream data through pipes instead of reading whole files, and check free memory and disk space before heavy work.

Rule 3 in practice:

$ unpack logs.tar.zst
unpack: needs zstd. Install it with: sudo apt install zstd

Where it runs

On every push to main and every pull request, CI runs the whole test suite on GitHub Actions in a container of each of these images.

• toolbelt needs Bash 4.4 or newer, and the installer stops on an older one. Alpine does not ship bash, so the installer asks you to run apk add bash first.
• The shared library has fallbacks for BusyBox, such as whole seconds where date +%N is missing.
• CI checks every package name in lib/pkgmap against the real repos of each image, except Rocky 9 and Ubuntu 22.04.