Creating a new session ¶

Creating a new session is done with the new commands, possibly abbreviated:

[new] [executable arg...]

This creates a new process running the executable with the specified command-line arguments.

You can leave out the new if the executable contains a “/” (slash). For example:

$ domterm /bin/csh -v

If executable is not specified, the default shell (for example bin/bash) is used. (See shell.default in Settings.)

The executable runs a new terminal window, as specified a window specifier.

The following options control which front-end (usually a browser), if any, is started.

Browser specifier option ¶

A browser-specifier option specifies how to display a new domterm window. This can be a window or tab in general-purpose web-browser, a specialized browser without locationbar or similar distracting “chrome”, or a sub-window.

It is used for certain commands like new and attach. For example:

domterm --Belectron new
domterm --below attach 4
domterm --browser /bin/sh

If there is no browser-specifier option, the value of the browser.default setting is used.

Browser specifiers ¶

--browser

-B

Creates a new window or tab in your preferred desktop browser. Same as -Bbrowser.

-Bcommand

--browser=command

For example either -Bfirefox or --browser=firefox (which are equivalent).

The command is most commonly one of the browser aliases below. Can also be a command with an optional %U, which is replaced by a URL generated by domterm. (If there is no %U in the command, then ‘ '%U'’. is added.) You can also specify a list of commands or aliases, separated by semi-colons, which are tried in order.

If program is specified, instead creates a window in the specified browser, where program is the name of a browser program that takes a single URL argument. The program can be a multi-word template, where %U is replaced by a URL generated by domterm. If program contains a ‘$’ it is processed by the shell; the program should either deamonize itself or otherwise run in the background (perhaps by using ‘&’). If program does not contain a ‘$’, domterm splits it into words and runs it directly (daemonized).

The following aliases are available.

firefox

chrome

google-chrome

safari (macOS only)

edge (Windows only)

Open a new tab or window in the specified desktop browser, either Firefox, Google Chrome (chrome and google-chrome are synonymous), Safari (on macOS only), or Microsoft Edge (on Windows only). DomTerm looks in common platform-specific locations for these browers, and knows which options to pass.

chrome-app

edge-app (Windows only)

The aliases chrome-app and edge-app open chrome or edge in “application mode” (with the --app= option). This is recommended: you don’t get the clutter of the browser location bar, menubar, or toolbar, or the browser taking over certain keybindings (like ctrl+N).

electron

electron-frames

electron-widgets (Experimental)

Use a front-end based on Electron. This is currently the nicest (and default) front-end.

The default (electron-frames or electron) uses a shared browser instance for all sub-windows in the same top-level window. The experimental electron-widgets runs each sub-window is a separate browser instance, which allows a sub-window to be moved from one top-level window to another without reloading.

qt

qt-widgets

qt-frames

qtdomterm

qtwebengine

These all run the qtdomterm front-end, a stripped-down browser based on the Qt toolkit (specifically QtWebEngine, which is based on the Chrome browser).

Except for -Bqt-frames, these are all equivalent, and each sub-window has a separate browser instance. This has the benefit that a sub-window can be moved from one top-level window to another without reloading. In contrast, -Bqt-frames uses a shared browser instance for each top-level window and uses interior frames for sub-windows (like other front-ends).

webview

wry

Run the stripped-down dt-webview or dt-wry browser, respectively. (Available if configured --with-webview or with-wry, respectively.)

browser

Run the default desktop browser. The option --browser=browser (or -Bbrowser) is the same as plain --browser (or -B).

Special window specifiers ¶

The following create sub-window in existing browser windows, or have other special uses.

--left[=window]

--right[=window]

--above[=window]

--below[=window]

Split window (a window specifier) in two, and create a new pane (sub-window) to the left/right/above/below the old one. If window is not specified, use the current window.

If window starts with ^, split the specified top-level window. For example, if window 1 is above window 2, then --left=2 will will put the new window side-by-side with 2, and both below window 1 (which is full-width). In contrast, --left=^2 will create a new full-height window on the left, while on the right window 1 will be above window 2.

--pane[=window]

Equivalent to either --right or --below depending on the current window’s width/height ratio.

--tab[=window]

Create new tab.

--headless

Create an “invisible” (hidden) browser window. This runs all the regular display logic except actually displaying on a screen. This (experimental) feature is useful for testing (of DomTerm or of other applications). It is also useful as a backup of the display in case of network disconnect. (The headless server runs on the same remote computer as the session.)

You should use the command.headless setting to specify the command for running the headless browser. This can be any command that can take a URL argument (using with a %U pattern that is filled in by domterm). If command.headless is not set, but one of --chrome, --qt, or --electron is specified the corresponding frontend in used headless mode. (Using --chrome seems to work best.) If none of these are set, the default is as if --chrome was specified, assuming the Chrome browser is available.

--detached

When creating a new session, it is detached, without a window.

--print-browser-command

(Debugging use.) This option can be used with another window specifier. Print out the command that would start a new top-level browser window, but don’t actually execute that command. You can use that command to start the browser from a debugger or change the command line. The browser will first open a local file (with a file: URL) and a filename ending with start-windownumber.html. This file will redirect to an http: URL (served by the domterm backend) with various parameters that are interpreted by JavaScript in the browser.

--browser-pipe

(Internal use.) Proxy input and output, usually over an ssh connection.

Window specifier option ¶

Certain commands affect an existing window. These take a window-specifier option that can specify which window(s) should be acted on. For example, to minimize windows 2 and 3 do:

domterm -w 2,3 minimize

-w window-specifier

--window window-specifier

--window=window-specifier

Specify which windows are affected by the current command.

The general format for window specifiers is here.

Miscellaneous commands ¶

help [sub-help] ¶

Print some help. The sub-help may be a sub-command.

is-domterm ¶

Succeeds (exits with code 0) if the current terminal is DomTerm; fails (exits with code -1) otherwise.

This test does not depend on environment variables, but instead sends a special request code, and checks the response. This test works over an ssh connection. (The test does require that either DOMTERM be non-empty, or that TERM be either empty or contain the string xterm; otherwise it does not try to the request code.)

status [--verbose] [--by-session] ¶

Prints various bits of information about the backend, sessions, windows, and version numbers. The information displayed and the format are likely to change. The default groups sessions by top-level window; the --by-session groups windows by session. The --verbose option adds more detail.

settings name=value ... ¶

Change the given local settings for the specified window(s).

If the value is empty, the local setting with the given name is removed, so the global setting (if set) becomes active.

browse url ¶

Create a new browser window or sub-window that displays url. This is implemented using an iframe. Access depends on the permissions of the browser (front-end). (A future command may proxy via the back-end server.)

One use for this is to view documentation in a sub-window:

$ domterm --above browse http://example.com/

view-saved filename ¶

The filename is an HTML file of a previously saved session. Open the session is “view” mode: Lines will be re-wrapped on window re-size, links are clickable, and hide/show buttons work.

kill-server [--only] ¶

Kill the domterm server. This also kills all local sessions. Also close any windows, unless --only is specified. (This may kill remote sessions if their only window is closed.)

“Printing” images or html ¶

html [--base=base-url] ¶

html [--base=base-url] html-value ...

hcat [--base=base-url] filename.html ...

Use this to embed HTML content info the DomTerm page. If there are no arguments, read from standard input. Either of the following work:

echo 'E = mc<sup>2</sup>' | domterm html
domterm html 'E = mc<sup>2</sup>'

displays: E = mc2.

The html-value can be a complete html file, but elements such as <html>, <body> or <style> are ignored.

Relative URLs are resolved relative to the base-url, which can be an absolute URL or a filename or directory; the default is the current working directory.

The hcat command takes the name of an html file, rather than literal html. (With no arguments hcat is the same as html.) The following are equivalent:

domterm hcat /path/to/doc.html
cat /path/to/doc.html | domterm html --base=/path/to/

image [-n] [--attrname=attrvalue]... filename ¶

imgcat [-n] [--attrname=attrvalue]... filename

image [-n] [--attrname=attrvalue]... url

This script “prints” the contents of the image file to domterm. The image must be of a type that can be displayed by an HTML <img> element, such as a png, jpg, or svg file.

If a filename is specified, the file is read by the domterm command, and sent to the front-end (using a “data:” URI), so it works for remote contections. As the image data is “inline” in the DOM it is included when saving as HTML.

If a url is specified, it is used instead. The front-end is responsible for fetching the data.

By default (no -n is specified), the image has a display: block style (so it is automatically on a “line” by itself),’ and gets a horizontal scroll bar if and only if it is too wide to fit. If -n is specified, then only a plain <img> element is written, which means you can write multiple images and other HTML on the same “line”.

--attrname=attrvalue

Specify the given attribute; for example: --height=200. Valid attrnames are the following, which are specified in the HTML specification: alt, longdesc, height, width, border, hspace, vspace, class.

For example: --width=600 scales the image width to be the given number of pixels (in the CSS meaning). (The height is scaled proportionally, unless you also specify the --height option.)

fresh-line ¶

If not already at beginning of line, starts a fresh line

Sessions ¶

attach session-specifier ¶

Create a new window displaying an existing session. The same session (process) may be displayed in multiple windows. See session-specifier.

list ¶

List information about running sessions.

The status command shows more information, including some information about each window.

Windows operations ¶

close ¶

Close specified window(s), as if you clicked on the “close” button. The default windows-specifier is . (the current window).

detach ¶

Close specified window(s) (the default is .), and (assuming there are no more windows attached to the session) make the session detached.

minimize ¶

(Electron, Qt, and Wry only.) Minimize (iconify) the specified top-level windows, where the default window is top. The minimized windows may be still visible in the task bar, as an icon on the desktop, or during an “windows expose” operation

hide ¶

(Electron, Qt, and Wry only.) Hide the specified top-level windows. The hidden windows are not visible in the task bar, as icons on the desktop, or during an “windows expose” operation

show ¶

(Electron, Qt, and Wry only.) Show the specified minimized or hidden windows. If there are no windows, create one.

toggle-minimize ¶

(Electron, Qt, and Wry only.) Toggle between normal and minimized state: If a window is hidden or minimized, show it. If visible, minimize it. If there are no windows, create one.

toggle-hide ¶

(Electron, Qt, and Wry only.) Toggle between normal and hidden state: If a window is hidden or minimized, show it. If visible, hide it. If there are no windows, create one.

set-window-name name ¶

Set name as the window-name of the specified window(s).

window window-specifier ... subcommand options ... ¶

Do the subcommand on the windows specified by the window-specifier list. Older (deprecated) form equivalent to: --window=window-specifier ... subcommand options ...

Automation ¶

The following are useful for automatically or remotely controlling DomTerm. For examples for doing automatic testing for DomTerm check the file tests/Makefile.am in the sources.

do-keys [option|string]... ¶

Simulate user keystrokes by sending them to the front-end for interpretation.

-w window-specifier

If specified, must be the first argument. Same as if specified before the do-keys argument.

-N count

Repeat following actions count times, until the next -N.

-l text

-e text

Send the text as plain characters, with no interpretation for special key-bindings. Acts like a key-press event for each character. If -e (“escape”) is used, string escapes are processed; if -l (“literal”) is used, the text is used as-is.

-C[response]

Wait until connection is closed. Only a single window is allowed in this case. Similar to a separate domterm await --close [response] command, but avoids a race condition.

key-stroke

The front-end simulates the specified key-stroke, as a key-down event. Examples are Enter or Ctrl+A. (Ctrl-A is accepted in addition to the modern Ctrl+A style.) However, if the key-stroke starts and ends with single-quote, the characters between the quotes are processed as if with the -l options. Also, if the key-stroke has no action in the current context, the front-end treats the key-stroke as if preceeded by -l

send-input send-option... string... ¶

Send the specified string directly to the standard input of a session. If there is more than one string, send them in order, with a single space in between.

A string may have string escapes.

Usually send-input "text" has the same effect as do-keys -e "text". However, send-input feeds the text directly to the application input, while do-keys sends it to the front-end for processing first. If the browser is in line-edit mode, it inserts the text input the editing area instead of sending it to the application.

A send-option can be:

-s session-specifier

Send to the session as specified by the session-specifier.

-w window-specifier

Send to the session attached to the specified window.

-C[response]

Wait until connection is closed. Only a single window is allowed in this case. Similar to a separate domterm await --close [response] command, but avoids a race condition.

capture capture-option... ¶

Get the text contents of the specified window (defaulting ., the current window). The text is printed on standard output. This command is useful for testing.

A capture-options can be:

-B

Only capture the contents of the current buffer, as opposed to that of all buffers of the specified window.

-S

Only capture the contents of the selection.

-l

Include active soft newlines (i.e. from line-wrap or pretty-printing) as newlines in the output. Also skips extra whitespace (" \t\r") at end of lines, and extra newlines at the end.

-T

Preserve tabs, if possible. When DomTerm receives a Tab character, it will remember that (assuming the columns moved past by the Tab contain just spaces). The -T flag will report a Tab character in the captured output; the default is to report the equivalent number of spaces.

-e

Include ANSI escape sequences that encode color and style in the output. These escapes should work on almost all modern terminals. DomTerm-specific “logical” styles (such as prompt or input areas) are currently ignored.

-w window-specifier

Same as if specified before the capture command name.

In the future some options make be extended to take optional arguments, so scripts should not combine options: instead of -Ble write -B -l -e.

await options... event... ¶

Wait until one of the specifed events happen.

The following options and events are supported:

--match-output pattern response [nlines]

After each “block” of output, try match pattern (a regular expression) against the last nlines (default 1) lines of the buffers. (Trailing empty lines are not included in the nlines count.) If the match succeds, write response to standard output. (A newline is added if response is non-empty and does not end in a newline.)

When this test is run depends on buffering (how the application and network/system break output into blocks), so this test is mainly intended to detect when output is “done” and the application is waiting for input. Typically, the pattern would look for a prompt string.

--close [response]

Wait until connection is closed. (This action is handled in the server, rather than the front-end.)

--timeout time response

If after time seconds none of the other events have occurred, return (with a non-zero exit code indicating failure). If response is non-empty, write it (plus a newline) to standard error.

-w window-specifier

A window specifier for the affected window.

Miscellaneous options ¶

An argument that contains equal-sign (=), does not start with a hyphen (-), and precedes a command (if any) is a settings option.

--geometry size-and-position

Specify the initial size and/or position of a new top-level window. See geometry specifier.

--name window-name

If this command creates a new window, set window-name as its name.

--version

Print version information and copyright, and then exit.

--verbose

Print information about interesting events. This works best with --no-daemonize. A second --verbose prints more information.

A single (respectively double) --verbose prints the same as -d 7 (respectively -d 15), but the latter prints a timestamp on each line.

-d debug-level

Finer-grained control over debugging level than using --verbose, plus prints time-stamps before each message. Sets the debug-level as defined by the LWS logging API.

-L socket-name

--socket-name=socket-name

DomTerm uses a Unix Domain socket to communicate between the command-line and the server. By default the socket is the file $XDG_RUNTIME_DIR/domterm/default.socket, but this option overrides that. Using different socket names mean you get different servers that do not know about each other. If socket-name starts with ‘/’ then the filename is absolute; otherwise $XDG_RUNTIME_DIR/domterm/ is prepended. If there is no file extension, .socket is appended.

DomTerm also creates a temporary html that has the same name as the socket, but with a .html extension. That is by default it is $XDG_RUNTIME_DIR/domterm/default.html.

--settings=filename

Specify the location of the Settings file containing user preferences. (The default is .config/domterm/settings.ini in the user’s home directory, except on WSL (Windows Subsystem for Linux).)

Note this flag won’t have much if any effect if you specify it when there is already a running domterm server.

--no-daemonize

When a domterm backend (server) is created, it normally turns itself into a daemon. This option prevents “daemonizing” - which is helpful for debugging.

--remote-debugging-port=debug-port

Only relevant for the qtdomterm front-end. (For the Electron front-end, use menu item Toggle Developer Tools. If using a general web browser, use its debugger.) Allow remote debugging (using a Chromium-based browser, such as Google Chrome). This is useful for debugging DomTerm itself, as well as any inspecting any unusual HTML, CSS, or JavaScript you might throw at it.

There are other ldomterm options which useful if you want to run DomTerm as a server.

Starting a web server ¶

The domterm command normally starts an internal web-server, bur for security reasons this is only usable by the current user on the current computer (enforced by the browser having to read a file in the user’s directory).

Sometimes you want a public web-server that other people can attach to. For that use the --port option and the --ssl options. See Remote serving for more information.

--port portnum

Start a server, listening on the specified portnum. A portnum of 0 lets the system choose an available port, which is printed out. The server is an http server, unless --ssl is specified, in which case it an https server. No front-end is started.

--ssl

Start an https server rather than an http server. Strongly recommended except for testing.

--ssl-cert cert-file

The name of a file containing the server certificate.

--ssl-key key-file

The name of a file containing the passphrase needed for the private key.

--ssl-ca ca-file

CA (certificate authority) filepath.

--once

(Probably obsolete.) Only allow a single connect before shutting down. This option is the default unless --port is specified.

Working with styles ¶

All of these work with a window-specifier option, defaulting to ., the current window.

reverse-video on|off ¶

add-style style-rule ... ¶

If called for the first time, create and install a temporary stylesheet. This temporary stylesheet has a name attribute with the value "(temporary-styles)". Add each style-rule to the temporary stylesheet.

For example, to change the background color to pink:

$ domterm add-style "div.domterm { --background-color: pink }"

You can also set the background-color style directly:

$ domterm add-style "div.domterm { background-color: pink }"

However, it is better to set the --background-color CSS variable, as that is required for reverse video and “Background Color Erase” to work.

Inverse video (using CSS variables):

$ domterm add-style "div.domterm { --background-color: black; --foreground-color: white }"

Changing font size:

$ domterm add-style "body { font-size: 14pt }"

list-stylesheets ¶

List on the standard output the set of stylesheets associated with the domterm document, one per line:

$ domterm list-stylesheets
0: enabled  - "style/domterm-core.css"
1: enabled  - "style/domterm-standard.css"
2: enabled  "Default DomTerm styling" "style/domterm-default.css"
3: enabled  - "(temporary-styles)"

After the sequence number, either enabled or disabled specified whether the stylesheet is disabled. If the stylesheet has a title, if is shown next (in json format); otherwise - is printed. If the stylesheet has the href attribute, it is shown next (in json format); otherwise, if it has the code attribute, that is shown; otherwise - is printed.

load-stylesheet name filename

Replace or create a new stylesheet with the given name. The content of the stylesheet are read from the given filename. If the filename is - then standard input is used.

The name is used to set the non-standard name attribute of the created <style> element. If there is an existing stylesheet with a matching name attribute, then that stylesheet is replaced; otherwise a new stylesheet is created. The name attribute is displayed by the list-stylesheets subcommand.

print-stylesheet index ¶

Print out the style rules of the specified stylesheet, which is an index in the list-stylesheets output.

disable-stylesheet index ¶

enable-stylesheet index

Disable or enable the specified stylesheet. A index is an integer index into the list as shown by list-stylesheets.

$ domterm disable-stylesheet 2