Command‐line interface - arklumpus/TreeViewer GitHub Wiki

In addition to the graphical user interface, TreeViewer also features a command-line interface that can be used to perform administrative tasks (e.g. installing or uninstalling modules) or to plot trees.

This command-line interface consists of command-line options for the TreeViewer executable and of the TreeViewerCommandLine program, which provides an interactive command-line interface for creating tree plots and editing module parameters.

The command-line options for the TreeViewer executable are used mainly to perform administrative tasks, e.g. to install or uninstall modules without going through the graphical interface. The following table lists the available options. Any unrecognised option is treated as the path to a tree file that will be opened in the program.

-h, --help	Shows a list of all the available command-line options and their function.
-d, --delete	Deletes tree files after opening them. Useful when the program reboots and needs to reopen and delete a temporary file.
-w, --wait <milliseconds>	Waits for the specified number of milliseconds before doing anything. Useful when the program reboots to ensure that the previous instance has had time to close properly.
-k, --key </path/to/newkey>	Creates a public/private RSA key pair in JSON format. These are useful if you want to create and sign your own modules. Note that you will have to place your public key in the source code of TreeViewer in order to have your signature recognised as valid.
--welcome	Deletes all the installed modules and starts the program with the welcome window.
--file-associations	Shows the file associations window (not available on macOS).
--module-creator	Starts the program with the module creator window.
--new-process	Normally, TreeViewer attempts to keep only one process running. If this command-line option is provided, it forces the program to spawn a new process. The advantage is that if one of the processes crashes, the other is unaffected; the disadvantage is that if one process does something with global effects (e.g. changing a global setting, installing a module, etc), inconsistencies may happen.
--set-global <setting=value>	Sets the value of a global setting. See Changing the value of global settings below for more details.
--log-exceptions	Logs all exceptions (i.e. errors), handled and unhandled, that occur while running the program. Redirect the standard output (e.g. > log.txt) to save the log to a file. This is useful to identify the root cause when the program suddenly crashes without an apparent reason. Note that a lot of exceptions happen (and are handled) during the normal execution of the program, hence if TreeViewer seems to be working normally do not worry if you enable this option and see a lot of errors.

-I, --install-all[=/path/to/modules.tar.gz]	Uninstalls all currently installed modules, and installs all the modules contained in the specified modules.tar.gz file. If no file is specified, the modules will be downloaded from the module repository.
-i, --install </path/to/module.json.zip>	Installs a module from a module.json.zip file and closes the program (unless the -b/--boot option is also specified). This option can be specified multiple times to install more than one module at once.
--install-references	When installing modules, also installs the additional references for the modules, if available.
--install-unsigned	Makes it possible to install modules without a signature or with an invalid signature.
--delete-modules	Deletes the specified module.json.zip file after installing the module.
-u, --uninstall <module-id>	Uninstalls the module with the specified id and close the program (unless the -b/--boot option is also specified). If modules are being uninstalled and installed at the same time, the modules will be uninstalled first, then the program will be rebooted and the new modules installed (this makes it possible to update a module by uninstalling it and installing the new version in a single program call). This option can be specified multiple times to uninstall more than one module at once.
-b, --boot	Reboots the program to the graphical user interface after installing/uninstalling the modules.
--rebuild-all-modules	Recompiles all the installed modules from the source code. Can be useful in case the module cache gets somehow corrupted.
--clean	Exports all the currently installed modules, then uninstalls all of them, deletes the module cache and reinstalls all the modules. Useful in cases of catastrophic corruption of the module cache that cannot be solved by --rebuild-all-modules.
--fetch-assets	When exporting the modules as part of --clean, re-fetches the assets (e.g. images for the manual) from their remote location, rather than from the local cache. Useful if the module asset cache is also corrupted.
--clean-cache	Deletes the compiled module cache. This option is used as part of the --clean process, and should probably not be invoked by users (use the --clean option instead).

The value of a global setting can be changed by using the --set-global command-line option. This option requires as arguments the name of the global setting and its new value.

The name of the global setting is defined by the module that exports the setting, and generally coincides with the label that appears in the "Preferences" window, including the colon (for example, --set-global "Default cartoon colour:=#FF0000" sets the default cartoon colour to red).

In addition to these settings defined by the modules, there are global settings that are defined by TreeViewer itself:

• AutosaveInterval: defines the time span between two consecutive autosaves (default is 10 minutes). The value is parsed as a culture-invariant TimeSpan string, such as h:m:s (where h is the number of hours, m is the number of minutes and s is the number of seconds). For example, --set-global AutosaveInterval=0:10:0 specifies an interval of 10 minutes.

• DragInterval: defines for how long (in milliseconds) must the mouse button be held on a Plot action/Further transformation module for the program to register the intent to drag it to reorder the modules. For example, --set-global DragInterval=250 specifies an interval of 250 ms (which is the default).

• KeepRecentFilesFor: defines for how long (in days) information about recent files is kept and shown in the home panel. For example, --set-global KeepRecentFilesFor=30 specifies an interval of 30 days (which is the default).

• DrawTreeWhenOpened: defines whether simple tree files (that only contain a tree, without any module information) should be drawn automatically using a default style or not (default is to do so). The possible values are True or False. For example, --set-global DrawTreeWhenOpened=False disables this option.

• ShowLegacyUpDownArrows: defines whether the up and down arrows that were present in previous versions of TreeViewer are shown for Further transformation and Plot action modules. The possible values are True or False. For example, --set-global ShowLegacyUpDownArrows=False disables this option (which is the default).

• SelectionColour: determines the colour used for selected nodes in the tree (the default is #237FFF). The colour should be specified as a CSS colour string (e.g. #FF0000, red or rgb(255,0,0)). For example, --set-global SelectionColour=violet sets the selection colour to violet.

• ModuleRepositoryBaseUri: sets the base URI for the module repository (the default is this repository, i.e. https://raw.githubusercontent.com/arklumpus/TreeViewer/main/Modules/). Note that this can be the path to a local folder on the computer.

• UpdateCheckMode: determines what kind of updates are checked when the program starts (the default is to check for updates for TreeViewer and for all the modules). Possible values are: DontCheck, ProgramOnly, ProgramAndInstalledModules, ProgramAndAllModules.

• InterfaceStyle: determines the appearance of the buttons in the interface. Possible values are: Windows (default on Windows and Linux) or macOS (default on macOS).

• RibbonStyle: determines the background colour of the ribbon. Possible values are: Colourful (default on Windows, note the British spelling) or Grey (default on macOS and Linux, again note the British spelling).

• EnableUndoStack: determines whether all the elements that are necessary to allow undoing/redoing actions are enabled. The possible values are True (the default) or False. For example, --set-global EnableUndoStack=False disables this option. You should only need to disable this on very slow/memory-limited machines.

• PairwiseTreeComparisons: when computing statistics such as distance metrics, determines whether the trees that are being compared should be trimmed down so that they only contain the set of leaves that are in common between all of them, or if they should be trimmed in a pairwise fashion (which is the default). For example --set-global PairwiseTreeComparisons=False tells the program to use global trimming.

• ClusterAccordingToRawDistances: when creating plots of tree space, determines whether trees should be clustered according to the raw (Robinson-Foulds) distances, or according to the 2D metric induced by the multidimensional analysis (which is the default). For example, --set-global ClusterAccordingToRawDistances=True tells the program to use the raw distances.

If a value is not specified for the setting, the setting is returned to its default value. For example, --set-global ModuleRepositoryBaseUri= resets the module repository URI to the default value.

TreeViewerCommandLine is a command-line version of TreeViewer that is installed alongside the main program. If the install path of TreeViewer has been added to the PATH environment variable, it can be invoked by typing TreeViewerCommandLine in a command-line environment, otherwise the full path to the program needs to be provided.

TreeViewerCommandLine uses colour to convey information; however, due to how the console interface is implemented, on some systems this can cause a slowdown of the program. If you wish to disable the use of colours for any reason, you can use the NO_COLOR environment variable. For example, on Linux or macOS you can run: NO_COLOR=true TreeViewerCommandLine, while on Windows you can run set NO_COLOR=true && TreeViewerCommandLine.

A list of the commands that are available in TreeViewerCommandLine can be obtained by using the help command. Specific information about a command can be obtained by typing help <command>; for example, help open shows information about the open command.

Tab-completion is available for all commands. Pressing the tab key once completes the command if there is only one option available, while pressing it twice or more shows a list of the available options if there is more than one. For commands that support a file name as a parameter, the tab-completion works as expected, by listing and selecting the files.

CTRL+C terminates the execution of the current command. CTRL+D closes the program (same as the exit or quit commands).

The module command can be used to enable or disable modules for the plot. Module arguments for this command can be specified by their name or by their ID (which makes it possible to distinguish between modules with the same name, but different IDs, such as the Custom script further transformation and the Custom script plot action).

Furthermore, when a module needs to be selected out of the ones that have been enabled, it can be specified based on its index (e.g. module disable #5 disables the fifth module), which is useful to distinguish between different instances of the same module. The list of modules that have been enabled together with their index can be obtained with the command module list enabled.

The available options for a module can be displayed by first selecting the module (e.g. module select Rectangular) and then using the option list command. Then, an option can be selected using the option select command (e.g. option select Width or option select #1 - the option can be specified either by its name, or by its index). This will also list the possible values or ways in which the value of the option can be changed. The value of the option can be set using the option set command (e.g. option set 1000).

Some Action and Selection action modules can be invoked in command line mode, while others cannot. These modules are invoked by enabling them (e.g. module enable Rooted tree style). Selection action modules invoked in this way act on the node that has been currently selected using the node command. Modules that have sub-items in the TreeViewer GUI can be invoked by adding the name of the sub-item after the module name (e.g. module enable Reshape tree Rooted style).

The node command can be used to select a node in the tree and show information about it. For example, node select "taxonA" "taxonB" selects the last common ancestor (LCA) of taxonA and taxonB (note that taxon names need to be enclosed within double quotes). node info shows information about the currently selected node, including the leaves that descend from it, the index of the nodes that descend directly from it (which can be used as an argument to node select), the number of direct and total descendants, the number of descendant leaves, and some taxa that have that node as their LCA.

For more information about the other commands, use the help function within TreeViewerCommandLine.