MonoBash

A minimalist, single-file Bash framework featuring self-documenting magic and BusyBox-style multicall architecture.

Features

🧩 zero-dependency 📄 single-file 📦 multicall
🎨 ANSI-DSL 🪄 self-documenting ⚡ auto-dispatch

🌟 Witness the monobash magic in motion. 🌟

Quick Start

For Beginners (Demo)

Witness the framework assemble itself. Download the self-bootstrapping script that dynamically fetches the latest core and fuses it with demo features at runtime.

curl -O https://raw.githubusercontent.com/miniyu157/monobash/main/demo/demo.sh
chmod +x demo.sh
./demo.sh        # 1st run: Bootstraps and assembles the demo
./demo.sh --help # 2nd run: Explore available commands

For Developers (Production)

Start your new project with the clean core framework:

curl -o my-tool https://raw.githubusercontent.com/miniyu157/monobash/main/monobash
chmod +x my-tool
# Edit 'my-tool' to add your own functions!

Multicall Architecture (Applets)

monobash natively supports BusyBox-style symlink execution. When invoked via a symlink, the framework automatically dispatches to the corresponding internal command.

# Create a symlink to monobash
ln -s ./my-tool server

# This is equivalent to running `./my-tool server`
./server --port 8080

Usage

> ./monobash --help
Usage:
  monobash COMMAND [options...]
  COMMAND [options...]

Commands:
  foo       Do something awesome
  bar       Another cool command

Options:
  -h, --help    Show help message
  -l, --list    List all available commands

Development Guide

1. Define Commands

Any function prefixed with __ automatically becomes an exposed CLI subcommand.

__build() {
    echo "Building project..."
}

Note

For internal calls, directly invoke __<command> "$@". Only use run_cmd <command> "$@" when you explicitly need to update the global CMD context.

2. Self-Documenting Comments

Documentation is extracted directly from the source using internal awk magic. Prefix your docstrings with ## right above your function.

Variable Expansion: Variables within the ## blocks are expanded at runtime. Available variables:

• ${CMD}: Current subcommand name.
• ${SELF}: Script filename.
• ${SELF_PATH}: Absolute path to the script.
• ${SELF_DIR}: Directory containing the script.
• Any variable defined via # @ui tags.

## Compile the source code.
##
## Usage:
##   ${CMD} [options]
##
## Options:
##   -v, --verbose    Enable verbose output
__compile() {
    # implementation...
}

3. UI and Styling (ANSI-DSL)

Define global ANSI styles using # @ui tags at the top of the script. The framework prepends the \e[ escape sequence automatically.

Use # @off to terminate the parser early and avoid unnecessary overhead.

monobash includes these core styles:

# @ui COFF=0m BOLD=1m FAINT=2m ITALIC=3m ULINE=4m INVERT=7m HIDE=8m DLINE=9m
# @off

You can easily declare custom color palettes:

# @ui RED=31m GREEN=32m YELLOW=33m BLUE=34m 
# @ui ERROR=31;1m SUCCESS=32;1m

Applying styles in code and docs:

## Deploy to production.
## Returns ${SUCCESS}0${COFF} on success, ${ERROR}1${COFF} on error.
__deploy() {
    echo -e "${BOLD}Deploying...${COFF}"
}

4. Global Context

The following global variables are available anywhere inside your functions:

• IS_APPLET: 1 if executed via symlink, 0 otherwise.
• CMD: The name of the currently executing subcommand (without the __ prefix).
• UI_VARS: An associative array containing all parsed @ui styles (e.g., ${UI_VARS[BOLD]}).

License

MIT LICENSE