Scripting

Introduction

XPipe's scripting functionality for shells allows you to extend and customize your workflow with your own shell scripts. Scripts can be used in many places in XPipe, each with unique properties. In summary, you can run scripts

• On remote shell init in your terminal, in addition to the shell's rc files
• In the connection hub, on the dedicated scripts button for each connection
• In the file browser, with selected file paths as script arguments
• In an active terminal session opened from XPipe

Shell compatibility

Each remote system you connect to has a specific login shell dialect. This can be anything like cmd, powershell, bash, etc. Any scripts you create will also be bound to that shell dialect. For example, if you write a bash script, it won't run on a powershell-based connection. Therefore, the first choice you have to make is which shell dialect you are creating a script for:

Any script declared as a sh script will be able to run in any posix-related shell environment, such as bash or zsh. If you intend to run a basic script on many different systems, then using only sh syntax scripts is the best solution.

Scripts that are declared as normal powershell scripts can also run in pwsh environments.

Enabled state

Each script has a toggle that you can use to enable or disable a script. A script must first be enabled for it to appear anywhere in XPipe. This toggle allows you to control which scripts you want to use at the moment, so you can ignore the ones you don't need at the moment without having to delete them. You can also enable whole groups of scripts by toggling the group itself.

It is important to always check if a script is enabled if it does not appear in the menus as expected.

Authoring scripts

Since you can use a script in several different scenarios, you should first choose which execution type you want to create the script for. These different types are explained in detail below.

You can also check multiple boxes for a script's execution types if you want to use it in multiple scenarios.

Editing

You can either edit scripts in-place in the text box or use the external edit button in the top right corner to launch an external text editor. Any changes you make in this external editor will be automatically applied when you save.

When creating scripts, you don't need to specify a shebang line for shells that support it, one will be added automatically with the appropriate shell type you specified earlier. Adding a shebang line won't break the script, but it's unnecessary here.

Dependencies

For more complex scripting tasks, it is also possible to create multiple independent reusable script parts, each of which performs a specific task. If you want to bring them all together, you can create a script with those other scripts as dependencies. This will make all the dependent scripts run before the actual script, allowing you to chain multiple scripts together and avoid duplication.

Init scripts

The idea of init scripts is to be able to take your environment configuration to all remote shells. Essentially, you can configure what commands to run when you log into a remote system in a terminal. For example, if you want certain aliases, prompt settings, or extensions to be automatically available in your remote shell session, then init scripts are the way to go.

Any script that is enabled, compatible with the remote system's shell, and marked as an init script will be run when a new terminal session is started on any connection.

Basic example

As a simple example, you can create a script like this

to have your aliases available in your remote shells.

Advanced example

Of course, you can create much more advanced init scripts. For example, if you want to have the starship prompt configured in all of your remote terminal sessions, you can use this script:

dir="/tmp/xpipe/$USER/scriptdata/starship"
export PATH="$PATH:$dir"
which starship > /dev/null 2>&1
if [ "$?" != 0 ]; then
    mkdir -p "$dir" && \
    which curl > /dev/null && \
    curl -sS https://starship.rs/install.sh | sh /dev/stdin -y --bin-dir "$dir" > /dev/null
fi
eval "$(starship init bash)"

This script also checks to see if it is already installed. If not, starship will be dynamically downloaded and installed on the system. Using such scripts allows you to implement complex initialization routines on your remote shells.

Shell environments

As an alternative to having all enabled init scripts run whenever a remote shell session is started, you can also create shell environment configurations to use only a selected subset of scripts specific to this environment. These don't even need to be enabled to run.

This is also important if you're looking to run scripts as root. Shell environments provide the ability to launch them elevated via sudo, so any scripts you run in them will also be run as root.

Runnable scripts

Scripts can also be run on demand on any system from the connection hub. Any script that is enabled, compatible with the remote system's shell, and marked as a runnable script can be run from the script context menu for a connection.

This is useful for actions you want to perform at any time. In this example, a simple

sudo apt update && sudo apt upgrade

script for a frequently performed action.

File browser scripts

All file browser sessions that work through shell connections also support the execution of arbitrary commands. In addition to the pre-existing actions found in the file context menu, you can add your own commands.

Any script that is enabled, compatible with the file browser session shell, and marked as a file script will appear in the file browser context menu.

Arguments

One of the core features of file scripts is the support of arguments, which are provided by the file browser selection. So if you have one or more files selected in the file browser, they are automatically passed as arguments to the script as normal. Essentially, it is the same as simply running myscript.sh "<file 1>" "<file 2>". The behavior of passing arguments is the same for all shells, so if you're implementing a cmd script instead, you can refer to it with ~%1, ~%2, and so on. The arguments are ordered by the time of selection.

Note that there is currently no verification for arguments, so if you have a different number of files selected than your script actually requires, you will still be able to call the script from the menu. So to avoid any mishaps, it is recommended to validate the script arguments to have the correct amount. This also applies to file types, so a script that takes a directory as input should check to see if it was not accidentally called on a file instead.

Execution

You can either run the script in a new terminal window, or in the file browser to just see its output. If your script requires any interactive input, you should run it in a terminal. If you only care about the output, and no interactivity is required, running it in the file browser will work fine.

For example, if you want to create a script that diffs two files, using the script

will allow you to do this by running the script with two files selected.

The working directory of the scripts will also be the current directory you are in the file browser. So it also makes sense to have scripts that don't take arguments and only work in the working directory.

Shell session scripts

A session script is intended to be called in a shell session in your terminal. Any script that is enabled, compatible with the session shell, and marked as a shell script is copied to the target system and placed in the PATH. This allows you to run the script from anywhere in a terminal session. The script name is lowercased and spaces are replaced with underscores, making it easy to invoke the script.

For example, with a simple shell script like

you can run it on any compatible system with git-push.sh "<message>" in a terminal session if the script is enabled. The script file will be automatically created by XPipe in the background on the target system and added to the terminal session PATH so that you can run it immediately.