cliffs is a small CLI built on brick that makes interacting with scripts
to rule them all (STRTA) easier.
It is oriented around three features that should alleviate some common pain points:
| Pain Point | cliffs help |
|---|---|
| Remembering what script does what | Rendering script descriptions next to names |
| Remembering what arguments scripts take | Rendering --help output with a hotkey |
| Separating help from where you run the command | Providing a small terminal for command submission with the table |
You can see an example by running cliffs in this directory. Running the
executable will get you an interactive table of scripts like:
┏━━━━━━━━━━━━━━━━━━━━━━━Scripts━━━━━━━━━━━━━━━━━━━━━━┓
┃ bootstrap ┃ Set stuff up ┃
┃ server ┃ Start servers ┃
┃ update ┃ Update dependencies and containers ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
You can press the up / down arrow to select different scripts, which will update
the Help output box (not shown in paste above).
Scripts can have short descriptions as well as their help text. You can include
such information in a table in a README. Your README must live in a file called
README.md. cliffs will show the description from the table in the README for
any scripts that have them. To detect the short descriptions automatically, your
README must have a table with two columns named "Script Name" and
"Description" somewhere in the README.
An example table is below:
| Script Name | Description |
|---|---|
| release | Create tags and CHANGELOG entries for a new release |
| bootstrap | Set stuff up |
| server | Start servers |
| update | Update dependencies and containers |
If you have a similar table but with different names, you can specify those at
runtime! You can use the --script-name-column / -s option to control
the name of the column where script names can be found, and the
--description-column / -d option to control the name of the column
where the descriptions are found. Both have defaults in case your names
match "Script Name" and "Description" already.
Relases are handled by chan and GitHub Actions. To create a new release:
- rotate the changelog:
chan release v<VERSION> - bump versions in
package.yamlandcliffs.cabal(the second withhpack) - commit the release:
git commit -am "Update changelog for <VERSION> - tag the release:
git tag -S -a v<VERSION> -m "Release v<VERSION>" - push the tag:
git push origin --tags v<VERSION> - create the GitHub release after the build completes
Everything up to creating the GitHub release after the build is handled by the
scripts/release script. The GitHub action will create the release itself.
After the release exists, you should:
- paste the changelog for this release
- add an installation command like:
nix-env -i -f https://github.com/jisantuc/cliffs/archive/refs/tags/VERSION.zip. This command will work across platforms wherenixis installed, so MacOS / Linux / NixOS / anyone else with nix should be able to call the install command and get a working executable.