The domterm command

The domterm command is the preferred away of using DomTerm.

If you run domterm with no arguments, it creates a new terminal emulator window, just as if you’d start xterm, say. You can specify options to specify what kind of window is created (for example a new tab or a web browser window). You can also specify a command to perform other actions besides creating a new terminal emulator.

domterm [options] [command arg...]

The command specifies one of a set of commands used to control domterm, as described in the following sections. If command is not specified, the default command is new, which creates a new session using a default shell such as /bin/bash.

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.

Window specifier option

Use a window-specifier option with certain commands, such as new or attach. For example:

domterm --electron new
domterm --below attach '#4'
domterm --firefox /bin/sh
--browser
--browser=program
--browser=firefox
--browser=google
--browser=google-chrome

Use program as a browser to run DomTerm in. If program is not specified, creates a new window or tab in your preferred desktop browser.

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.

Using firefox, chrome, or google-chrome for program enables some special tricks to search for those browsers. (Using chrome or google-chrome has the same effect.)

--electron

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

--firefox

Same as --browser=firefox. (This used to start a XUL application, but that is no longer supported.)

--chrome

This uses the Google Chrome browser, started using the --app= option, so you get a fresh chrome-less window (with no menubar or toolbar).

This works well and the performance is good. This method provides no menubar or context-menu customization (so far).

--qt
--qtdomterm
--qtwebengine

Either option (they do the same thing) runs qtdomterm with the --connect option, after starting up a websockets server.

--left
--right
--above
--below

If there is a current DomTerm window, split it in two, and create a new window to the left/right/above/below the old one.

--pane

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

--tab

Create new tab.

--detached

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

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.)

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/

“Printing” images or html

html
html html-value ...

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.

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

This script “prints” the contents of the named image file to domterm. This uses a “data:” URI with the file contents sent directly to domterm, so it works when working remotely.

The filename must be a file that can be displayed by an HTML <img> element, most commonly a png or jpg file.

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.

Miscellaneous options

--geometry widthxheight

Specify initial size of new top-level windows. The default if not specified is currently 800x600. The width and height are in pixel units and must be positive integers.

Works for both the Electron and qtdomterm front-ends.

-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 $HOME/.domain/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 $HOME/.domain/ 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 $HOME/.domain/default.html.

--settings=filename

Specify the location of the Settings file containing user preferences. (The default is .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.

--port portnum

(Probably obsolete.) Start a server, listening on the specified portnum. A portnum of 0 lets the system choose an available port, which is printed out. No front-end is started.

--once

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

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

Working with styles

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 }"

Howeverm 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