First Steps

Got qtermy running? Great! Follow along with this tutorial to familiarize yourself with some aspects of how TermySequence works.

First off, when running qtermy for the first time, you will be greeted with the Setup Tasks dialog. Here you can enable shell integration and set up your persistent user server (discussed below) as a systemd user service. Skipping this won't break anything immediately, and you can always run termy-setup by hand later.

With that out of the way, what you see before you should resemble this:

If the shell prompt appears as plain black text without a "P" mark next to it, shell integration isn't enabled in the terminal. Follow the instructions here to install it. This is optional but highly recommended, since it enables many useful features within qtermy.

Terminals, Servers, Windows, and Panes

Let's have a look at the Terminals tool first. It's at the top of the window by default, but it can be dragged around and docked elsewhere. The Terminals tool displays an ordered list of all the currently connected servers (i.e. terminal multiplexers) and their terminals. Don't worry if some terminal thumbnails look improperly sized. The terminals will resize when switched to. The starting terminal size can be adjusted in the profile settings (discussed below).

By default, qtermy connects to not one but two servers on startup. These are your transient local server (on the left) and your persistent user server (on the right). The transient local server is run directly by qtermy as a private child process. It will go away when the application is closed and its terminals will be lost. However, this also means that it's part of your desktop session (hence the desktop icon) and you can launch GUI applications and the like from shell prompts. In contrast, the persistent user server is intended to run forever, or least until the next reboot. This is the typical usage model for terminal emulator multiplexers which are "detached" from the user login session.

At this point, let's make it easier to tell the terminals apart. Right-click on a terminal and choose Adjust Colors, then select a predefined color theme from the Theme dropdown. Choose a different theme for each terminal or run some commands in the terminals to produce different output. These color adjustments are only temporary; we'll discuss profile settings below.

One thing you may have noticed is the big number right in the middle of the terminal. This number is the pane or viewport index number. Open a new window using File→New Window. Now experiment with switching terminals by clicking them in the Terminals tool of either window or by pressing Shift+Left and Shift+Right.

In qtermy, terminals are independent of the viewports which display them. It's possible to open multiple viewports onto the same terminal and scroll them independently. The Terminals tool always displays the terminal screen in its native size, along with the index number of any viewport showing the terminal. In addition to opening new windows, additional viewports can be created using the split window actions under View→Split View.

Keymap Tool

Okay, so Shift+Left and Shift+Right switch terminals in the current viewport. What other key bindings are there? Bring up the Keymap tool by clicking its tab or using Tools→Activate→Keymap. In this tool, a complete list of key bindings is displayed. It's specifically designed to help you get up to speed with the keyboard.

A word about keymaps: they are highly customizable. Key bindings come in two flavors: action bindings and literal bindings. A literal binding sends some UTF-8 text to the terminal as input. An action binding runs an action, which tells qtermy to do something. There are roughly 300 actions to choose from, and you can write your own in Javascript. All of qtermy's menus are just lists of action bindings.

qtermy has a command mode for constructing dual-mode keymaps in the vi style. It's also possible to create combination bindings with two separate keypresses. But the keymap mode that's most important to know about is selection mode.

Run a command such as man ls that prints some text. Now, make a selection with the mouse. In the Keymap tool, you'll see that selection mode is now active and along with it a set of key bindings for mouseless selection editing. Use the space bar to choose a selection "handle" and then try using the WASD bindings to move the handle around. Other selection mode bindings are shown in the Keymap tool. Press Escape to cancel the selection and exit selection mode.

Selection mode, along with many other things, can be configured in the global settings (Settings→Edit Global Settings).

Profile Settings

Let's make it so the two local servers have different color terminals by default. First, undo the temporary changes made above using View→Undo All Adjustments. This restores all terminals to the settings specified in their profiles.

Profile? What's that? Choose Settings→Manage Profiles and in the Manage Profiles window that appears, select the Default profile and click Edit Profile.

What appears is the Settings Editor dialog used to edit most of qtermy's settings objects. Of particular note in this dialog are the little question marks along the right-hand side, one for each individual setting. Clicking those will bring you to the relevant documentation on this site.

We want to change the profile's color theme, so find the color theme setting (it's in the Appearance category) and select your preferred color theme from the dropdown. Then click OK.

Next, click Clone Profile to clone the default profile. Give the new profile the name "Transient". In the settings editor window for the new profile, change the color theme to be different from the one in default profile. Click OK in both dialogs.

Now we'll make it so the transient local server uses the new profile by default. Click on the transient local server (desktop icon) in the Terminals tool, then choose Server→Edit Server. This brings up a settings editor for another type of settings object, the server settings. In the default profile option, select the new profile from the dropdown. Then click OK. Now, when you restart qtermy, the terminals belonging to the transient local server will use the new profile.

Connections

Let's try connecting to another server. For this part, it's assumed that:

• You have access to the root account (or some other user account) on your machine.
• That account has termy-server in its PATH.

To become root using sudo, go to Connect and choose Superuser (sudo). Otherwise, choose Switch User and in the dialog box that appears, select "Switch User (su)" from the dropdown, enter the username, and click OK.

If a password is required, the Connection Status dialog will appear to collect it. If all goes well, the connection will succeed and the user's persistent user server will appear in the Terminals tool.

TermySequence connections are a powerful thing. They can be established using any terminal-based program that runs termy-server in a remote environment, including ssh and container exec commands. They can be chained from one server to another. And they can be batched to reach servers across multiple hops. A single connection gets you as many terminals as you want, and as will be seen later, filesystem access as well.

The connection can be closed using Server→Disconnect. But leave it open for now; we'll be using it in the next section.

Files

One of the design goals of TermySequence is that files should come for free. That is to say, if a connection already exists to a server for the purpose of running terminals, it shouldn't be necessary to open additional connections using separate tools to download and upload files.

Open the Files tool by clicking the Files tab or using Tools→Activate→Files. In this tool, an ls-like listing of files is displayed. The listing will follow the terminal's current directory. Right click a file in the tool to see what's possible using the context menu.

For local servers, the Files tool is nice to have. But it's not just a local thing, it works with remote terminals too. Switch to a terminal belonging to the connection you opened in the previous step. Notice how you can see the root user's files in the Files tool. Try uploading a file to root's home directory. Try downloading a file to your home directory. In the course of doing this, you'll be introduced to the Tasks tool where qtermy reports all of its tasks such as uploads and downloads.

Try the following: create a text file in root's home directory with a .txt extension. Find it in the Files tool, right-click it, and choose Open with→Open with firefox. If all goes well, Firefox will open, showing the text file (this might fail, depending on the distribution, if unprivileged FUSE mounts are not permitted by default). How did Firefox, running as you, open a file in root's home directory? The answer can be seen in the Tasks tool: working with termy-server, qtermy performed a FUSE mount of the file across the connection, then opened the mounted file in Firefox. This feature makes it possible to edit files on remote systems with local desktop applications.

When finished with Firefox, right-click the mount task in the Tasks tool and cancel it to unmount the file.

Semantic Regions and Plugins

Run ls --hyperlink in a terminal. If your version of ls supports the --hyperlink switch, it will produce OSC 8 hyperlinks, which TermySequence supports. These provide the same features as the Files tool, including on remote servers.

If you have a git repository handy (with modified or staged changes), run git status in a terminal with shell integration active. If the relevant semantic parser is loaded, the output will be annotated with semantic regions produced by the plugin. Unlike OSC 8 hyperlinks, parser plugins don't require any support from the command itself, just ordinary text output that can be parsed.

To demonstrate custom action plugins, we'll create a key binding for the RectangleCopy plugin that ships with qtermy. Choose Settings→Edit Keymap "Default" to open the Keymap Editor dialog, then click New Rule to open the Binding Editor dialog. We'll bind Shift+F10 to the custom action, so under Key or Button, select F10 in the dropdown or focus the text field and press F10. In the Conditions table, click the Requirement for Shift and select "must be true". Finally, under Outcome, select "Perform action" and enter the text "CustomRectangleCopy" in the combo box. Click OK in both dialogs to save the changes.

Now, generate some text in a terminal, make a selection, and press Shift+F10 to execute the custom action. The inner rectangle of text defined by the selection will be copied to the clipboard and a brief animation will display at both ends of the rectangle. The RectangleCopy plugin is just one example of what can be done with qtermy's Javascript API for custom actions. See the file action.mjs for more custom action examples.

End

There are many additional features to explore within qtermy, but this is the end of the tutorial for now. We hope you find TermySequence useful!