||1 day ago|
|.vscode||2 months ago|
|art||1 year ago|
|departments||1 day ago|
|i18n||1 day ago|
|other||2 months ago|
|LICENSE||1 year ago|
|README.md||7 months ago|
|butler||2 months ago|
|makefile||7 months ago|
|taskeditor.sh||2 months ago|
Sapphire Butler is an extensible task executor and shell script codebase that aims to make certain tasks easier to do or simply more user friendly.
It is designed to work perfectly on Sapphire GLS and it's parent distributions Arch and Parabola as well as their children, but there is only a little support for other distributions and the use of Sapphire Butler on those systems is cautioned against until proper support can be given for them.
Arch User Repository
Sapphire Butler is available in the Arch User Repository as
sapphire-butler. Install it with your favorite AUR helper.
Clone the Git repository with
git clone https://codeberg.org/Sapphire/sapphire-butler run
sudo make install in the source tree to install Sapphire Butler manually.
Like real life butler work, Tasks are organized into Departments. There are Administrative (admin), Fun (fun), Network/Internet (net), Package Management (pkg), and Productivity (prod) tasks. You can view all tasks in a department by simply typing the department.
> butler admin [❖ BUTLER] Available tasks in the admin department: Name Department/Task ------------------------------------------------------------ Home Backup admin/homebackup Turn on NTP admin/ntpon Install a LAMP Stack admin/lampinstall Update GRUB Bootloader Config admin/updategrub Enable zRAM for Swap Service admin/zramswapenable Turn off NTP admin/ntpoff Uninstall zRAM for Swap admin/zramswapuninstall Generate Locales admin/localegen Disable zRAM for Swap Service admin/zramswapdisable Install zRAM for Swap admin/zramswapinstall
To run any task, specify the department followed by the task, separated by a forwards slash.
> butler net/neton [❖ BUTLER] Running task "Turn on networking"... [❖ BUTLER] I successfully turned on networking. [❖ BUTLER] Task "Turn on networking" completed.
If a task name is unique, it is also possible to issue only the task name and run the task.
A yad-powered GUI interface is available by executing
- Code 50 Tasks.
- Translate all tasks into at least two non-English languages.
Contributing / Adding Tasks
Adding a task to Sapphire Butler is easy and only requires a bit of shell scripting knowledge (or more, if you are doing something more complicated).
If you want to make this process more simple, there is a Task Editor included with Sapphire Butler. If you want to make edits to the source tree, you can run the
taskeditor.sh script with
bash taskeditor.sh command.
If you have Sapphire Butler installed, you can use it's
admin/taskeditor task to make edits or add to your Sapphire Butler installation. Just remember that once you upgrade, your changes might be overwritten.
In this tutorial, we will manually create a task to play a Lofi Hip Hop Radio Station by working directly from the source tree. You can obtain the source tree by running
butler prod/butlersrc, and then you can enter it by running
Creating the Language File
We need to create a language file so that your task has a name and description and is translatable.
First go into the i18n directory of the source tree, choose what department you want to use, and then change into that directory in the source tree and make another directory with your task name. Then change into that directory.
cd i18n/fun mkdir lofihiphopradio cd lofihiphopradio
Create a file that is named the language code of whatever language you making the language file for. For example, English is en, Spanish is es, Chinese is zh, French is fr, German is de, Italian is it, Japanese is ja, Russian is ru. Check here for a larger list.
In this file, we need to define variables that will contain text in our spoken language. The required variables are
description. We should also define variables here that will contain text for our task later, but this is optional if there are none needed.
name="Play LoFi Hip Hop Radio" description="Plays a LoFi Hip Hop Icecast Radio Station."
Write that file and then go back to the root of the source tree.
Creating the Task Script
Next choose what department you want to use, and then change into that directory in the source tree and make another directory with your task name. Then change into that directory.
cd departments/fun mkdir lofihiphopradio cd lofihiphopradio
Create a file called
task.sh. Here we write the script that will be executed when the user wants to use our task. Since our task right now is just playing an internet radio station, our task is very straight forward.
Things to note:
- There is no need to specify a shebang (ex.
- Don't use
butlermsgto send messages, if needed.
- There shouldn't be any plaintext in this file unless it is being translated in the script. Use the variables you should have set in the language file in the
i18ndirectory as that file is sourced before this script is run.
The contents of our
task.sh will contain the following:
clementine -pl http://hyades.shoutca.st:8043/stream
Feel free to use this directory for any files that your task needs such as images or configuration files.
Creating the Dependency List
We have now written a task that uses the
clementine music player. But we cannot just make a guess as to if the user has clementine installed. We have to add
clementine to our
dependencies.list, a file containing the required packages for running your task.
While in our same directory we have the
task.sh file, we need to make a
dependencies.list file. This file will contain each package that our task needs on it's own line.
For our task, we simply have
clementine on it's own line:
Say if we had a seperate package that the task needed, we would add it like this:
We have now created a task. Go back to the root of the source tree and then run
sudo make install to install Sapphire Butler, then run your task to test it.
There are infinite possibilities of what you can put into a task. Check out some of the preexisting tasks to learn more tips and tricks.