Skip to content

Home

Jump to bottom
Eugene Lazutkin edited this page Mar 20, 2026 · 5 revisions

options.bash is a pure Bash library for building CLI utilities with rich terminal output and option parsing. It requires Bash 4.0+ and has zero external dependencies beyond coreutils and getopt.

For AI assistants: see llms.txt for LLM-optimized documentation.

Major features:

  • Zero external dependencies — pure Bash, no Python, no Node, no compiled binaries.
  • Rich terminal output — colors, styles, cursor control, hyperlinks, true color support.
  • Option parsing — wraps getopt with a clean API for options, commands, and arguments.
  • Auto-generated help — colored help screens built from your option definitions.
  • Box layout engine — normalize, pad, align, and stack multi-line text blocks.
  • Terminal-aware output — ANSI codes are automatically stripped when piped to files.
  • Include guards — modules can be sourced multiple times safely.
  • Auto-dependency resolution — modules load their own dependencies.

Quick start

Clone or add as a sparse worktree:

git clone git@github.com:uhop/options.bash.git

Source the modules you need:

#!/usr/bin/env bash
set -euo pipefail

LIB_DIR="/path/to/options.bash"
source "${LIB_DIR}/args.sh"
source "${LIB_DIR}/args-help.sh"
source "${LIB_DIR}/args-version.sh"

args::program "my-tool" "1.0.0" "Does useful things"
args::option "-v, --version" "Show version"
args::option "-h, --help" "Show help"
args::option "--output, -o" "Output file" "file"
args::option "build" "Build the project"

args::parse "$@"

Module reference

The library is organized into independently sourceable modules:

Terminal output:

  • ansi.sh — ANSI escape codes via raw sequences (bash 4.0+). The primary ANSI module.
  • ansi-tput.sh — alternative ANSI implementation via tput (bash 4.3+).
  • ansi-utils.sh — shared ANSI utilities: color math, stripping, composing, output helpers.

Text layout:

  • string.sh — string primitives: pad, clean, length, output helpers.
  • box.sh — text box layout engine: normalize, pad, align, stack multi-line strings.

Option parsing:

Testing:

  • test.sh — built-in test harness: assertions, colored output, runner.

Module layers

┌─────────────┐  ┌───────────────┐
│  args-help  │  │ args-version  │    ← high-level: help/version handlers
├─────────────┤  └───────┬───────┘
│   args.sh   │          │            ← option/command parsing
├─────┬───────┘          │
│     │                  │
│  ┌──┴──────┐  ┌───────┘
│  │ box.sh  │  │
│  ├─────────┤  │
│  │ ansi.sh │  │                     ← terminal output (pick one)
│  │   —or—  │  │
│  │ ansi-   │  │
│  │ tput.sh │  │
│  ├─────────┤  │
│  │ ansi-   │◄─┘                     ← shared ANSI utilities
│  │ utils.sh│
│  ├─────────┤
│  │string.sh│                        ← string primitives
│  └─────────┘

ansi.sh and ansi-tput.sh are mutually exclusive — source only one.

Key conventions

  • set -euo pipefail at the top of every module.
  • Functions use module::submodule::name naming (e.g., ansi::fg, box::exec, string::pad).
  • Use ansi::out / box::out / string::out instead of raw echo for terminal-safe output.
  • Error output functions (ansi::err, box::err, string::err) write to stderr and return 1.
  • Set ANSI_NO_SIMPLE_COMMAND_NAMES=1 before sourcing to suppress global color/style names.

Formalities

The project is distributed under the BSD 3-Clause license.

Clone this wiki locally