Next: Settings, Previous: Downloading and building, Up: DomTerm [Contents]
The domterm
command is the preferred away of using DomTerm.
The command has various sub-commands and options.
Most sub-commands will start a server in the background
if one isn’t already running.
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
.
You can run a command on a different (remote) computer named host, using the following syntax:
domterm
[options] user@
host [command arg...]
This uses ssh
.
For details see here:
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.
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
.
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).
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
Creates a new window/tab in the Google Chrome browser.
Same as --browser=chrome
.
--chrome-app
This uses the Google Chrome browser, but
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.
--qt
--qtdomterm
--qtwebengine
Either option (they do the same thing)
runs qtdomterm
with the --connect
option,
after starting up a websockets server.
--left
[=
window]--right
[=
window]--above
[=
window]--below
[=
window]Split window (a window number) 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.
--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.
--browser-pipe
(Internal use.) Proxy input and output,
usually over an ssh
connection.
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 specified local settings for the current session.
If the value is empty, the local setting with the given name is removed, so the global setting (if set) becomes active.
browse
urlCreate 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
filenameThe 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.)
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
]... filenameimgcat
[-n
] [--attrname=attrvalue
]... filenameThis 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
attach
session-specifierCreate 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.
window
window-specifier ... subcommand options ...Do the subcommand on the windows specified by the window-specifier list.
A window-specifier can be a window (connection) number;
or the top
specifier (all top-level windows).
If there is no window-specifier the default depends on the subcommand; if not specified it is top
.
window
window-specifier ... close
Close specified window(s), as if you clicked on the “close” button.
window
window-specifier ... detach
Close specified window(s), and (assuming there are no more windows attached to the session) make the session detached.
window
window-specifier ... minimize
(Electron and Qt only.) Minimize (iconify) the specified top-level windows. The minimized windows may be still visible in the task bar, as an icon on the desktop, or during an “windows expose” operation
window
window-specifier ... hide
(Electron and Qt 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
window
window-specifier ... show
(Electron and Qt only.) Show the specified minimized or hidden windows. If there are no windows, create one.
window
window-specifier ... toggle-minimize
(Electron and Qt 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.
window
window-specifier ... toggle-hide
(Electron and Qt 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.
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-positionSpecify the initial size and/or position of a new top-level window. See geometry specifier.
--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-levelFiner-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-nameDomTerm 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=
filenameSpecify 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.
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
portnumStart 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-fileThe name of a file containing the server certificate.
--ssl-key
key-fileThe name of a file containing the passphrase needed for the private key.
--ssl-ca
ca-fileCA (certificate authority) filepath.
--once
(Probably obsolete.)
Only allow a single connect before shutting down.
This option is the default unless --port
is specified.
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 filenameReplace 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
indexPrint out the style rules of the specified stylesheet,
which is an index in the list-stylesheets
output.
disable-stylesheet
indexenable-stylesheet
indexDisable or enable the specified stylesheet.
A index is an integer index into the
list as shown by list-stylesheets
.
$ domterm disable-stylesheet 2
Next: Settings, Previous: Downloading and building, Up: DomTerm [Contents]