command-line-options.md

Text-based Desktop Environment

Command-line options

Syntax

vtm [ -c <file> ][ -q ][ -p <id> ][ -s | -d | -m ][ -x <cmds> ]
vtm [ -c <file> ][ -q ][ -t | -g ][ -r [ <type> ]][ <args...> ]
vtm [ -c <file> ]  -l
vtm -i | -u | -v | -?

<script relay via piped redirection> | vtm [ -p <id> ]

By default, vtm runs Desktop Client, running an additional instance with Desktop Server in background if it is not running.

Option	Description
-h, -?, --help	Print command-line options.
-v, --version	Print version.
-l, --listconfig	Print configuration.
-t, --tui	Force TUI mode.
-g, --gui	Force GUI mode.
-i, --install	Perform system-wide installation. Allow Desktop Server to run in user context in Session 0 on Windows. Placing Desktop Server in Session 0 allows console applications to run independently of the user's GUI login session. Note: This prevents GUI applications from running from the vtm desktop environment. See "Session 0 Isolation" on the Web for details.
-u, --uninstall	Perform system-wide deinstallation.
-0, --session0	Use Session 0 to run Desktop Server in background.
-q, --quiet	Disable logging.
-x, --script <cmds>	Specifies script commands to be run by the desktop when ready.
-c, --config <file>	Specifies a settings file to load or plain xml-data to merge.
-p, --pin <id>	Specifies the desktop id it will be pinned to.
-s, --server	Run Desktop Server.
-d, --daemon	Run Desktop Server in background.
-m, --monitor	Run Desktop Monitor.
-r, --, --run	Run desktop applet standalone.
<type>	Desktop applet to run.
<args...>	Desktop applet arguments.
--env <var=val>	Set environment variable.
--cwd <path>	Set current working directory.

The plain xml-data could be specified in place of <file> in --config <file> option:

• command-line:

  vtm -c "<config><terminal><scrollback size=1000000/></terminal></config>" -r term

  or (using compact syntax)
• command-line:

  vtm -c "<config/terminal/scrollback size=1000000/>" -r term

Desktop Applets

Applet	Type	Arguments
Teletype Console (default)	vtty	CUI application with arguments to run
Terminal Console	term	CUI application with arguments to run
DirectVT Gateway	dtvt	DirectVT-aware application to run
DirectVT Gateway with TTY	dtty	CUI application to run, forwarding DirectVT I/O

The following commands have a short form:

• vtm -r vtty <cui_app...> can be shortened to vtm <cui_app...>.
• vtm -r dtty ssh <user@host dtvt_app...> can be shortened to vtm ssh <user@host dtvt_app...>.

Script commands

Syntax: <command>([<args...>])[; <command>([<args...>]); ... <command>([<args...>])]

Script Command	Description
vtm.run([<attr_list...>])	Create and run a menu item constructed using a space-separated list of <attribute>=<value> (derived from existing or updated temporary item). Create and run temporary menu item constructed using default attributes if no <attr_list...> specified. See Settings/Taskbar menu item attributes for details.
vtm.set(id=<item_id> [<attr_list...>])	Create or override a menu item using a space-separated list of <attribute>=<value>.
vtm.del([<item_id>])	Delete the taskbar menu item by <id>. Delete all menu items if no <id> specified.
vtm.dtvt(<dtvt_app...>)	Create a temporary menu item and run the specified dtvt-executable.
vtm.selected(<item_id>)	Set selected menu item using specified <id> (affected to the desktop RightDrag gesture and Tile's + button).
vtm.shutdown()	Terminate the running desktop session.

Character escaping

The following escaped characters have special meaning:

Characters	Expanded to
\a	ASCII 0x07 BEL
\t	ASCII 0x09 TAB
\n	ASCII 0x0A LF
\r	ASCII 0x0D CR
\e	ASCII 0x1B ESC
\\	ASCII 0x5C Backslash
\u	A Unicode escape sequence in the form \u{XXX} or \uXXX, where XXX is the hexadecimal codepoint value.
$0	Current module full path

Usage Examples

	Description
vtm	Run Desktop Client.
vtm ssh <user@server> vtm	Run Desktop Client remotely over SSH.
vtm -r term	Run Terminal Console.
vtm -r term </path/to/console/app...>	Run Terminal Console with a CUI application inside.
vtm ssh <user@server> vtm </path/to/console/app...>	Run a CUI application remotely over SSH.
vtm -x "vtm.del(); vtm.set(splitter id=Apps); vtm.set(id=Term)"	Run Desktop Client and reconfigure the taskbar menu.
echo "vtm.del(); vtm.set(splitter id=Apps); vtm.set(id=Term)" | vtm echo "vtm.set(id=user@server type=dtty cmd='ssh <user@server> vtm')" | vtm	Reconfigure the taskbar menu of the running desktop.
echo "vtm.run()" | vtm echo "vtm.run(id=Term)" | vtm echo "vtm.dtvt(vtm -r term)" | vtm	Run Terminal Console on the running desktop.
echo "vtm.run(title='Console \nApplication' cmd='</path/to/app...>')" | vtm	Run Teletype Console with a CUI application inside on the running desktop.
echo "vtm.run(type=tile title=Terminals cmd='v(h(Term,Term),Term)')" | vtm	Run Tiling Window Manager with three terminals attached.
echo "vtm.shutdown()" | vtm	Terminate the running desktop session.