Adding Custom Command Entries

Overview

By default, the installation of Ste-Mux will include the deployment of the file .ste-mux-custom.sh. This is a script file that is intended to contain custom shell commands that you can trigger from within Ste-Mux.

The standard file comes pre-configured with some example commands, but you are free to customise the file and add your own.

Editing the Custom Commands File

Because the file name begins with a period (".") it will be hidden in the file system by default. To view the file, you need to set Finder or your file management app of choice to show hidden files.

The file is purposefully set as hidden to stop SwiftBar identifying it as a plugin.

File Structure

The file structure consists of three sections.

The first section sets up ZSH as the shell of choice (the default shell on modern macOS), and includes some comments.

#!/bin/zsh
# This file gets executed by ste-mux.sh, so you can use it to add your own custom commands
# There are two clearly marked sections. One you should leave alone, and one you can feel free to edit.

The next section, bounded by a couple of markers should be left alone. This section sets up the file to be used with Ste-Mux. The section begins with...

# -----------------------------------------------------
# ⬇ ⬇ ⬇ ⬇ ⬇ WARNING: DO NOT EDIT THIS SECTION ⬇ ⬇ ⬇ ⬇ ⬇
# ----------------------------------------------------

...and ends with...

# -----------------------------------------------------
# ⬆ ⬆ ⬆ ⬆ ⬆ WARNING: DO NOT EDIT THIS SECTION ⬆ ⬆ ⬆ ⬆ ⬆
# -----------------------------------------------------

Conversely, the section where commands should be added is the third section and is clearly labelled. The section begins with...

# ---------------------------------------------
# ⬇ ⬇ ⬇ ⬇ ⬇ PLEASE EDIT THIS SECTION ⬇ ⬇ ⬇ ⬇ ⬇
# ---------------------------------------------

...and ends with...

# ---------------------------------------------
# ⬆ ⬆ ⬆ ⬆ ⬆ PLEASE EDIT THIS SECTION ⬆ ⬆ ⬆ ⬆ ⬆
# ---------------------------------------------

Menus

SwiftBar, and by extension Ste-Mux utilises a menu based system to access information and actions. If you are not already familiar with how menus are constructed, it may be worth familiarising yourself with the Menus page, which describes how to add items of information, sub menus, and menu separators.

Example Commands

The following examples are all available by default in the .ste-mux-custom.sh. "Please Edit Me" section. All of the non-SSH commands are set to appear under the "Custom Commands" sub menu.

Generic Shell Commands

Throughout these examples, you will see the use of the function runCommand. This function is defined in the Common Functions section, and is intended to make the definition of a shell command to Ste-Mux/SwiftBar, easier.

The first parameter of runCommand is the path to the main plugin script being run by SwiftBar. This is accessible through the OSP (Original Script Path) variable, which by default is set to be equal to an environment variable STEMUX, which is set by the main script.

OSP was used rather than STEMUX as this helps with testing and debugging multiple script files.

Say Hello

The following command will say "Hello, I am Ste-Mux" when it is executed. The peculiar spelling used as the input to the say command simply helps the pronunciation.

Because there is no final appears under the custom argument for the sub menu level, a level 0 is assumed. However, because the title "Say Hello" is prefixed with two hyphens, the entry will appear as a first level sub menu item.

runCommand "$OSP" "--Say Hello" "say Hello. I am stee mux"

Open Terminal

The following command will open the terminal application.

Note that unlike the previous command, this command includes a sub menu level entry of "1" at the end. Therefore it will be positioned as a first level sub menu item, but does not reply on hyphens in the name to specify that.

runCommand "$OSP" "Open Terminal" "open -a Terminal" 1

Copy Desktop File Listing

This command will take a file listing of the current user's Desktop folder (using ls -hal), and copy it to the system clipboard.

runCommand "$OSP" "Copy Desktop file listing" "ls -hal ~/Desktop | pbcopy" 1

Kill All Jekyll Processes

More complex command sequences involving various types of quoting is also possible. This command will kill all processes for Jekyll web servers.

runCommand "$OSP" "Kill all Jekyll processes" 'ps aux | grep jekyll | awk '"'"'{print $2}'"'"' | xargs kill -9' 1

Generic SSH Command

Much like the runCommand for generic shell commands, Ste-Mux also includes an sshSessionAddition function to make it easier to add details to trigger an SSH session. This function is once again defined in the [[Common Functions#sshSessionAddition|Common Functions]] section.

If you have a lot of SSH sessions you wish to add, you may wish to consider placing them in one or more sub menus.

SSH to Mac Mini

This command is commented out in the example file as it cannot be made generic enough to be applicable to everyone. If uncommented, it will appear at the root menu level as it does not use any hyphens at the start of the name, or specify a sub menu level at the end.

When executed, this command will attempt to open a terminal SSH connection on port 22 to a device on the local network named "macmini.local". The user ID to be used in the connection is "hal9000".

sshSessionAddition "$OSP" "SSH: Mac Mini" "hal9000" "macmini.local" "22"