121 lines
7.2 KiB
Markdown
121 lines
7.2 KiB
Markdown
Bash TUI Toolkit
|
|
===
|
|
[](https://github.com/timo-reymann/bash-tui-toolkit/blob/main/LICENSE)
|
|
[](https://app.circleci.com/pipelines/github/timo-reymann/bash-tui-toolkit)
|
|
[](https://github.com/timo-reymann/bash-tui-toolkit/releases)
|
|
[](https://renovatebot.com)
|
|
[](https://pre-commit.com/)
|
|
[](https://github.com/timo-reymann/bash-tui-toolkit/releases)
|
|
|
|
<p align="center">
|
|
<img width="300" src="./.github/images/logo.png">
|
|
<br />
|
|
Toolkit to create interactive and shiny terminal UIs using plain bash builtins
|
|
</p>
|
|
|
|
## Features
|
|
|
|
- clean and standardized API
|
|
- provide a simple and clear default set of elements to use creating an interactive terminal UI
|
|
- clean and minimalistic design
|
|
- zero dependencies to be installed
|
|
- parts can be used modular
|
|
|
|
## Requirements
|
|
|
|
- [bash 3+](https://www.gnu.org/software/bash/)
|
|
|
|
## Installation
|
|
|
|
### Download and include in your scripts
|
|
|
|
1. Download the bundle (entire lib) or single compoennt
|
|
from [releases](https://github.com/timo-reymann/bash-tui-toolkit/releases)
|
|
2. Source the bundle in your script or embed, e.g.
|
|
```bash
|
|
source ./lib/bundle.bash
|
|
```
|
|
or simply copy it into your script.
|
|
|
|
### Source directly from release
|
|
|
|
> Note that this is not a recommended approach and only intended for quick testing or trying out another version.
|
|
|
|
1. Choose the bundle in the version you want to use from the available releases on the [gh-pages branch](https://github.com/timo-reymann/bash-tui-toolkit/tree/gh-pages).
|
|
2. Source it to your script on runtime:
|
|
1. Using `wget`
|
|
```bash
|
|
source <(wget -qO- https://bash-tui-toolkit.timo-reymann.de/latest/bundle.bash)
|
|
```
|
|
2. Using `curl`
|
|
```bash
|
|
source <(curl -qsS https://bash-tui-toolkit.timo-reymann.de/latest/bundle.bash)
|
|
```
|
|
|
|
## Usage
|
|
|
|
For a list of available modules and their documentation please check the [docs/modules](./docs/modules) folder
|
|
|
|
For a complete playground demo check [test.sh](./test.sh).
|
|
|
|
## Motivation
|
|
|
|
Providing a clean bash UI sometimes becomes a mess and interactivity is hard to achieve especially when it should be
|
|
portable.
|
|
|
|
The target is to provide a simple-to-use toolkit that can be dropped into any bash script and is compatible no matter
|
|
the target system.
|
|
|
|
## Documentation
|
|
|
|
- [Modules](./docs/modules) - Modules available and their usage
|
|
- [Compability table](./docs/Compatibility) - Known combinations of OS/Bash Version/Terminal emulators that work guaranteed
|
|
|
|
## Contributing
|
|
|
|
I love your input! I want to make contributing to this project as easy and transparent as possible, whether it's:
|
|
|
|
- Reporting a bug
|
|
- Discussing the current state of the configuration
|
|
- Submitting a fix
|
|
- Proposing new features
|
|
- Becoming a maintainer
|
|
|
|
To get started please read the [Contribution Guidelines](./CONTRIBUTING.md).
|
|
|
|
## Development
|
|
|
|
### Requirements
|
|
|
|
- [GNU make](https://www.gnu.org/software/make/)
|
|
- [Docker](https://docs.docker.com/get-docker/)
|
|
- [pre-commit](https://pre-commit.com/)
|
|
|
|
### Build
|
|
|
|
```
|
|
make build
|
|
```
|
|
|
|
### Update documentation
|
|
|
|
To update the module documentation you just need to run
|
|
|
|
```sh
|
|
make generate-docs
|
|
```
|
|
|
|
This builds the documentation inside a docker container and updates the
|
|
repo locally. Afterwards just commit the docs with your code changes
|
|
|
|
|
|
## Credits
|
|
|
|
- Logo
|
|
- Bash logo from [pngegg](https://www.pngegg.com/en/png-pxpgu)
|
|
- Toolbox logo from [IconExperience.com](https://www.iconexperience.com/g_collection/icons/?icon=toolbox)
|
|
|
|
## Alternatives
|
|
- [kahkhang/Inquirer.sh](https://github.com/kahkhang/Inquirer.sh) - List, Checkbox and Text Input with more advanced
|
|
validation
|