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.

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

--qtdomterm
--qtwebengine

Experimental (not all functionality is working). 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

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. (Work-in-progress.)

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.

Currently only works for the Electron front-end.

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

--no-daemonize

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

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