feat: add bats tests, docs (#139)

* fix(test): ensure bats file list uses xargs

* docs(readme): use yarn for testing instructions

* fix(test): ensure pipelines fail properly

* docs(alias): fix table header

---------

Signed-off-by: Ismo Vuorinen <ismo@ivuorinen.net>

local/bin/a.md

@@ -0,0 +1,29 @@
+# a
+
+Encrypt or decrypt files and directories using `age` and your GitHub SSH keys.
+
+## Usage
+
+```bash
+a encrypt <file|dir>
+a decrypt <file.age|dir>
+```
+
+Options:
+
+- `-v`, `--verbose` – show log output
+
+Environment variables:
+
+- `AGE_KEYSFILE` – location of the keys file
+- `AGE_KEYSSOURCE` – URL to fetch keys if missing
+- `AGE_LOGFILE` – log file path
+
+## Example
+
+```bash
+a encrypt secret.txt
+a decrypt secret.txt.age
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/ad.md

@@ -0,0 +1,19 @@
+# ad
+
+Decrypt a file encrypted with `age` using your GitHub SSH keys.
+
+## Usage
+
+```bash
+ad <file.age>
+```
+
+Uses `AGE_KEYSFILE` and `AGE_KEYSSOURCE` if keys are missing.
+
+## Example
+
+```bash
+ad secret.txt.age
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/ae.md

@@ -0,0 +1,19 @@
+# ae
+
+Encrypt a file with `age` using your GitHub SSH keys.
+
+## Usage
+
+```bash
+ae <file>
+```
+
+Uses `AGE_KEYSFILE` and `AGE_KEYSSOURCE` if keys are missing.
+
+## Example
+
+```bash
+ae secret.txt
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/dfm.md

@@ -0,0 +1,26 @@
+# dfm
+
+Dotfiles manager and installation helper. Provides wrappers for many
+setup tasks defined in this repository.
+
+## Usage
+
+```bash
+dfm <command> [options]
+```
+
+Common commands include:
+
+- `install` – install tools or run platform specific setup
+- `brew` – manage Homebrew packages
+- `docs` – regenerate markdown documentation
+
+Set `VERBOSE=1` to see debug output.
+
+### Example
+
+```bash
+dfm install all
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/fzf-tmux.md

@@ -0,0 +1,21 @@
+# fzf-tmux
+
+Wrapper around [`fzf`](https://github.com/junegunn/fzf) that opens the
+interface inside a tmux pane or popup.
+
+## Usage
+
+```bash
+fzf-tmux [layout options] [--] [fzf options]
+```
+
+Layout flags like `-p` or `-d` control popup and split behaviour. Use
+`--` to pass arguments directly to `fzf`.
+
+### Example
+
+```bash
+fzf-tmux -p 80%,60% -- --reverse
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/fzf.md

@@ -0,0 +1,16 @@
+# fzf
+
+Binary of the fuzzy finder [fzf](https://github.com/junegunn/fzf).
+Use `fzf` as you would normally; this wrapper ships the prebuilt
+binary in the dotfiles.
+
+## Usage
+
+```bash
+fzf [options]
+```
+
+Refer to the upstream `fzf` documentation for all available
+flags and features.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/git-attributes.md

@@ -0,0 +1,25 @@
+# git-attributes
+
+Checks that every tracked file has a matching pattern in `.gitattributes`.
+Can optionally suggest or write missing rules.
+
+## Usage
+
+```bash
+git-attributes [options]
+```
+
+Options include:
+
+- `-v, --verbose` – show progress information
+- `-e, --exit` – exit with non-zero status if missing rules
+- `-p, --pattern <glob>` – pattern to check (default: `text: auto`)
+- `-w, --write` – append suggestions to `.gitattributes`
+
+### Example
+
+```bash
+git-attributes -v --write
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/iterm2_shell_integration.zsh.md

@@ -0,0 +1,15 @@
+# iterm2_shell_integration.zsh
+
+Official iTerm2 shell integration script for zsh. Source this file to
+enable prompt tracking and command notifications in iTerm2.
+
+## Usage
+
+```bash
+source iterm2_shell_integration.zsh
+```
+
+No parameters are required. The script modifies your prompt to work
+with iTerm2 features such as badges and profile switching.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/msgr.md

@@ -0,0 +1,20 @@
+# msgr
+
+Helper library for printing colorized log messages from shell scripts.
+
+## Usage
+
+```bash
+msgr <type> "message" [extra]
+```
+
+Message types include `ok`, `warn`, `err`, `run` and many more. The
+script is primarily sourced by other scripts.
+
+### Example
+
+```bash
+msgr ok "Installation complete"
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/php-switcher.md

@@ -0,0 +1,23 @@
+# php-switcher
+
+Switch between Homebrew-installed PHP versions or list installed versions.
+
+## Usage
+
+```bash
+php-switcher <version>|--auto [options]
+```
+
+Options:
+
+- `--installed` – list versions installed via Homebrew
+- `--current` – print currently active PHP version
+- `--auto` – read version from `.php-version` in current directory
+
+### Example
+
+```bash
+php-switcher 8.3
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/pushover

@@ -56,22 +56,31 @@ __pushover_send_message()
 
   response="$(eval "${curl_cmd}")"
   printf "%s\n" "$response"
-  # TODO: Parse response
-  r="${?}"
-  if [ "${r}" -ne 0 ]; then
-    printf "%s: Failed to send message\n" "${0}" >&2
+
+  # Parse response status. Expect JSON like: {"status":1,"request":"..."}
+  if echo "$response" | grep -q '"status"[[:space:]]*:[[:space:]]*1'; then
+    r=0
+  else
+    r=1
   fi
 
-  return "${r}"
+  if [ "$r" -ne 0 ]; then
+    # Extract possible error message from JSON
+    err=$(echo "$response" | grep -o '"errors".*' | sed 's/"errors"[:,\[]//g' | tr -d '[]"')
+    [ -n "$err" ] && printf "%s: %s\n" "$0" "$err" >&2
+    printf "%s: Failed to send message\n" "$0" >&2
+  fi
+
+  return "$r"
 }
 
-CURL="$(which curl)"
+CURL="$(command -v curl)"
 PUSHOVER_URL="https://api.pushover.net/1/messages.json"
 TOKEN=$PUSHOVER_TOKEN
 USER=$PUSHOVER_USER
 CURL_OPTS=""
-devices="${devices} ${device}"
-optstring="c:d:D:e:f:p:r:t:T:s:u:U:a:h"
+devices=""
+optstring="c:d:D:e:p:r:t:T:s:u:U:a:h"
 
 OPTIND=1
 while getopts ${optstring} c; do
@@ -97,7 +106,7 @@ while getopts ${optstring} c; do
     t)
       title="${OPTARG}"
       ;;
-    k)
+    T)
       TOKEN="${OPTARG}"
       ;;
     s)

local/bin/pushover.md

@@ -0,0 +1,25 @@
+# pushover
+
+Send notifications via the Pushover API.
+
+## Usage
+
+```bash
+pushover -T <token> -U <user> [-t title] [-p priority] message
+```
+
+Common options:
+
+- `-c <callback>` – callback URL
+- `-d <device>` – target device
+- `-s <sound>` – notification sound name
+- `-T <token>` – application token (or `PUSHOVER_TOKEN` env)
+- `-U <user>` – user key (or `PUSHOVER_USER` env)
+
+## Example
+
+```bash
+pushover -T $TOKEN -U $USER -t "Build" "Finished successfully"
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/t.md

@@ -0,0 +1,23 @@
+# t
+
+Launch or switch to a tmux session based on a directory selected with
+`fzf`. Inspired by scripts from ThePrimeagen and Jess Archer.
+
+## Usage
+
+```bash
+t
+```
+
+Environment variables:
+
+- `T_ROOT` – base directory to search (default: `~/Code`)
+- `T_MAX_DEPTH` – recursion depth for directory search
+
+### Example
+
+```bash
+T_ROOT=~/projects t
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-backup-folder.md

@@ -0,0 +1,20 @@
+# x-backup-folder
+
+Create a compressed archive of a folder with a timestamped name.
+
+## Usage
+
+```bash
+x-backup-folder <folder> [archive-name]
+```
+
+- `folder` – directory to back up
+- `archive-name` – optional prefix for the generated tar.gz
+
+## Example
+
+```bash
+x-backup-folder ~/Documents Notes
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-backup-mysql-with-prefix.md

@@ -0,0 +1,21 @@
+# x-backup-mysql-with-prefix
+
+Dump MySQL tables matching a prefix to a timestamped file.
+
+## Usage
+
+```bash
+x-backup-mysql-with-prefix <prefix> <name> [database]
+```
+
+- `prefix` – table prefix to match (e.g. `wp_`)
+- `name` – file name prefix
+- `database` – database name (default: `wordpress`)
+
+## Example
+
+```bash
+x-backup-mysql-with-prefix wp_ blog
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-change-alacritty-theme.md

@@ -0,0 +1,20 @@
+# x-change-alacritty-theme
+
+Adapted from <https://gist.github.com/xqm32/17777d035930d622d0ff7530bfab61fd>
+
+## Usage
+
+```bash
+x-change-alacritty-theme <day|night>
+```
+
+Switches Alacritty's theme by copying a theme file under
+`~/.config/alacritty/`.
+
+### Example
+
+```bash
+x-change-alacritty-theme night
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-clean-vendordirs.md

@@ -0,0 +1,19 @@
+# x-clean-vendordirs
+
+Remove `vendor` and `node_modules` directories recursively.
+
+## Usage
+
+```bash
+x-clean-vendordirs [directory]
+```
+
+- `directory` – root directory to clean (default: current directory)
+
+## Example
+
+```bash
+x-clean-vendordirs ~/projects
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-compare-versions.py.md

@@ -0,0 +1,14 @@
+# x-compare-versions.py
+
+Compare version strings using Python's packaging library.
+
+## Usage
+
+```bash
+echo "1.2.3 >= 1.0.0" | x-compare-versions.py
+```
+
+The script reads comparison expressions from standard input and exits
+with status 0 if all comparisons are true.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-dc.md

@@ -0,0 +1,19 @@
+# x-dc
+
+Create a directory if it does not exist.
+
+## Usage
+
+```bash
+x-dc <directory>
+```
+
+Set `VERBOSE=1` to see log messages.
+
+## Example
+
+```bash
+x-dc ~/tmp/mydir
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-dfm-docs-xterm-keybindings.md

@@ -0,0 +1,14 @@
+# x-dfm-docs-xterm-keybindings
+
+Generate `docs/tmux-keybindings.md` using tmux's key list.
+
+## Usage
+
+```bash
+x-dfm-docs-xterm-keybindings
+```
+
+No parameters are needed. The script writes the file under `docs/` and
+overwrites any existing version.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-env-list.md

@@ -0,0 +1,21 @@
+# x-env-list
+
+Lists environment variables grouped by their prefix. Sensitive values
+are hidden by default.
+
+## Usage
+
+```bash
+x-env-list [options]
+```
+
+Use `--json` for machine readable output or specify
+`X_ENV_GROUPING` with a YAML file to override the default groups.
+
+### Example
+
+```bash
+X_ENV_GROUPING=~/env-groups.yaml x-env-list --json
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-foreach.md

@@ -0,0 +1,20 @@
+# x-foreach
+
+Run a command in each directory produced by another command.
+
+## Usage
+
+```bash
+x-foreach "<list-cmd>" "<cmd>"
+```
+
+- `list-cmd` – command that outputs directories
+- `cmd` – command to run inside each directory
+
+## Example
+
+```bash
+x-foreach "ls -d */" "git status"
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-gh-get-latest-release-targz.md

@@ -0,0 +1,19 @@
+# x-gh-get-latest-release-targz
+
+Fetch the tarball URL of the latest GitHub release or download it directly.
+
+## Usage
+
+```bash
+x-gh-get-latest-release-targz <owner/repo> [--get]
+```
+
+- `--get` – download and extract the tarball instead of printing the URL
+
+## Example
+
+```bash
+x-gh-get-latest-release-targz ivuorinen/dotfiles --get
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-git-largest-files.py.md

@@ -0,0 +1,21 @@
+# x-git-largest-files.py
+
+Lists the largest files in a git repository.
+
+```bash
+x-git-largest-files.py [options]
+```
+
+Options:
+
+- `-c NUM` – number of files to show (default: 10)
+- `--files-exceeding N` – list files larger than N KB
+- `-p` – sort by on-disk size instead of pack size
+
+## Example
+
+```bash
+x-git-largest-files.py -c 5
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-have.md

@@ -0,0 +1,18 @@
+# x-have
+
+Check if a command exists on the system. Exits with status 0 if found
+and 1 otherwise.
+
+## Usage
+
+```bash
+x-have <command>
+```
+
+### Example
+
+```bash
+x-have git && echo "git installed"
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-hr.md

@@ -0,0 +1,19 @@
+# x-hr
+
+Print a horizontal rule. Useful for visually separating log output.
+
+## Usage
+
+```bash
+x-hr [character]
+```
+
+If no character is given a red `-` is used.
+
+### Example
+
+```bash
+x-hr "="
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-ip.md

@@ -0,0 +1,19 @@
+# x-ip
+
+Fetch your public IP address using `curl`.
+
+## Usage
+
+```bash
+x-ip [curl-options]
+```
+
+Any arguments are passed directly to `curl`.
+
+### Example
+
+```bash
+x-ip -4
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-load-configs.md

@@ -0,0 +1,21 @@
+# x-load-configs
+
+Source shell configuration files for aliases and exports. Intended to
+be run after `dfm install` or when switching hosts.
+
+## Usage
+
+```bash
+x-load-configs
+```
+
+Set `VERBOSE=1` to print each file as it is sourced. Use `DEBUG=1` to
+enable tracing.
+
+### Example
+
+```bash
+VERBOSE=1 x-load-configs
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-localip.md

@@ -0,0 +1,25 @@
+# x-localip
+
+Display local IPv4 and IPv6 addresses with optional interface filtering.
+
+## Usage
+
+```bash
+x-localip [--ipv4] [--ipv6] [interface]
+```
+
+- `--ipv4` – show only IPv4 addresses
+- `--ipv6` – show only IPv6 addresses
+- `interface` – limit output to the named interface
+
+## Example
+
+```bash
+# Show all addresses
+x-localip
+
+# IPv4 for wlan0
+x-localip --ipv4 wlan0
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-mkd.md

@@ -0,0 +1,19 @@
+# x-mkd
+
+Create a directory and immediately `cd` into it.
+
+## Usage
+
+```bash
+x-mkd <dir>
+```
+
+Set `VERBOSE=1` for status messages.
+
+## Example
+
+```bash
+x-mkd project && git init
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-multi-ping.md

@@ -0,0 +1,20 @@
+# x-multi-ping
+
+Multi-protocol ping helper supporting IPv4 and IPv6.
+
+## Usage
+
+```bash
+x-multi-ping [--loop] [--sleep=N] host1 host2...
+```
+
+- `--loop` – ping continuously
+- `--sleep` – seconds to wait between iterations
+
+## Example
+
+```bash
+x-multi-ping --loop --sleep=5 example.com
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-multi-ping.pl.md

@@ -0,0 +1,20 @@
+# x-multi-ping.pl
+
+Ping multiple hosts with IPv4/IPv6 support.
+
+## Usage
+
+```bash
+x-multi-ping.pl [--loop|--forever] [--sleep N] host1 host2 ...
+```
+
+`--loop` keeps pinging each host until interrupted. `--sleep` controls
+the delay between attempts.
+
+### Example
+
+```bash
+x-multi-ping.pl --loop --sleep 2 example.com 1.1.1.1
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-open-ports.md

@@ -0,0 +1,19 @@
+# x-open-ports
+
+List listening ports using `lsof` or `ss`.
+
+## Usage
+
+```bash
+x-open-ports [--json]
+```
+
+- `--json` – output as JSON instead of Markdown
+
+## Example
+
+```bash
+x-open-ports --json
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-path-append.md

@@ -0,0 +1,19 @@
+# x-path-append
+
+Append directories to the `PATH` variable without duplicates.
+
+## Usage
+
+```bash
+x-path-append <dir1> [dir2 ...]
+```
+
+Set `VERBOSE=1` for verbose logging.
+
+## Example
+
+```bash
+x-path-append /usr/local/sbin "$HOME/bin"
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-path-prepend.md

@@ -0,0 +1,19 @@
+# x-path-prepend
+
+Prepend directories to the `PATH` variable without duplicates.
+
+## Usage
+
+```bash
+x-path-prepend <dir1> [dir2 ...]
+```
+
+Set `VERBOSE=1` for verbose logging.
+
+## Example
+
+```bash
+x-path-prepend "$HOME/bin" /opt/tools
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-path-remove.md

@@ -0,0 +1,19 @@
+# x-path-remove
+
+Remove directories from the `PATH` variable.
+
+## Usage
+
+```bash
+x-path-remove <dir1> [dir2 ...]
+```
+
+Set `VERBOSE=1` for verbose logging.
+
+## Example
+
+```bash
+x-path-remove /usr/local/bin
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-path.md

@@ -0,0 +1,30 @@
+# x-path
+
+Manage entries in the `PATH` variable through subcommands.
+
+## Usage
+
+```bash
+x-path <command> <directory1> [directory2 ...]
+```
+
+### Commands
+
+- `append` / `a` – Append directories to `PATH`
+- `prepend` / `p` – Prepend directories to `PATH`
+- `remove` – Remove directories from `PATH`
+- `check` – Validate directories (default: all in `PATH`)
+
+Set `VERBOSE=1` for progress output.
+
+## Examples
+
+```bash
+# Prepend /opt/bin to PATH
+x-path prepend /opt/bin
+
+# Remove /usr/local/bin from PATH
+x-path remove /usr/local/bin
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-quota-usage.php.md

@@ -0,0 +1,14 @@
+# x-quota-usage.php
+
+Display filesystem quota usage in a human readable table.
+
+## Usage
+
+```bash
+x-quota-usage.php
+```
+
+Runs the `quota` command and formats the output. Requires PHP with the
+`shell_exec` function enabled.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-record.md

@@ -0,0 +1,19 @@
+# x-record
+
+Interactive screen recording wrapper around `giph`.
+
+## Usage
+
+```bash
+x-record <gif|mkv|webm|mp4> <fullscreen|set>
+```
+
+The script asks for file type and area when omitted.
+
+## Example
+
+```bash
+x-record gif fullscreen
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-set-php-aliases.md

@@ -0,0 +1,14 @@
+# x-set-php-aliases
+
+---
+
+## Usage
+
+```bash
+source x-set-php-aliases
+```
+
+Generates shell aliases (`php80`, `php81` ...) for each Homebrew PHP
+installation. Caches the list under `$XDG_CACHE_HOME/x-set-php-aliases`.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-sha256sum-matcher.md

@@ -0,0 +1,22 @@
+# x-sha256sum-matcher
+
+Compare two files by calculating their SHA256 checksums.
+
+## Usage
+
+```bash
+x-sha256sum-matcher [options] file1 file2
+```
+
+Options:
+
+- `-v` – verbose output
+- `-h, --help` – show help
+
+### Example
+
+```bash
+x-sha256sum-matcher original.iso download.iso
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-ssl-expiry-date.md

@@ -0,0 +1,22 @@
+# x-ssl-expiry-date
+
+Check the expiry date of an SSL certificate for one or more hosts.
+
+## Usage
+
+```bash
+x-ssl-expiry-date [-d] [-p PORT] host1 host2 ...
+```
+
+Options:
+
+- `-d` – show days left instead of the full date
+- `-p <port>` – use custom port (default: 443)
+
+### Example
+
+```bash
+x-ssl-expiry-date -d github.com
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-term-colors.md

@@ -0,0 +1,14 @@
+# x-term-colors
+
+Display a table of 24‑bit color codes for testing terminal color
+support.
+
+## Usage
+
+```bash
+x-term-colors
+```
+
+Pipe the output to `less -R` to view with color highlighting.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-thumbgen.md

@@ -0,0 +1,26 @@
+# x-thumbgen
+
+Generate thumbnails using ImageMagick (magick) with MIME type filtering.
+
+## Usage
+
+```bash
+x-thumbgen [options] source_directory
+```
+
+Options:
+
+- `-o DIR` – output directory (default: same as source)
+- `-s STR` – suffix for thumbnails
+- `-h` – show help
+
+Environment variables like `THUMB_BACKGROUND` control the background
+color.
+
+### Example
+
+```bash
+THUMB_BACKGROUND=black x-thumbgen -o ~/thumbs ~/images
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-until-error.md

@@ -0,0 +1,20 @@
+# x-until-error
+
+Repeatedly execute a command until it returns a non-zero exit status.
+
+## Usage
+
+```bash
+x-until-error [--sleep SECONDS] command [args...]
+```
+
+Use `--sleep` to wait between runs. The command is executed at least
+once.
+
+### Example
+
+```bash
+x-until-error --sleep 2 ping -c1 example.com
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-until-success.md

@@ -0,0 +1,20 @@
+# x-until-success
+
+Repeat a command until it succeeds (exit status 0). The command is
+always executed at least once.
+
+## Usage
+
+```bash
+x-until-success [--sleep SECONDS] command [args...]
+```
+
+Use `--sleep` to control the delay between attempts.
+
+### Example
+
+```bash
+x-until-success --sleep 5 curl -I https://example.com
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-validate-sha256sum.sh.md

@@ -0,0 +1,14 @@
+# x-validate-sha256sum.sh
+
+This script contains a helper for sha256 validating your downloads
+
+## Usage
+
+```bash
+x-validate-sha256sum.sh file sha256sum
+```
+
+The script computes the SHA256 hash of `file` and compares it to the
+expected value. It exits non-zero if the sums differ.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-welcome-banner.md

@@ -0,0 +1,13 @@
+# x-welcome-banner
+
+Print a colorful MOTD with greeting, system info and today's weather.
+
+## Usage
+
+```bash
+x-welcome-banner
+```
+
+Requires optional tools: `neofetch`, `figlet`, `lolcat` and `curl` for extra info.
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-when-down.md

@@ -0,0 +1,17 @@
+# x-when-down
+
+Wait until a host stops responding to ping, then run a command.
+
+## Usage
+
+```bash
+x-when-down <host> <command...>
+```
+
+## Example
+
+```bash
+x-when-down 1.2.3.4 echo "server down"
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->

local/bin/x-when-up.md

@@ -0,0 +1,19 @@
+# x-when-up
+
+Wait for a host to respond to ping before running a command.
+
+## Usage
+
+```bash
+x-when-up <host> <command...>
+```
+
+If the command is `ssh`, the host argument may be omitted.
+
+## Example
+
+```bash
+x-when-up 1.2.3.4 ssh 1.2.3.4
+```
+
+<!-- vim: set ft=markdown spell spelllang=en_us cc=80 : -->