Octivi Bash Boilerplate (OBB)

If you are writing a script that is more than 100 lines long, or that uses non-straightforward control flow logic, you should rewrite it in a more structured language now. -- Google Shell Style Guide

Octivi Bash Boilerplate (OBB)

Octivi Bash Boilerplate (OBB) is a lightweight starting point for Bash scripts that promotes consistent structure and safe defaults. With ready-to-use helpers and auto-generated documentation, it helps you ship maintainable CLI utilities faster and with fewer surprises.

Octivi Bash Boilerplate (OBB) Header

Octivi Bash Boilerplate (OBB) Header is a minimalistic version of the Bash boilerplate for use in scripts. Copy and paste this code at the beginning of your Bash script files.

Key features

• Enforces Unofficial Bash "Strict Mode" to reduce hard-to-track runtime errors
• Enables verbose diagnostics through the DEBUG environment variable
• Honors the NO_COLOR (disabling colors) and FORCE_COLOR environment variables and supports ANSI colors out of the box
• Exposes logging helpers for uniform, readable output
• Generates -h help text from inline comments, so documentation stays close to the code
• Handles option parsing through POSIX getopts for predictable CLI behavior

Requirements

• Bash 4.4 or newer

Install

AI agents skill

This repository is also available as a skill for AI agents.

Install it with:

npx skills add octivi/bash-boilerplate

Manual

Download, verify checksums, and install all OBB files together:

# or use releases/latest/download/... URLs if you always want the latest release
curl -fsSLO https://github.com/octivi/bash-boilerplate/releases/download/v1.1.0/octivi-bash-boilerplate \
  && curl -fsSLO https://github.com/octivi/bash-boilerplate/releases/download/v1.1.0/octivi-bash-boilerplate-header \
  && curl -fsSLO https://github.com/octivi/bash-boilerplate/releases/download/v1.1.0/octivi-bash-boilerplate-update \
  && curl -fsSL https://github.com/octivi/bash-boilerplate/releases/download/v1.1.0/octivi-bash-boilerplate.sha256 \
  | sha256sum -c - \
  && curl -fsSL https://github.com/octivi/bash-boilerplate/releases/download/v1.1.0/octivi-bash-boilerplate-header.sha256 \
  | sha256sum -c - \
  && curl -fsSL https://github.com/octivi/bash-boilerplate/releases/download/v1.1.0/octivi-bash-boilerplate-update.sha256 \
  | sha256sum -c - \
  && sudo install -m 0644 octivi-bash-boilerplate /usr/local/share/octivi-bash-boilerplate \
  && sudo install -m 0644 octivi-bash-boilerplate-header /usr/local/share/octivi-bash-boilerplate-header \
  && sudo install -m 0755 octivi-bash-boilerplate-update /usr/local/share/octivi-bash-boilerplate-update \
  || { echo "Checksum verification failed; aborting installation." >&2; exit 1; }

Ansible

Install all OBB files with checksum verification:

- name: "Install Octivi Bash Boilerplate files"
  ansible.builtin.get_url:
    # or use releases/latest/download/... URLs if you always want the latest release
    url: "https://github.com/octivi/bash-boilerplate/releases/download/v1.1.0/{{ item.name }}"
    dest: "/usr/local/share/{{ item.name }}"
    owner: "root"
    group: "root"
    mode: "{{ item.mode }}"
    checksum: "sha256:https://github.com/octivi/bash-boilerplate/releases/download/v1.1.0/{{ item.name }}.sha256"
  loop:
    - { name: "octivi-bash-boilerplate", mode: "0644" }
    - { name: "octivi-bash-boilerplate-header", mode: "0644" }
    - { name: "octivi-bash-boilerplate-update", mode: "0755" }
  register: "__obb_download"
  until: __obb_download is succeeded
  retries: 5
  delay: 2

Quick start: use OBB in scripts (with markers)

The easiest workflow is to keep OBB in a marked block and let octivi-bash-boilerplate-update inject/update the content for you.

Header variant (minimal)

Use this when you only need strict mode and base constants.

#!/usr/bin/env bash

# >>> OBB:BEGIN variant=header
# <<< OBB:END

main() {
  echo "Hello from header mode"
}

main "$@"

Then update the marked block:

/usr/local/share/octivi-bash-boilerplate-update ./your-script

Full variant (helpers + logging + checks)

Use this when you want OBB helper functions like print, error, die, require_command, etc.

Important: place the full OBB marker block at the end of the script and keep your own logic above it.

#!/usr/bin/env bash
#/ Usage: your-script [OPTIONS]
#/ Example:
#/   your-script --help

main() {
  print "Hello from full mode"
}

# >>> OBB:BEGIN variant=full
# <<< OBB:END

Then update the marked block:

/usr/local/share/octivi-bash-boilerplate-update ./your-script

To pin the inserted block to a specific release:

/usr/local/share/octivi-bash-boilerplate-update -u 1.1.1 ./your-script

Update inlined OBB blocks

Use octivi-bash-boilerplate-update to update scripts where OBB was copy-pasted (not sourced).

/usr/local/share/octivi-bash-boilerplate-update ./script-a ./script-b
/usr/local/share/octivi-bash-boilerplate-update -u 1.1.1 ./script-a
/usr/local/share/octivi-bash-boilerplate-update --variant header ./script-a ./script-b

--variant accepts full or header. Without --variant, each marked block must define variant=full|header in its # >>> OBB:BEGIN ... marker.

When -u/--use is set, the script downloads release assets and verifies their .sha256 checksums before updating any target files.

If a target file has no OBB markers, it is skipped with a warning.

The updater writes explicit markers around embedded blocks:

# >>> OBB:BEGIN variant=full source=github version=v1.1.1
...
# <<< OBB:END

Projects that use Octivi Bash Boilerplate

• BorgBackup Wrapper - a wrapper around the deduplicating archiver BorgBackup that streamlines everyday tasks across multiple repositories.

How to test on a specific Bash version

The easiest way is to use Docker, for example to test Bash 3.2:

docker run -it --rm -v "$PWD":/work -w /work bash:3.2 bash

Other resources

Awesome Bash - A curated list of delightful Bash scripts and resources

Style guides

• Google Shell Style Guide
• Bash FAQ
• Pure Bash Bible
• Unix shell script tactics — best practices style guide
• Shell Scripts Matter
• Bash tips: Colors and formatting

Boilerplates

• BASH3 Boilerplate (b3bp)
• https://github.com/xwmx/bash-boilerplate
• https://github.com/oxyc/bash-boilerplate
• https://github.com/ralish/bash-script-template
• https://github.com/andrei-pavel/bash-boilerplate

Tools

• ShellCheck
• Shellharden

License

All content is provided under the terms of The MIT License.