Actions

Actions are the mechanism by which qtermy's internal functions are invoked. All of qtermy's menu entries and all (non-literal) key bindings are specified as action invocations. Actions can also be invoked in other ways:

An action invocation consists of an action name along with zero or more parameters, separated by vertical bar (|) characters. This means that parameters themselves cannot contain the vertical bar (|) character (there is no escaping mechanism). When invoking a custom action registered by a plugin, prepend the string "Custom" to the action's name.

Use the Index to jump to an action's documentation if you know its name.

Conventions

Some action parameters have consistent behavior across many different actions.

Terminal Lookup

Unless otherwise noted, the TerminalId action parameter has the following semantics:

  • If set to a UUID, the terminal with that identifier is used.
  • If unset, the active terminal is used.

Server Lookup

Unless otherwise noted, the ServerId action parameter has the following semantics:

Job Lookup

Unless otherwise noted, a combination of RegionId and TerminalId action parameters has the following semantics. Note that shell integration is required for job regions to be created.

  • If both are empty, the current job from the active viewport is used.
  • If RegionId is the string Selected, the selected job in the active viewport is used.
  • If RegionId is the string Tool, the selected job in the History tool will be used if that tool is active.
  • Otherwise, the terminal is looked up per Terminal Lookup and RegionId is parsed as an unsigned decimal number and looked up within that terminal.

If the job lookup is successful, the region's terminal is made active in the active pane.

Task Lookup

Unless otherwise noted, the TaskId action parameter refers to a specific task UUID or to the selected task in the Tasks tool if empty.

Selection Handle Lookup

A text selection within a terminal viewport has two handles: upper and lower, one at each end of the selection. Certain actions modify the active text selection by adjusting one of the handles. These actions are intended to be run from key bindings that are conditioned on selection mode. In these actions, the Arg action parameter used to choose a selection handle has the following semantics:

  • If Arg is 1, the upper handle is selected.
  • If Arg is 2, the lower handle is selected.
  • If Arg is 0 or empty, the currently selected handle is used. If no handle is selected, a default handle will be selected depending on the specific action.

The selected handle is drawn in a different color to distinguish it from the unselected handle.

Reference

AdjustTerminalColors TerminalId

Opens the Adjust Colors dialog for the specified terminal.

AdjustTerminalFont TerminalId

Opens the Adjust Font dialog for the specified terminal.

AdjustTerminalLayout TerminalId

Opens the Adjust Layout dialog for the specified terminal.

AdjustTerminalScrollback TerminalId

Opens the Adjust Scrollback dialog for the specified terminal.

AnnotateCommand RegionId TerminalId

Opens the Create Annotation dialog to annotate the command text of the specified job. RegionId can refer to either a command region itself, or its parent job.

AnnotateOutput RegionId TerminalId

Opens the Create Annotation dialog to annotate the output text of the specified job. RegionId can refer to either an output region itself, or its parent job.

AnnotateRegion RegionId TerminalId

Opens the Create Annotation dialog to annotate the first line of the specified job. RegionId can refer to any region.

AnnotateScreen Row

Opens the Create Annotation dialog to annotate the specified row within the active viewport. Row is a decimal integer measured from the top of the screen (if zero, positive, or unspecified) or from the bottom of the screen (if negative).

AnnotateSelection

Opens the Create Annotation dialog to annotate the selected text in the active viewport.

CancelTask TaskId

Cancels the specified task.

ClearAlert TerminalId

Clears any running alert on the specified terminal. Also clears any "urgent" indicator icon set on the terminal thumbnail by the ShowIndicator alert setting.

ClearTerminalScrollback TerminalId

Clears the scrollback buffer of the specified terminal.

CloneTerminal Duplicate TerminalId

Clones the specified terminal, producing a new terminal on the same server. If Duplicate is 1, the scrollback buffer (including all regions) is duplicated in the new terminal. Otherwise, only the profile settings and any settings overrides are copied and the new terminal starts empty.

CloseTerminal TerminalId

Closes the specified terminal. This may prompt for confirmation, depending on the value of the PromptClose profile setting. If the terminal is hosting a connection to a server, the connection will be closed.

CloseWindow

Closes the current application window. If there is only a single application window, equivalent to QuitApplication.

CommandTerminal ProfileName ServerId Cmdspec

Creates a new terminal with ServerId and ProfileName specified as in NewTerminal. Cmdspec is an executable name and argument vector (including argument zero) separated by unit separator (0x1f) characters. The command specified by Cmdspec is run in the new terminal rather than the command specified in the Profile setting.

This action is a specialization of LaunchCommand.

Copy TerminalId

Copies the selected text in the specified terminal to the clipboard. If there is no selected text, an empty string will be copied. If selection mode is active and ExitSelectModeOnCopy is enabled, the selection will be cleared following the copy.

CopyAll TerminalId

Copies the entire scrollback contents in the specified terminal to the clipboard.

CopyCommand RegionId TerminalId

Copies the specified job's command text to the clipboard. If the job is not found, an empty string will be copied.

CopyDirectoryPath DirPath

If DirPath is empty, the enclosing directory path of the selected file in the Files tool is copied to the clipboard. Otherwise, DirPath is copied.

CopyFile Format ServerId RemotePath

Initiates a task to copy the contents of the file named by the absolute path RemotePath on the specified server to the clipboard. If RemotePath is empty, the selected file in the Files tool is used.

CopyFilePath FilePath

If FilePath is empty, the path of the selected file in the Files tool is copied to the clipboard. Otherwise, FilePath is copied.

CopyImage Format TerminalId ContentId

Initiates a task to copy the named content item in the specified terminal to the clipboard. If Format is 0, the data is treated as UTF-8 text. If Format is 1, the data is treated as an image, parsed using Qt5's QImage class. If Format is empty, the data is treated as text if it's valid UTF-8 and as an image otherwise. Otherwise, Format is treated as a MIME type and the data is placed on the clipboard using that type.

Content items are loaded into a terminal using the termy-download, termy-imgcat, or termy-imgls utilities. Note that inline images may be reduced to thumbnails. To ensure that the original image data is downloaded, download the image file itself rather than the content item.

CopyJob RegionId TerminalId

Copies the specified job's full text to the clipboard. If the job is not found, the clipboard is not touched.

CopyOutput RegionId TerminalId

Copies the specified job's output text to the clipboard. If the job is not found, the clipboard is not touched.

CopyRegion RegionId TerminalId

Looks up the specified region in the specified terminal and copies its contents to the clipboard. Note that this is not a Job Lookup. RegionId can refer to any region.

CopyScreen Format TerminalId

Copies the contents of a viewport or terminal screen to the clipboard. If TerminalId is set, the contents of the specified terminal's screen are copied to the clipboard as text and Format is ignored. Otherwise, the contents of the active viewport are copied as text if Format is empty, or as a PNG image if Format is png.

CopySemantic RegionId TerminalId

Looks up the specified semantic region in the specified terminal and copies its contents to the clipboard. Note that this is not a Job Lookup. RegionId must refer to a region created by a semantic parser.

CopySuggestion Index

If Index is empty, the selected suggestion in the Suggestions tool is copied to the clipboard. Otherwise, the nth suggestion is copied, indexed from 0, specified by Index.

CopyTaskDirectoryPath TaskId

If the specified task has a local output file associated with it, copies the enclosing directory path of that file to the clipboard.

CopyTaskFile Format TaskId

If the specified task has a local output file associated with it, initiates a task to copy the contents of that file to the clipboard. See CopyFile.

CopyTaskFilePath TaskId

If the specified task has a local output file associated with it, copies the path of that file to the clipboard.

CopyUrl Url

Copies the URL string Url to the clipboard.

DecreaseFont

Decreases the font size in the active viewport.

DeleteFile ServerId RemotePath

Initiates a task to delete the file or directory named by the absolute path RemotePath on the specified server. If RemotePath is empty, the selected file in the Files tool is used. A confirmation prompt may be shown, depending on the value of the DeleteFileConfirmation global setting and whether RemotePath is a file or directory. Non-empty directories will be recursively removed.

DisconnectServer ServerId

Ends the connection to the specified server.

DisconnectTerminal TerminalId

If the specified terminal terminal hosts a connection to a server, ends the connection.

DownloadFile ServerId RemotePath LocalPath

Initiates a task to download the file named by the absolute path RemotePath on the specified server. If RemotePath is empty, the selected file in the Files tool is used. The local destination LocalPath is interpreted as follows:

  • If set to the string <Prompt>, a save file dialog will be shown.
  • If empty, the download folder specified by the DownloadLocation server setting or DownloadLocation global setting is used.
  • If set to an existing directory, the file will be saved to that directory.
  • If set to a path with a filename that does not exist, the file will be saved to that name.

If the destination file already exists, the file may be saved under a different name, a confirmation prompt may be shown, or the task may fail, depending on the value of the DownloadFileConfirmation global setting.

Downloads from local servers are not allowed unless the LocalDownloads global setting is enabled.

DownloadImage TerminalId ContentId LocalPath

Initiates a task to download the named content item in the specified terminal. LocalPath is interpreted as in DownloadFile.

Content items are loaded into a terminal using the termy-download, termy-imgcat, or termy-imgls utilities. Note that inline images may be reduced to thumbnails. To ensure that the original image data is downloaded, download the image file itself rather than the content item.

EditGlobalSettings

Opens a settings editor dialog to edit the Global settings.

EditIconRules

Opens the Icon Rules Editor.

EditKeymap KeymapName

Opens the Keymap Editor to edit the keymap named by KeymapName, or the keymap associated with the active terminal if empty.

EditProfile ProfileName

Opens a settings editor dialog to edit the profile named by ProfileName, which is interpreted as follows:

EditServer ServerId

Opens a settings editor dialog to edit the Server settings for the specified server.

EditSwitchRules

Opens the Profile Rules Editor.

EventLog

Opens the Event Log.

ExitFullScreen

Exits full screen mode, if active.

ExitPresentationMode

Exits presentation mode, if active.

ExtractProfile TerminalId

Opens the Extract Profile dialog to create a new profile from the settings in the specified terminal.

FetchImage TerminalId ContentId

Initiates a task to download the named content item in the specified terminal and display it inline. This may be done automatically, depending on the RenderInlineImages server setting and RenderInlineImages global setting.

FileFirst

Selects the first file in the Files tool.

FileLast

Selects the last file in the Files tool.

FileNext

Selects the next file in the Files tool, or the first file if there is no current selection.

FilePrevious

Selects the previous file in the Files tool, or the last file if there is no current selection.

FileSearch

Opens and focuses the search bar within the Files tool.

FileSearchReset

Clears the current search within the Files tool.

Find

Raises the Search tool and focuses the search bar within it. Pressing Return or Escape in the search bar will return focus to the terminal viewport.

FirstTerminal

Activates the first terminal on the first server in the Terminals tool.

HelpAbout

Opens the application help-about dialog.

HideServer ServerId

In the active window, hides all terminals belonging to the specified server in the Terminals tool. See HideTerminal.

Use ShowServer to unhide the terminals.

HideTerminal TerminalId

In the active window, hides the specified terminal in the Terminals tool. The terminal's thumbnail will not be shown, and navigation actions such as NextTerminal and PreviousTerminal will skip over the terminal.

Use ShowTerminal to unhide the terminal.

HideTerminalEverywhere TerminalId

In all windows, hides the specified terminal in the Terminals tool. See HideTerminal.

HighlightCursor

Displays a brief animation at the cursor location in the active viewport.

HighlightSemanticRegions

Displays a brief animation over any hyperlinks or other semantic regions in the active viewport.

HistoryFirst

Selects the first job in the History tool.

HistoryLast

Selects the last job in the History tool.

HistoryNext

Selects the next job in the History tool, or the first job if there is no current selection.

HistoryPrevious

Selects the previous job in the History tool, or the last job if there is no current selection.

HistorySearch

Opens and focuses the search bar within the History tool.

HistorySearchReset

Clears the current search within the History tool.

IncreaseFont

Increases the font size in the active viewport.

InputSetFollower TerminalId

Sets the specified terminal to be an input multiplexing follower. Any input to the input multiplexing leader will be copied to the specified terminal.

InputSetLeader TerminalId

Sets the specified terminal to be the input multiplexing leader. Any input to the input multiplexing leader will be copied to all input multiplexing followers.

InputToggleFollower TerminalId

Toggles whether the specified terminal is an input multiplexing follower. See InputSetFollower.

InputUnsetFollower TerminalId

Unsets the specified terminal as an input multiplexing follower. See InputSetFollower.

InputUnsetLeader

Stops input multiplexing.

InspectTask TaskId

Opens a task status dialog to view the progress of the specified task.

LaunchCommand LauncherName ServerId Substitutions

Runs the specified launcher on the specified server. If LauncherName is empty or doesn't exist, the default launcher is used.

Markers may be substituted within the launcher's command using the Substitutions parameter, which consists of zero or more strings of the form X=value separated by unit separator (0x1f) characters. X is the marker's letter and value is the string (treated as a single word) to substitute at the location of %X within the command.

Depending on the configuration of the launcher and whether the server is local or remote, any of the following may occur:

  • A desktop application may be launched as in OpenDesktopUrl.
  • A command may be run as in RunCommand.
  • A command may be run with output shown in a dialog box as in PopupCommand.
  • A terminal may be opened to run a command as in CommandTerminal.
  • A command string may be written to the active terminal using WriteText.

Refer to Launcher for more information on launchers.

LocalPortForward ServerId Spec

Initiates a task to perform port forwarding between the application and the specified server. The listening socket is on the local machine and outbound connections are made on the remote machine.

Spec has the format LocalSpec:RemoteSpec with each part having the following format:

  • For TCP sockets: 0:Address:Port or 0:[Address]:Port if the address contains colon characters. For a listening socket bound to all addresses, use an empty address.
  • For Unix-domain sockets: 1:Path. For listening sockets, the socket file will be created but its parent directory must exist and be writable.

Port forwarding tasks can be launched on demand via the Manage Port Forwarding window or automatically at server connection time via server PortForwardingRules.

ManageAlerts

Opens the Manage Alerts window.

ManageConnections

Opens the Manage Connections window.

ManageKeymaps

Opens the Manage Keymaps window.

ManageLaunchers

Opens the Manage Launchers window.

ManagePlugins

Opens the Manage Plugins window.

ManagePortForwarding

Opens the Manage Port Forwarding window.

ManageProfiles

Opens the Manage Profiles window.

ManageServers

Opens the Manage Servers window.

ManageTerminals

Opens the Manage Terminals window.

ManpageTerminal Manpage

Opens a terminal on the local server using the server's default profile and runs the command "man Manpage" rather than the command specified in the Profile setting.

This action exists mostly to implement the "View Man Page" entry in the Help menu. For a more flexible way to run commands in new terminals, see Launcher.

MountFile Readonly ServerId RemotePath

Initiates a task to perform a FUSE mount of the file or directory named by the absolute path RemotePath on the specified server, which must not be a local server. If RemotePath is empty, the selected file in the Files tool is used.

If Readonly is 1 and RemotePath refers to a file, the mount will be made read-only. If RemotePath refers to a directory, the mount will always be made read-only regardless of Readonly.

The user account under which qtermy is running must have permission to perform unprivileged FUSE mounts using fusermount3(1), which may require adding the user to a "fuse" group. Refer to the documentation for your distribution's FUSE package.

A temporary mountpoint folder will be created in the application's runtime directory. After the mount has been made, the task's output file will be set so that the mounted path can be opened from the Tasks tool or via OpenTaskFile, OpenTaskDirectory, and similar actions. The configured automatic action for mount tasks in the Global settings will be launched, if any.

The task will keep running until a cancel, timeout, or server connection loss. If the status of the task is "Idle" or "In Use", the mount is set up and ready to use. To unmount, ensure all applications and terminals referencing mounted files have been closed, then cancel the task using the Tasks tool or CancelTask action.

For read-write mounts, local applications such as text editors may create temporary files (but not directories) within the mountpoint folder. These will be written to underlying local storage. File rename operations to and from the mounted remote file are supported. Some applications may perform file operations that aren't supported by qtermy's FUSE filesystem implementation. Test each application for compatibility with qtermy FUSE mounts before using this feature to edit files in production.

Warning

If qtermy is forcibly closed by a KILL signal, the FUSE mount will not be properly unmounted and may need to be cleaned up manually using umount(8) and fusermount3(1). Furthermore, a read-write mount which is interrupted for any reason may cause data loss in the remote file. Use the remote file mount feature with caution.

NewConnection ConnType ConnArg ServerId

Initiates a task to create an anonymous connection of type ConnType. If ServerId is empty, the connection is run as a child process of qtermy itself. Otherwise, it is run from the specified server.

If ConnArg is empty, a dialog box will be shown to collect the configuration for the connection. Otherwise, ConnArg contains the connection configuration specific to ConnType.

ConnType must be one of the following:

Refer to Connection for more information on connections.

NewLocalTerminal ProfileName

Creates a new terminal on the local server, with ProfileName specified as in NewTerminal.

NewTerminal ProfileName ServerId

Creates a new terminal on the specified server using the profile named by ProfileName, which is interpreted as follows:

  • If empty or set to the string <ServerDefault>, the server's default profile.
  • If set to the string <Default>, the global default profile.
  • If set to the string <Prompt>, a dialog box will be opened where the user can choose a profile.
  • Otherwise, the profile with the given name.

Ownership of the terminal is assigned to this client.

NewWindow ProfileName ServerId

Opens a new application window and then calls NewTerminal with the given ProfileName and ServerId. If ProfileName is empty, no terminal is created.

NextPane

Moves input focus to the next split pane within the same window.

NextServer

Changes the active server to the next server in the Terminals tool. The first terminal on that server is made the active terminal.

NextTerminal

Changes the active terminal to the next terminal in the Terminals tool.

NoteFirst

Selects the first annotation in the Annotations tool.

NoteLast

Selects the last annotation in the Annotations tool.

NoteNext

Selects the note annotation in the Annotations tool, or the first note if there is no current selection.

NotePrevious

Selects the previous annotation in the Annotations tool, or the last note if there is no current selection.

NoteSearch

Opens and focuses the search bar within the Annotations tool.

NoteSearchReset

Clears the current search within the Annotations tool.

NotifySend Summary Body

Sends a desktop notification with the given Summary and Body using the notify-send command provided by libnotify (which must be present on the local machine). Ensure that Summary and Body do not contain vertical bar (|) characters.

This action exists to allow custom actions and alerts to send desktop notifications.

OpenConnection ConnName

Initiates a task to open the saved connection with name ConnName.

Refer to Connection for more information on connections.

OpenDesktopUrl Url

Launch the given Url via the local desktop environment, specifically by calling QDesktopServices::openUrl. The application launched will depend on the desktop environment and its configuration.

See OpenUrl for a way to open URL's using arbitrary launchers.

OpenFile LauncherName ServerId RemotePath Substitutions

Opens the file named by the absolute path RemotePath on the specified server using the specified launcher. If RemotePath is empty, the selected file in the Files tool is used.

LauncherName is interpreted as follows:

  • If empty, the default launcher is used.
  • If set to the string <Prompt>, a dialog box will be opened where the user can choose a launcher.
  • Otherwise, the launcher with the given name.

RemotePath will be substituted into the launcher's command at the location of the %f marker (other markers are also supported, refer to Launcher for more information). Custom markers may also be substituted within the command using the Substitutions parameter, which consists of zero or more strings of the form X=value separated by unit separator (0x1f) characters. X is the marker's letter and value is the string (treated as a single word) to substitute at the location of %X within the command.

Depending on the configuration of the launcher and whether the server is local or remote, any of the following may occur in order to handle the request:

  • A remote file may be mounted locally as in MountFile.
  • A desktop application may be launched as in OpenDesktopUrl.
  • A command may be run as in RunCommand.
  • A terminal may be opened to run a command as in CommandTerminal.
  • A command string may be written to the active terminal using WriteText.

Refer to Launcher for more information on launchers.

OpenTaskDirectory LauncherName TaskId

If the specified task has a local output file associated with it, opens the enclosing directory of that file on the local server using the specified launcher as in OpenFile.

LauncherName is interpreted as follows:

  • If empty, the launcher set in the Tasks/PreferredDirectoryLauncher global setting.
  • If set to the string <Desktop>, the enclosing directory will be opened as a file:// URL via the local desktop environment as in OpenDesktopUrl.
  • Otherwise, the launcher with the given name.
OpenTaskFile LauncherName TaskId

If the specified task has a local output file associated with it, opens that file on the local server using the specified launcher as in OpenFile.

LauncherName is interpreted as follows:

  • If empty, the launcher set in the Tasks/PreferredFileLauncher global setting.
  • If set to the string <Desktop>, the file will be opened as a file:// URL via the local desktop environment as in OpenDesktopUrl.
  • Otherwise, the launcher with the given name.
OpenTaskTerminal ProfileName TaskId

If the specified task has a local output file associated with it, creates a new terminal on the local server, with the starting directory set to the enclosing directory of that file. The file's path will also be printed to the terminal as the starting message.

ProfileName is interpreted as follows:

OpenUrl LauncherName ServerId Url

Opens Url using LauncherName and ServerId as specified in OpenFile.

If Url is not a file:// URL, only %u and %U markers will be substituted in the launcher's command. Refer to Launcher for more information.

Paste TerminalId

Paste the clipboard contents into the specified terminal.

PasteFile TerminalId FilePath

Paste the contents of the local file named by FilePath into the specified terminal. If FilePath is empty, an open file dialog will be shown.

Depending on the size of the input file, a task may be initiated to write the data.

PasteSelectBuffer TerminalId

Paste the select buffer contents into the specified terminal.

Middle-click in a terminal viewport or on a terminal thumbnail performs this action.

PopProfile TerminalId

Pops the next saved profile off the specified terminal's saved profile stack and switches the terminal to it. If the stack is empty, the global default profile is used.

PopupCommand ServerId Cmdspec Startdir

Initiates a task to run the command specified by Cmdspec on the specified server, using Startdir as the starting directory for the command. Cmdspec is an executable name and argument vector (including argument zero) separated by unit separator (0x1f) characters. The standard output and standard error of the command are displayed in a dialog box.

This action is a specialization of LaunchCommand.

PreviousPane

Moves input focus to the previous split pane within the same window.

PreviousServer

Changes the active server to the previous server in the Terminals tool. The first terminal on that server is made the active terminal.

PreviousTerminal

Changes the active terminal to the previous terminal in the Terminals tool.

Prompt

Opens a dialog box where the user can specify an action string to invoke.

PushProfile ProfileName TerminalId

Pushes the specified terminal's current profile onto its profile stack and switches the terminal to the specified profile. If the stack is full, the profile on the bottom of the stack will be discarded to make room. The default profile stack size is 8.

ProfileName is interpreted as in SwitchProfile

QuitApplication

Closes all windows and exits the application. A running transient local server will also exit and any terminals on it will be destroyed.

RaiseActiveTool

Raises the active tool.

RaiseAnnotationsTool

Raises the Annotations tool in the active window.

RaiseFilesTool

Raises the Files tool in the active window.

RaiseHistoryTool

Raises the History tool in the active window.

RaiseKeymapTool

Raises the Keymap tool in the active window.

RaiseSearchTool

Raises the Search tool in the active window.

RaiseSuggestionsTool

Raises the Suggestions tool in the active window.

RaiseTasksTool

Raises the Tasks tool in the active window.

RaiseTerminalsTool

Raises the Terminals tool in the active window.

RandomTerminalTheme SameGroup TerminalId

Changes the specified terminal's palette to that of a randomly chosen theme. If SameGroup is 1 and the terminal's current palette matches a defined theme, the chosen theme will have the same group as that theme. Otherwise, the chosen theme may be any defined theme.

RemotePortForward ServerId Spec

Initiates a task to perform port forwarding between the application and the specified server. The listening socket is on the remote machine and outbound connections are made on the local machine.

Spec is as described in LocalPortForward.

RemoveNote RegionId TerminalId
A note region is looked up using the RegionId and TerminalId parameters as follows:
  • If both are empty, the selected note in the Annotations tool will be used if that tool is active.
  • Otherwise, the terminal is looked up per Terminal Lookup and RegionId is parsed as an unsigned decimal number and looked up within that terminal. RegionId must refer to an annotation.

If the note lookup is successful, the specified note is removed.

RemoveSuggestion Index

If Index is empty, the selected suggestion in the Suggestions tool is removed from the command history database. Otherwise, the nth suggestion is removed, indexed from 0, specified by Index.

RemoveTasks

Removes all completed tasks from the Tasks tool.

RenameFile ServerId RemotePath NewPath

Initiates a task to rename the file or directory named by the absolute path RemotePath on the specified server to NewPath. If RemotePath is empty, the selected file in the Files tool is used. A confirmation prompt may be shown, depending on the value of the RenameFileConfirmation global setting.

ReorderServerBackward ServerId

Reorders the specified server backward in the Terminals tool.

ReorderServerFirst ServerId

Reorders the specified server first in the Terminals tool.

ReorderServerForward ServerId

Reorders the specified server forward in the Terminals tool.

ReorderServerLast ServerId

Reorders the specified server last in the Terminals tool.

ReorderTerminalBackward TerminalId

Reorders the specified terminal backward in the Terminals tool.

ReorderTerminalFirst TerminalId

Reorders the specified terminal first in the Terminals tool.

ReorderTerminalForward TerminalId

Reorders the specified terminal forward in the Terminals tool.

ReorderTerminalLast TerminalId

Reorders the specified terminal last in the Terminals tool.

ResetAndClearTerminal TerminalId

Resets the emulator, clears the screen, and clears the scrollback buffer of the specified terminal.

ResetTerminal TerminalId

Resets the emulator of the specified terminal.

RestartTask TaskId

If the specified task is clonable, starts a new identical task with the same parameters as before.

RunCommand ServerId Cmdspec Startdir

Initiates a task to run the command specified by Cmdspec on the specified server, using Startdir as the starting directory for the command. Cmdspec is an executable name and argument vector (including argument zero) separated by unit separator (0x1f) characters. The standard output and standard error of the command are discarded.

This action is a specialization of LaunchCommand.

SaveAll LocalPath TerminalId

Saves the entire scrollback contents in the specified terminal to a file. The local destination LocalPath is interpreted as follows:

  • If empty or set to the string <Prompt>, a save file dialog will be shown.
  • Otherwise, the file will be saved to the specified path.

If the destination file already exists, the file may be saved under a different name, a confirmation prompt may be shown, or nothing may be saved, depending on the value of the DownloadFileConfirmation global setting.

SaveScreen LocalPath TerminalId

Saves the contents of a viewport or terminal screen to the clipboard. If TerminalId is set, the contents of the specified terminal's screen are saved. Otherwise, the contents of the active viewport are saved. The local destination LocalPath is interpreted as follows:

  • If empty or set to the string <Prompt>, a save file dialog will be shown.
  • Otherwise, the file will be saved to the specified path.

Terminal screens are always saved as text. Viewport contents are saved in either text or PNG format, depending on whether the specified path ends in .png.

If the destination file already exists, the file may be saved under a different name, a confirmation prompt may be shown, or nothing may be saved, depending on the value of the DownloadFileConfirmation global setting.

ScrollLineDown

Scrolls down one line in the active viewport.

ScrollLineUp

Scrolls up one line in the active viewport.

ScrollNoteDown

Scrolls to the next note in the active viewport.

ScrollNoteUp

Scrolls to the previous note in the active viewport.

ScrollPageDown

Scrolls down one page in the active viewport. The page size is half the height of the viewport.

ScrollPageUp

Scrolls up one page in the active viewport. The page size is half the height of the viewport.

ScrollPromptDown

Scrolls to and selects the next prompt in the active viewport. This requires shell integration.

ScrollPromptFirst

Scrolls to and selects the first prompt in the active viewport. This requires shell integration.

ScrollPromptLast

Scrolls to and selects the last prompt in the active viewport. This requires shell integration.

ScrollPromptUp

Scrolls to and selects the previous prompt in the active viewport. This requires shell integration.

ScrollRegionEnd RegionId TerminalId

Scrolls to the last line of the specified job in the active viewport. RegionId can refer to any region. If the region is a job region, its prompt will be selected.

ScrollRegionRelative RegionId Offset

Scrolls Offset lines relative to the first line of the region named by RegionId in the active viewport.

ScrollRegionStart RegionId TerminalId

Scrolls to the first line of the specified job in the active viewport. RegionId can refer to any region. If the region is a job region, its prompt will be selected.

ScrollSemantic RegionId

Scrolls to the first line of the semantic region named by RegionId in the active viewport. RegionId must refer to a region created by a semantic parser.

ScrollSemanticRelative RegionId Offset

Scrolls Offset lines relative to the first line of the semantic region named by RegionId in the active viewport. RegionId must refer to a region created by a semantic parser.

ScrollToBottom

Scrolls to the bottom of the scrollback in the active viewport.

ScrollToTop

Scrolls to the top of the scrollback in the active viewport.

SearchDown

Searches down in the active viewport using the current search string in the Search tool. The search is started from the location of the current search match if present, otherwise from the top of the viewport.

SearchReset

Clears the current search in the Search tool. Input focus remains in the search bar if it has focus.

SearchUp

Searches up in the active viewport using the current search string in the Search tool. The search is started from the location of the current search match if present, otherwise from the bottom of the viewport.

SelectAll

Selects the contents of the active viewport.

SelectCommand RegionId TerminalId

Scrolls to and selects the command text of the specified job in the active viewport. The job's prompt will be selected.

SelectHandle Arg

If Arg is nonzero, makes the specified selection handle active. If Arg is zero, swaps the active selection handle if one is active, otherwise makes the lower selection handle active.

SelectHandleBackChar Arg

Moves the specified selection handle back one character. The upper selection handle is moved by default.

SelectHandleBackWord Arg

Moves the specified selection handle back one word. The upper selection handle is moved by default.

SelectHandleDownLine Arg

Moves the specified selection handle down one line. The lower selection handle is moved by default.

SelectHandleForwardChar Arg

Moves the specified selection handle forward one character. The upper selection handle is moved by default.

SelectHandleForwardWord Arg

Moves the specified selection handle forward one word. The lower selection handle is moved by default.

SelectHandleUpLine Arg

Moves the specified selection handle up one line. The upper selection handle is moved by default.

SelectJob RegionId TerminalId

Scrolls to and selects the entire text of the specified job in the active viewport. The job's prompt will be selected.

SelectLine Arg

If no selection is active, equivalent to SelectMoveUpLine. Otherwise:

  • If Arg is 1, the upper selection handle is moved to the beginning of the line.
  • If Arg is 2, the lower selection handle is moved to the end of the line.
  • If Arg is 0 or unset, both handles are moved as described.
SelectMoveBackWord

If no selection is active, first calls SelectMoveUpLine.

The active selection is moved to the previous word within the line.

SelectMoveDownLine

If no selection is active, selects the first non-empty line below the top of the active viewport. Otherwise, moves the selection to the next non-empty line below the current selection.

SelectMoveForwardWord

If no selection is active, first calls SelectMoveDownLine.

The active selection is moved to the next word within the line.

SelectMoveUpLine

If no selection is active, selects the first non-empty line above the last line of the active viewport. Otherwise, moves the selection to the next non-empty line above the current selection.

SelectOutput RegionId TerminalId

Scrolls to and selects the output text of the specified job in the active viewport. The job's prompt will be selected.

SelectScreen

Selects the entire contents of the active viewport.

SelectWord Index

If no selection is active, first calls SelectMoveUpLine.

The selection is moved to the nth word on the line, indexed from 0, specified by Index.

SendMonitorInput ServerId Message

Sends Message to the attribute monitor associated with the specified server. The attribute monitor may respond by setting server attributes which can be displayed in badge strings and other format strings.

As an example, the attribute monitor distributed with termy-server will respond to the input string "loadavg" by reporting the system load average in the loadavg attribute. Refer to termy-monitor for more information.

SendSignal Signal TerminalId

Sends signal number Signal to the foreground process group in the specified terminal.

SetAlert AlertName TerminalId

Makes the specified alert active in the specified terminal. If an alert is already active in the terminal, it is replaced by the new alert.

AlertName is interpreted as follows:

  • If set to the string <Prompt>, a dialog box will be opened where the user can choose an alert.
  • Otherwise, the alert with the given name.
SetFileListingFormat Format

Changes the display format in the Files tool. Format is interpreted as follows:

  • 1: long format (similar to ls -l) is used.
  • 2: short format (similar to ls) is used.
  • 0 or unset: the FileDisplayFormat profile setting is used.
SetFileListingSort Spec

Sorts the files in the Files tool on column number Spec. If Spec is negative, the sort is descending, otherwise it is ascending. The column numbers are:

  • 1: mode
  • 2: user
  • 3: group
  • 4: size
  • 5: modification time
  • 6: git status
  • 7: name
SetSelectedUrl Url

Sets the selected URL in the active viewport to Url. Any semantic regions in the viewport which have the same URL will be highlighted. If Url is a file:// URL, that file will be selected in the Files tool, which makes it the default target for file-related actions such as DownloadFile. If Url is empty, the selected URL will be cleared.

Clicking on a semantic region performs this action with the semantic region's URL.

SetServerIcon Icon ServerId

Sets the thumbnail icon for the specified server in the Terminals tool to Icon. If Icon is empty, the icon will revert to the string specified by the icon server attribute. Otherwise, an SVG file with the given name is loaded from $HOME/.local/share/qtermy/images/server or prefix/share/qtermy/images/server in that order. If no such file is found, the name "default" is used instead. The name "none" specifies an empty icon.

A custom icon can be set on a server automatically using the FixedThumbnailIcon server setting.

SetTerminalIcon Icon TerminalId

Sets the thumbnail icon for the specified terminal in the Terminals tool to Icon. If Icon is empty, the icon will revert to using the icon autoswitch rules. Otherwise, an SVG file with the given name is loaded from $HOME/.local/share/qtermy/images/terminal and prefix/share/qtermy/images/terminal in that order. If no such file is found, the name "default" is used instead. The name "none" specifies an empty icon.

A custom icon can be set on a terminal automatically using the FixedThumbnailIcon profile setting. Note that an icon is never shown if ShowThumbnailIcon is disabled in the profile.

ShowMenuBar

Shows the menu bar in the active window, if hidden.

ShowServer ServerId

In the active window, shows all hidden terminals belonging to the specified server in the Terminals tool.

ShowTerminal TerminalId

In the active window, shows the specified terminal in the Terminals tool, if it is hidden.

SplitViewClose

In the active window, closes the focused split window pane unless it is the only remaining pane.

SplitViewCloseOthers

In the active window, closes all split window panes other than the focused pane.

SplitViewEqualize

In the active window, equalizes the focused split window pane with its companion.

SplitViewEqualizeAll

In the active window, calls SplitViewEqualize on all split window panes.

SplitViewExpand

In the active window, expands the size of the focused split window pane relative to its companion.

SplitViewHorizontal

In the active window, splits the focused split window pane horizontally into two companion panes, one above the other. The resize handle between the panes can be used to adjust the relative sizes of the two panes.

SplitViewHorizontalFixed

In the active window, splits the focused split window pane horizontally into two companion panes, one above the other. No resize handle is placed between the panes. However, SplitViewExpand and SplitViewShrink can be still be used to adjust the relative sizes of the two panes.

SplitViewQuadFixed

In the active window, splits the focused split window pane into four panes using one call to SplitViewHorizontalFixed followed by two calls to SplitViewVerticalFixed.

SplitViewShrink

In the active window, reduces the size of the focused split window pane relative to its companion.

SplitViewVertical

Like SplitViewHorizontal except the panes are split vertically, one next to the other.

SplitViewVerticalFixed

Like SplitViewHorizontalFixed except the panes are split vertically, one next to the other.

SuggestFirst

Selects the first suggestion in the Suggestions tool.

SuggestLast

Selects the last suggestion in the Suggestions tool.

SuggestNext

Selects the next suggestion in the Suggestions tool, or the first suggestion if there is no current selection.

SuggestPrevious

Selects the previous suggestion in the Suggestions tool, or the last suggestion if there is no current selection.

SwitchPane PaneIndex

Moves input focus to the nth pane within the same window, indexed from 0. Note that pane index numbers displayed in viewports and thumbnails are indexed from 1.

SwitchProfile ProfileName TerminalId

Switches the specified terminal's to the specified profile. ProfileName is interpreted as follows:

  • If empty, the global default profile.
  • If set to the string <Prompt>, a dialog box will be opened where the user can choose a profile.
  • Otherwise, the profile with the given name.
SwitchServer ServerId PaneIndex

Makes the specified server the active server. If PaneIndex is empty, the first terminal on that server is made the active terminal. Otherwise, changes the terminal in the nth pane, indexed from 0, to the first terminal on that server, making it the active terminal if that pane has input focus.

SwitchTerminal TerminalId PaneIndex

If PaneIndex is empty, the specified terminal is made the active terminal. Otherwise, changes the terminal in the nth pane, indexed from 0, to the specified terminal, making it the active terminal if that pane has input focus.

TakeTerminalOwnership TerminalId

Takes ownership of the specified terminal. This has the following effects:

  • The terminal's native size will be changed to fit the active viewport. Other clients will see the terminal at this size and will not be able to resize the terminal nor adjust the scrollback buffer size.
  • The local Avatar image will be displayed in other qtermy clients that have RenderAvatars enabled.
  • Input to the terminal from other clients can be disallowed using the AllowRemoteInput profile setting and the ToggleTerminalRemoteInput action. But see warning below about security.
  • If enabled, all profile settings associated with the current profile will be pushed to the server as terminal attributes. Other clients may extract their own profile from these settings. Only the owning client is allowed to set these attributes.
  • The terminal's palette, font, layout, fills, and badge (including any per-terminal adjustments) will be pushed to the server as terminal attributes. Other clients may honor these settings (in qtermy this is controlled via profile settings). Only the owning client is allowed to set these attributes.
  • The active viewport's scrollback position and timing origin will be pushed to the server as terminal attributes. Other clients may honor this information (in qtermy, this is controlled via the FollowRemoteScrolling profile setting and the ToggleTerminalFollowing action). Only the owning client is allowed to set these attributes.

Warning

Terminal ownership is not a security mechanism. Any client connected to a server can take ownership of a terminal at any time.

TaskFirst

Selects the first task in the Tasks tool.

TaskLast

Selects the last task in the Tasks tool.

TaskNext

Selects the next task in the Tasks tool, or the first task if there is no current selection.

TaskPrevious

Selects the previous task in the Tasks tool, or the last task if there is no current selection.

TerminalContextMenu

Brings up the context menu for the active viewport.

TimingFloatOrigin

Floats the timing origin in the Timing widget. When the origin is floating, timing measurements are shown relative to the start of the current job.

TipOfTheDay

Opens the application Tip of the Day window. The tips shown in it are generated by a dedicated plugin feature.

ToggleAnnotationsTool

Toggles the Annotations tool in the active window.

ToggleCommandMode Arg

Arg is interpreted as follows:

  • 0 or empty: toggles command mode.
  • 1: enables command mode.
  • 2: disables command mode.
ToggleFileListingFormat

Toggles the display format in the Files tool between short and long format.

ToggleFilesTool

Toggles the Files tool in the active window.

ToggleFullScreen

Toggles full screen mode.

ToggleHistoryTool

Toggles the History tool in the active window.

ToggleKeymapTool

Toggles the Keymap tool in the active window.

ToggleMenuBar

Toggles display of the menu bar in the active window.

TogglePresentationMode

Toggles presentation mode. Upon entering presentation mode, the applicable global settings will be applied.

ToggleSearchTool

Toggles the Search tool in the active window.

ToggleSelectionMode Arg

Arg is interpreted as follows:

  • 0 or empty: toggles selection mode. Treated as 1 if selection mode is disabled, 2 if selection mode is enabled.
  • 1: enables selection mode. If there is no active text selection, calls SelectMoveUpLine to create one.
  • 2: disables selection mode. Clears any active text selection.
ToggleServer ServerId

If any terminals belonging to the specified server are hidden, calls ShowServer on that server. Otherwise, calls HideServer on that server.

ToggleSoftScrollLock TerminalId

Toggles soft scroll lock in the specified terminal. When soft scroll lock is enabled, the server stops reading output from the terminal.

This differs from hard scroll lock, which is the result of sending a STOP character (normally DC3, Ctrl+S) to the terminal driver. Hard scroll lock can be undone using the START character (normally DC1, Ctrl+Q). Refer to termios(3) for more information.

ToggleStatusBar

Toggles display of the status bar in the active window.

ToggleSuggestionsTool

Toggles the Suggestions tool in the active window.

ToggleTasksTool

Toggles the Tasks tool in the active window.

ToggleTerminalFollowing

Toggles remote viewport following in the active viewport. If enabled, and the terminal is owned by another client, the active viewport's scrollback position and timing origin will track the information reported by the owning client. The default value for this option is set via the FollowRemoteScrolling profile setting.

ToggleTerminalLayout Item TerminalId

Toggles display of the specified widget in the specified terminal. Item is interpreted as follows:

ToggleTerminalRemoteInput TerminalId

Toggles remote input in the active terminal. If disabled, and the terminal is owned by this client, input from other clients is not permitted. The default value for this option is set via the AllowRemoteInput profile setting.

Warning

This is not a security mechanism. Any client connected to a server can take ownership of a terminal at any time. This option is intended to prevent inadvertent input from other users.

ToggleTerminalsTool

Toggles the Terminals tool in the active window.

ToggleToolSearchBar

Toggles display of the search bar in the active tool if it supports search. To both show and focus the search bar, use ToolSearch.

ToggleToolTableHeader

Toggles display of table column headers in the active tool, if applicable.

ToolAction Index

Calls the action configured in the per-tool global settings and specified by Index on the selected item in the active tool.

Index is interpreted as follows:

  • 0 or empty: calls the configured double-click action.
  • 1: calls the configured Control-click action.
  • 2: calls the configured Shift-click action.
  • 3: calls the configured middle-click action.
ToolContextMenu

Brings up the context menu for the selected item in the active tool.

ToolFilterAddServer ServerId

Makes the specified server visible in the History, Annotations, and Tasks tools.

ToolFilterAddTerminal TerminalId

Makes the specified terminal visible in the History, Annotations, and Tasks tools.

ToolFilterExcludeServer ServerId

Filters out the specified server in the History, Annotations, and Tasks tools. If ServerId is empty, the selected server in the active tool is used.

ToolFilterExcludeTerminal TerminalId

Filters out the specified terminal in the History, Annotations, and Tasks tools. If TerminalId is empty, the selected terminal in the active tool is used.

ToolFilterIncludeNothing

Filters out everything in the History, Annotations, and Tasks tools.

ToolFilterRemoveClosed

Removes closed terminals from the History, Annotations, and Tasks tools.

ToolFilterReset

Resets the filter, making everything visible in the History, Annotations, and Tasks tools.

ToolFilterSetServer ServerId

Filters out all but the specified server in the History, Annotations, and Tasks tools. If ServerId is empty, the selected server in the active tool is used.

ToolFilterSetTerminal TerminalId

Filters out all but the specified terminal in the History, Annotations, and Tasks tools. If TerminalId is empty, the selected terminal in the active tool is used.

ToolFirst

Selects the first item in the active tool.

ToolLast

Selects the last item in the active tool.

ToolNext

Selects the next item in the active tool, or the first item if there is no current selection.

ToolPrevious

Selects the previous item in the active tool, or the last item if there is no current selection.

ToolSearch

Shows and focuses the search bar in the active tool if it is a searchable tool. Pressing Return or Escape in the search bar will return focus to the terminal viewport. To hide the search bar, press Escape while the search bar has input focus, click the close button next to the search bar or use ToggleToolSearchBar.

ToolSearchReset

Clears the current search within the active tool.

UndoAllAdjustments

Calls UndoTerminalAdjustments for all terminals.

UndoTerminalAdjustments TerminalId

In the specified terminal, undoes any adjustments made using the Adjustment dialogs (except scrollback size changes) as well as the IncreaseFont, DecreaseFont, and RandomTerminalTheme actions. The settings revert to those specified in the terminal's profile.

UploadFile ServerId RemotePath LocalPath

Initiates a task to upload a file from LocalPath on the local machine to the absolute path RemotePath on the specified server. If RemotePath is empty, the selected file in the Files tool is used. If LocalPath is empty, an open file dialog will be shown.

If RemotePath ends in a slash or is known to be a directory, the local filename is appended to it to form the destination path.

If the destination file already exists, the file may be saved under a different name, a confirmation prompt may be shown, or the task may fail, depending on the value of the UploadFileConfirmation global setting.

Uploads to local servers are not allowed unless the LocalDownloads global setting is enabled.

UploadToDirectory ServerId RemoteDir LocalPath

Like UploadFile, but always assumes that the destination path RemoteDir is a directory. The local filename is appended to it to form the destination path.

ViewServerInfo ServerId

Opens the View Server Information window for the specified server.

ViewTerminalContent ContentId TerminalId

Opens the View Terminal Information window for the specified terminal, and changes to the Inline Content tab.

ViewTerminalInfo TerminalId

Opens the View Terminal Information window for the specified terminal.

WriteCommand RegionId TerminalId

Calls WriteText on the specified terminal with the specified job's command text.

WriteCommandNewline RegionId TerminalId

Calls WriteCommand, then writes a newline character.

Warning

This may result in a command being run without opportunity for review. Use this action with caution.

WriteDirectoryPath DirPath

If DirPath is empty, the enclosing directory path of the selected file in the Files tool is written to the active terminal. Otherwise, DirPath is written. The path is enclosed in single quotes when written.

WriteFilePath FilePath

If FilePath is empty, the path of the selected file in the Files tool is written to the active terminal. Otherwise, FilePath is written. The path is enclosed in single quotes when written.

WriteSelection

Writes the selected text in the active terminal back to the active terminal. If selection mode is active and ExitSelectModeOnCopy is enabled, the selection will be cleared following the write.

WriteSelectionNewline

Calls WriteSelection, then writes a newline character.

Warning

This may result in a command being run without opportunity for review. Use this action with caution.

WriteSuggestion Index

If Index is empty, the selected suggestion in the Suggestions tool is written to the active terminal using WriteText. Otherwise, the nth suggestion is written, indexed from 0, specified by Index.

WriteSuggestionNewline Index

Calls WriteSuggestion, then writes a newline character.

Warning

This may result in a command being run without opportunity for review. Use this action with caution.

WriteTaskDirectoryPath TaskId

If the specified task has a local output file associated with it, writes the enclosing directory path of that file to the active terminal. The path is enclosed in single quotes when written.

WriteTaskFilePath TaskId

If the specified task has a local output file associated with it, writes the path of that file to the active terminal. The path is enclosed in single quotes when written.

WriteText Text TerminalId

Writes Text to the specified terminal. With shell integration enabled, if the terminal has an active prompt and characters have been typed at the prompt, KILL or backspace characters will be written ahead of Text in order to clear those characters.

WriteTextNewline Text TerminalId

Calls WriteText, then writes a newline character.

Warning

This may result in a command being run without opportunity for review. Use this action with caution.