https://github.com/xooooooooox/radp-bash-framework
A modular Bash framework providing structured bootstrapping, configuration management, logging, and a comprehensive toolkit for shell scripting.
https://github.com/xooooooooox/radp-bash-framework
bash bash-framework commandline scaffold
Last synced: 29 days ago
JSON representation
A modular Bash framework providing structured bootstrapping, configuration management, logging, and a comprehensive toolkit for shell scripting.
- Host: GitHub
- URL: https://github.com/xooooooooox/radp-bash-framework
- Owner: xooooooooox
- License: mit
- Created: 2026-01-01T08:53:31.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-02-05T19:39:25.000Z (about 1 month ago)
- Last Synced: 2026-02-06T00:44:22.680Z (about 1 month ago)
- Topics: bash, bash-framework, commandline, scaffold
- Language: Shell
- Homepage:
- Size: 1.11 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# radp-bash-framework
```
____ ___ ____ ____ ____ ___ _____ __ __
/ __ \/ | / __ \/ __ \ / __ )/ | / ___// / / /
/ /_/ / /| | / / / / /_/ / / __ / /| | \__ \/ /_/ /
/ _, _/ ___ |/ /_/ / ____/ / /_/ / ___ |___/ / __ /
/_/ |_/_/ |_/_____/_/ /_____/_/ |_/____/_/ /_/
```
[](https://github.com/xooooooooox/radp-bash-framework/releases)
[](https://copr.fedorainfracloud.org/coprs/xooooooooox/radp/package/radp-bash-framework/)
[](https://build.opensuse.org/package/show/home:xooooooooox:radp/radp-bash-framework)
[](https://github.com/xooooooooox/radp-bash-framework/actions/workflows/build-copr-package.yml)
[](https://github.com/xooooooooox/radp-bash-framework/actions/workflows/build-obs-package.yml)
[](https://github.com/xooooooooox/radp-bash-framework/actions/workflows/update-homebrew-tap.yml)
[](https://download.copr.fedorainfracloud.org/results/xooooooooox/radp/)
[](https://software.opensuse.org//download.html?project=home%3Axooooooooox%3Aradp&package=radp-bash-framework)
A modular Bash framework for building CLI applications with structured bootstrapping, configuration management, and a
comprehensive toolkit.
## Features
- **CLI Scaffolding** - Generate complete CLI projects with `radp-bf new myapp`
- **CLI Scaffolding Upgrade** - Upgrade existing CLI projects to latest scaffold with `radp-bf upgrade`
- **Annotation-based Commands** - Define commands using comment metadata (`@cmd`, `@arg`, `@option`)
- **Auto-discovery** - Commands are discovered from directory structure, supports nested subcommands
- **Shell Completion** - Generate Bash/Zsh completion scripts automatically
- **YAML Configuration** - Layered config system with environment variable overrides
- **Built-in Global Options** - `--config`, `--verbose`, `--debug` available for all CLI apps
- **Logging** - Structured logging with levels (debug/info/warn/error)
- **OS Detection** - Cross-platform utilities for distro, architecture, package manager detection
- **Path Utilities** - File system helpers, path resolution
- **IDE Code Completion** - BashSupport Pro integration for framework function and variable completion
- **Dev/Install Mode** - Automatic config path detection based on `_ide.sh` marker
## Requirements
- Bash 4.3+
- GNU getopt (for CLI argument parsing, auto-installed if missing)
- Linux: included in `util-linux`
- macOS: `brew install gnu-getopt`
- [yq](https://github.com/mikefarah/yq) (for YAML parsing, auto-installed if missing)
## Installation
### Homebrew (macOS)
```shell
brew tap xooooooooox/radp
brew install radp-bash-framework
```
### Script (curl)
```shell
curl -fsSL https://raw.githubusercontent.com/xooooooooox/radp-bash-framework/main/install.sh | bash
```
### Portable Binary (Single File)
Download and run - no installation required:
```shell
# Standard version (~100KB) - macOS Apple Silicon
curl -fsSL -o radp-bf \
https://github.com/xooooooooox/radp-bash-framework/releases/latest/download/radp-bf-portable-darwin-arm64
chmod +x radp-bf && sudo mv radp-bf /usr/local/bin/
# Full version (~20MB, zero dependencies) - macOS Apple Silicon
curl -fsSL -o radp-bf \
https://github.com/xooooooooox/radp-bash-framework/releases/latest/download/radp-bf-portable-full-darwin-arm64
chmod +x radp-bf && sudo mv radp-bf /usr/local/bin/
```
Available platforms: `linux-amd64`, `linux-arm64`, `darwin-amd64`, `darwin-arm64`
See [Installation Guide](docs/installation.md) for more options (RPM, OBS, portable, manual install, upgrade).
## Quick Start
### Create a CLI Project
```shell
radp-bf new myapp
cd myapp
./bin/myapp --help
```
This generates:
```
myapp/
├── bin/myapp # Entry point
├── src/main/shell/
│ ├── commands/ # Command implementations
│ │ ├── hello.sh # myapp hello
│ │ └── version.sh # myapp version
│ └── config/
│ ├── config.yaml # Configuration
│ └── _ide.sh # IDE support & dev mode marker
├── .radp-cli/ # Scaffold metadata (for upgrade)
└── install.sh # Installer script
```
### Upgrade Existing Projects
When the framework updates, upgrade your project's scaffold files:
```shell
radp-bf upgrade # Upgrade current directory
radp-bf upgrade ./myapp --dry-run # Preview changes
radp-bf upgrade --force # Overwrite modified files
radp-bf -v upgrade . # Upgrade with verbose output
```
The upgrade command tracks changes via `.radp-cli/` metadata directory and detects user modifications.
See [Upgrade CLI Projects](docs/installation.md#upgrade-cli-projects) for more options.
### Define Commands
Commands use annotation-based metadata:
```bash
# src/main/shell/commands/greet.sh
# @cmd
# @desc Greet someone
# @arg name! Required argument
# @option -l, --loud Shout the greeting
cmd_greet() {
local name="$1"
local msg="Hello, $name!"
if [[ "${opt_loud:-}" == "true" ]]; then
echo "${msg^^}"
else
echo "$msg"
fi
}
```
```shell
$ myapp greet World
Hello, World!
$ myapp greet --loud World
HELLO, WORLD!
```
### Subcommands
Create directories for command groups:
```
commands/
├── db/
│ ├── migrate.sh # myapp db migrate
│ └── seed.sh # myapp db seed
└── hello.sh # myapp hello
```
### Configuration
YAML configuration with automatic variable mapping:
```yaml
# config/config.yaml
radp:
extend:
myapp:
api_url: https://api.example.com
```
Access in code:
```bash
echo "$gr_radp_extend_myapp_api_url" # https://api.example.com
```
Override via environment:
```shell
GX_RADP_EXTEND_MYAPP_API_URL=http://localhost:8080 myapp hello
```
### Shell Completion
```shell
# Bash
myapp completion bash >~/.local/share/bash-completion/completions/myapp
# Zsh
myapp completion zsh >~/.zfunc/_myapp
```
## radp-bf CLI
The `radp-bf` command-line tool manages framework operations:
```shell
radp-bf new [dir] # Create new CLI project
radp-bf upgrade [dir] [opts] # Upgrade existing project scaffold
radp-bf path # Print framework paths (init|launcher|root)
radp-bf completion # Generate shell completion (bash|zsh)
radp-bf self-update # Update to latest version (portable only)
radp-bf version # Show framework version
```
**Global options** (for any command):
```shell
radp-bf -v upgrade . # Verbose output (info logs)
radp-bf --debug upgrade . # Debug output (debug logs)
```
**Shell completion for radp-bf:**
```shell
# Bash
radp-bf completion bash > ~/.local/share/bash-completion/completions/radp-bf
# Zsh
radp-bf completion zsh > ~/.zfunc/_radp-bf
```
## Documentation
- [Installation Guide](docs/installation.md) - All installation methods and upgrade instructions
- [Getting Started](docs/getting-started.md) - Create your first CLI project
- [CLI Development Guide](docs/user-guide/cli-development.md) - Complete guide to building CLI applications
- [Command Annotations](docs/user-guide/annotations.md) - `@cmd`, `@arg`, `@option`, `@example` reference
- [Configuration](docs/configuration.md) - YAML config system and environment variables
- [API Reference](docs/reference/api.md) - Toolkit functions and IDE integration
## Toolkit API
The framework provides utility functions organized by domain:
| Domain | Functions | Description |
|---------------|------------------------------------------------------|-----------------------|
| `radp_log_*` | `debug`, `info`, `warn`, `error` | Structured logging |
| `radp_os_*` | `get_distro_id`, `get_distro_pm`, `is_pkg_installed` | OS detection |
| `radp_io_*` | `get_path_abs` | File system utilities |
| `radp_exec_*` | `exec`, `exec_sudo`, `set_dry_run`, `is_dry_run` | Dry-run mode support |
| `radp_cli_*` | `discover`, `dispatch`, `help` | CLI infrastructure |
See [API Reference](docs/reference/api.md) for complete documentation.
## Related Projects
- [radp-vagrant-framework](https://github.com/xooooooooox/radp-vagrant-framework) - YAML-driven Vagrant framework
- [homelabctl](https://github.com/xooooooooox/homelabctl) - Homelab infrastructure CLI
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and release process.
## License
[MIT](LICENSE)