Bash CLI Framework

A comprehensive framework for building consistent, professional bash CLI tools with standardized colors, logging, headers, and error handling patterns extracted from workspace-hub scripts.

When to Use This Skill

✅ Use when:

• Building new bash CLI tools or scripts

• Adding consistent output formatting to existing scripts

• Need standardized error handling and logging

• Creating user-friendly interactive scripts

• Building tools that will be used across multiple repositories

❌ Avoid when:

• Simple one-liner scripts

• Scripts that don't produce user-facing output

• When Python/Node CLI frameworks are more appropriate

Core Capabilities

1. Color Definitions

Standard ANSI color codes for consistent terminal output:

#!/bin/bash

ABOUTME: Standard color definitions for CLI output

ABOUTME: Use these consistently across all workspace-hub scripts

Colors

RED='\033[0;31m' GREEN='\033[0;32m' YELLOW='\033[1;33m' BLUE='\033[0;34m' CYAN='\033[0;36m' MAGENTA='\033[0;35m' WHITE='\033[1;37m' NC='\033[0m' # No Color

Bold variants

BOLD='\033[1m' BOLD_RED='\033[1;31m' BOLD_GREEN='\033[1;32m' BOLD_YELLOW='\033[1;33m' BOLD_BLUE='\033[1;34m'

Usage examples

echo -e "${GREEN}✓ Success${NC}" echo -e "${RED}✗ Error${NC}" echo -e "${YELLOW}⚠ Warning${NC}" echo -e "${CYAN}ℹ Info${NC}"

2. Script Header Template

Every script should start with proper identification:

#!/bin/bash

ABOUTME: Brief one-line description of what this script does

ABOUTME: Additional context about usage or dependencies

set -e # Exit on error

Script metadata

SCRIPT_NAME="$(basename "$0")" SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" VERSION="1.0.0"

3. Logging Functions

Standardized logging with timestamps and levels:

#!/bin/bash

ABOUTME: Logging framework for bash scripts

ABOUTME: Supports DEBUG, INFO, WARNING, ERROR, CRITICAL levels

Log file configuration

LOG_FILE="${LOG_FILE:-/tmp/${SCRIPT_NAME}.log}" LOG_LEVEL="${LOG_LEVEL:-INFO}"

Log level values

declare -A LOG_LEVELS=( ["DEBUG"]=0 ["INFO"]=1 ["WARNING"]=2 ["ERROR"]=3 ["CRITICAL"]=4 )

log() { local level="$1" shift local message="$*" local timestamp=$(date '+%Y-%m-%d %H:%M:%S')

# Check if level meets threshold
if [[ ${LOG_LEVELS[$level]} -ge ${LOG_LEVELS[$LOG_LEVEL]} ]]; then
    case "$level" in
        DEBUG)    echo -e "${CYAN}[${timestamp}] DEBUG${NC} - $message" ;;
        INFO)     echo -e "${GREEN}[${timestamp}] INFO${NC} - $message" ;;
        WARNING)  echo -e "${YELLOW}[${timestamp}] WARNING${NC} - $message" ;;
        ERROR)    echo -e "${RED}[${timestamp}] ERROR${NC} - $message" >&2 ;;
        CRITICAL) echo -e "${BOLD_RED}[${timestamp}] CRITICAL${NC} - $message" >&2 ;;
    esac

    # Also write to log file
    echo "[${timestamp}] ${level} - $message" >> "$LOG_FILE"
fi

}

Convenience functions

log_debug() { log "DEBUG" "$@"; } log_info() { log "INFO" "$@"; } log_warning() { log "WARNING" "$@"; } log_error() { log "ERROR" "$@"; } log_critical() { log "CRITICAL" "$@"; }

4. Display Headers

Professional header/banner display:

#!/bin/bash

ABOUTME: Header and banner display functions

ABOUTME: Creates consistent visual separation in CLI output

print_header() { local title="$1" local width="${2:-60}" local char="${3:-═}"

local line=$(printf "%${width}s" | tr ' ' "$char")

echo ""
echo -e "${CYAN}${line}${NC}"
echo -e "${CYAN}  ${title}${NC}"
echo -e "${CYAN}${line}${NC}"
echo ""

}

print_section() { local title="$1" echo "" echo -e "${BOLD}${title}${NC}" echo -e "${CYAN}$(printf '%.0s─' {1..40})${NC}" }

print_status() { local status="$1" local message="$2"

case "$status" in
    success) echo -e "  ${GREEN}✓${NC} $message" ;;
    error)   echo -e "  ${RED}✗${NC} $message" ;;
    warning) echo -e "  ${YELLOW}⚠${NC} $message" ;;
    info)    echo -e "  ${CYAN}ℹ${NC} $message" ;;
    pending) echo -e "  ${BLUE}○${NC} $message" ;;
    skip)    echo -e "  ${MAGENTA}⊘${NC} $message" ;;
esac

}

5. Error Handling

Robust error handling with cleanup:

#!/bin/bash

ABOUTME: Error handling and cleanup functions

ABOUTME: Ensures graceful exit and resource cleanup

Trap for cleanup on exit

cleanup() { local exit_code=$?

# Remove temporary files
[[ -n "$TEMP_DIR" && -d "$TEMP_DIR" ]] && rm -rf "$TEMP_DIR"

# Log exit status
if [[ $exit_code -eq 0 ]]; then
    log_info "Script completed successfully"
else
    log_error "Script exited with code $exit_code"
fi

exit $exit_code

}

Set trap

trap cleanup EXIT INT TERM

Error handler

die() { local message="$1" local exit_code="${2:-1}"

log_critical "$message"
exit "$exit_code"

}

Assert function

assert() { local condition="$1" local message="${2:-Assertion failed}"

if ! eval "$condition"; then
    die "$message"
fi

}

6. Argument Parsing

Standard argument parsing pattern:

#!/bin/bash

ABOUTME: Argument parsing framework

ABOUTME: Supports short/long options with values

Default values

VERBOSE=false DRY_RUN=false CONFIG_FILE=""

show_usage() { cat << EOF Usage: $SCRIPT_NAME [OPTIONS] <arguments>

Options: -h, --help Show this help message -v, --verbose Enable verbose output -n, --dry-run Show what would be done without doing it -c, --config FILE Use specified configuration file --version Show version information

Examples: $SCRIPT_NAME --verbose process $SCRIPT_NAME -c config.yaml --dry-run

EOF }

parse_args() { while [[ $# -gt 0 ]]; do case "$1" in -h|--help) show_usage exit 0 ;; -v|--verbose) VERBOSE=true LOG_LEVEL="DEBUG" shift ;; -n|--dry-run) DRY_RUN=true shift ;; -c|--config) CONFIG_FILE="$2" shift 2 ;; --version) echo "$SCRIPT_NAME version $VERSION" exit 0 ;; --) shift break ;; -*) die "Unknown option: $1" ;; *) break ;; esac done

# Remaining arguments
ARGS=("$@")

}

Complete Example

A complete script using all framework components:

#!/bin/bash

ABOUTME: Example script demonstrating bash-cli-framework usage

ABOUTME: Template for new CLI tools in workspace-hub

set -e

─────────────────────────────────────────────────────────────────

Configuration

─────────────────────────────────────────────────────────────────

SCRIPT_NAME="$(basename "$0")" SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" VERSION="1.0.0"

Colors

RED='\033[0;31m' GREEN='\033[0;32m' YELLOW='\033[1;33m' BLUE='\033[0;34m' CYAN='\033[0;36m' NC='\033[0m'

Defaults

VERBOSE=false DRY_RUN=false LOG_LEVEL="INFO"

─────────────────────────────────────────────────────────────────

Functions

─────────────────────────────────────────────────────────────────

log_info() { echo -e "${GREEN}[INFO]${NC} $"; } log_warning() { echo -e "${YELLOW}[WARN]${NC} $"; } log_error() { echo -e "${RED}[ERROR]${NC} $*" >&2; }

die() { log_error "$1"; exit "${2:-1}"; }

print_header() { echo "" echo -e "${CYAN}═══════════════════════════════════════${NC}" echo -e "${CYAN} $1${NC}" echo -e "${CYAN}═══════════════════════════════════════${NC}" echo "" }

show_usage() { cat << EOF Usage: $SCRIPT_NAME [OPTIONS] <command>

Commands: run Execute the main operation status Show current status clean Clean up temporary files

Options: -h, --help Show this help -v, --verbose Verbose output -n, --dry-run Dry run mode --version Show version

EOF }

cleanup() { local exit_code=$? [[ $VERBOSE == true ]] && log_info "Cleanup complete" exit $exit_code }

trap cleanup EXIT INT TERM

─────────────────────────────────────────────────────────────────

Main

─────────────────────────────────────────────────────────────────

main() { # Parse arguments while [[ $# -gt 0 ]]; do case "$1" in -h|--help) show_usage; exit 0 ;; -v|--verbose) VERBOSE=true; shift ;; -n|--dry-run) DRY_RUN=true; shift ;; --version) echo "$VERSION"; exit 0 ;; -*) die "Unknown option: $1" ;; *) break ;; esac done

local command="${1:-}"
[[ -z "$command" ]] && { show_usage; die "No command specified"; }

print_header "$SCRIPT_NAME v$VERSION"

case "$command" in
    run)
        log_info "Running main operation..."
        [[ $DRY_RUN == true ]] && log_warning "Dry run mode - no changes made"
        # Implementation here
        ;;
    status)
        log_info "Checking status..."
        ;;
    clean)
        log_info "Cleaning up..."
        ;;
    *)
        die "Unknown command: $command"
        ;;
esac

log_info "Done!"

}

main "$@"

Best Practices

1. Always Use set -e

Exit immediately if a command exits with non-zero status:

set -e

Or for more control:

set -euo pipefail

2. Quote Variables

Always quote variables to prevent word splitting:

Good

echo "$variable" "$command" "$arg1" "$arg2"

Bad

echo $variable $command $arg1 $arg2

3. Use Meaningful Exit Codes

Exit codes

EXIT_SUCCESS=0 EXIT_ERROR=1 EXIT_USAGE=2 EXIT_CONFIG=3

4. Provide Feedback

Always tell the user what's happening:

log_info "Starting process..."

do work

log_info "Process complete (processed $count items)"

5. Support Dry Run

Let users preview changes:

if [[ $DRY_RUN == true ]]; then log_info "[DRY RUN] Would execute: $command" else eval "$command" fi

Integration with workspace-hub

This framework is used across all workspace-hub scripts:

• scripts/monitoring/suggest_model.sh

• scripts/monitoring/check_claude_usage.sh

• scripts/workspace

• scripts/repository_sync

Resources

• Bash Best Practices

• Google Shell Style Guide

• ShellCheck - Static analysis tool

Version History

• 1.0.0 (2026-01-14): Initial release - extracted from workspace-hub scripts