Headless¶

‘’modo’’ 302 introduced “‘headless’” operation, allowing modo to act as a command line program with no graphical user interface.

Preface ¶

Various command line switches are also used in this article. Many of these switches also work with the full GUI mode as well. You should be comfortable with the MS-DOS prompt in Windows and the Terminal in OS X to use headless mode. The MS-DOS prompt and Terminal will henceforth be referred to as the ‘’command line’’ or ‘’console’’.

License ¶

The headless mode still requires a normal modo license to operate, and will fail with a license not found error if none is present.

Config File ¶

Console mode uses its own config file. For modo 501 on Windows, this is modo_cl501.cfg, while on OS X this would be com.luxology.modo_cl501.

Telnet vs. Headless ¶

Telnet operates very similar to headless mode, except that telnet can also be used from the GUI. The way commands are sent to and output is received from modo is identical for both telnet and headless.

Headless Basics ¶

Running Headless ¶

Headless modo is a separate executable. On Windows, it is ‘’modo_cl.exe’’, and is run just like any other command line program through the MS-DOS prompt.

 modo_cl.exe

On OS X, modo_cl is inside the application bundle, and can be run from the Terminal.

 modo.app/Contents/MacOS/modo_cl

After modo finishes stating up, you?ll be greeted with the following lines, which include a start message containing the build number, followed by a line showing the registered name associated with the license modo is using.

 @start  modo [xxxxx]  Luxology LLC
 John Smith
 >

modo is now ready to start accepting commands. You can type any normal, non-UI command here and it will execute normally, with its results returned through stout.

Exiting Headless Mode ¶

You can quit headless mode just like you can in GUI mode, by executing the app.quit command. You may also be able to use ctrl-C to immediately terminate modo, but using app.quit ensures a proper shutdown.

 app.quit
 @exit
 ok

Changing the Prompt ¶

By default, modo shows an greater than symbol (‘’>’’) when it is read for you to enter commands. You can use the -prompt switch to set the prompt to any character sequence you?d like. The following replaces the standard prompt with the string ready: and a space.

Windows

modo_cl.exe "-prompt:ready: "

OSX

modo.app/Contents/MacOS/modo_cl "-prompt:ready: "

After modo finishes starting up, you?ll see this:

 @start  modo [xxxxx]  Luxology LLC
 John Smith
 ready:

Formatting ¶

Headless mode conveys information to the user by prefixing certain lines with special characters. As of modo 501, all lines will start with a prefix. These were further standardized in 601.

Prefix	Description
>	Prompt, indicating that you can enter more commands. The prompt can be replaced with a custom one via the -prompt: command line switch.
	The last command executed successfully
	The last command returned an error
:	A result from a query. There is one result per line, with each line starting with a colon.
#	A comment line output by modo, which can be ignored
!	Output from the log system
@	System message

This is an example of a system message.

 @start  modo [xxxxx]  Luxology LLC

This is an example of the prompt, a series of queried results, and a success message.

 > query platformservice "" ?
 : licensedto
 : iseval
 : expiresin
 : serialnumber
 : numlicenses
 : appname
 : appversion
 : appbuild
 : isheadless
 : ostype
 : osname
 : osversion
 : paths
 : path.path
 : importpaths
 : isapp64bit
 : alias
 + ok

Lines beginning with an exclamation point (‘’!’’) are from the log system. The exclamation point is immediately followed by the name of the subsystem that issued the event wrapped in parentheses, followed by a space and the logged event itself. This output is otherwise identical to what is shown in the Event Log Viewport]] or the [[Feedback Viewport]] (for rolling messages). Log system output can be toggled with the [[log.toConsole]] and [[log.toConsoleRolling]] commands, and is disabled by default. See [[#Logging to the Console for more information.

Executing and Querying Commands ¶

Commands are executed just like they are from the full Command History Viewport]] of the modo GUI. You can think of the headless prompt as being like the Command History’s [[Command History Viewport#Command Entry. Results of command executions and queries go right to stdout and appear in the console.

From the Console ¶

When you see the prompt, you can enter a new command to execute or query. The Command System: Basics is exactly the same as it is from within ‘’modo’’. The formatting described above is about the only real difference.

Obviously, no commands requiring a GUI will work from headless mode, including dialogs. Most commands that open dialogs also include arguments that can be used in lieu of the dialogs, so no functionality is lost by running in headless mode.

 > select.item Camera
 + ok
 > item.channel focalLen ?
 : 0.05
 + ok
 > item.channel focalLen 0.1
 + ok
 > item.channel focalLen ?
 : 0.1
 + ok

Redirected From a File ¶

You can pass a list of commands from a file directly into modo on startup via redirection. Redirection is a standard feature of the console. Each line of a file is processed as a separate command, and each is executed in turn, similar to a macro. Once all lines are processed, modo will quit.

It is important to note the the redirection syntax is a feature of the console, not a feature of ‘’modo’’. This means that it is unlikely to work from a scripting language or another program that doesn’t also emulate console behaviors like redirection. In those cases, you should use one of the other methods, such as From a Pipe, to pass commands into modo.

Windows

modo_cl.exe < commands.txt

OSX

modo.app/Contents/MacOS/modo_cl < commands.txt

From a Pipe ¶

The real power of the headless mode comes from piping commands into it by redirecting stdio (specifically, stdin and stdout) to your application. This allows scripts and external programs to have direct control over modo by emulating the input and output provided by a console. For example, Perl]] has a standard syntax for opening a one-way pipe. Once the connection has been established, perl?s print() function can be used to send commands to modo. When you are finished you can call [[app.quit to close ‘’modo’’.

Perl

#perl
open (MODOCMD, "| modo_cl");
print MODOCMD "scene.open $myscene\n";
print MODOCMD "render.animation\n";

Python

 #python
 #-------------------------------------------------------------------------
 #vs9841 2013-10-23 Add Edit
 #The python script running on python v3.3.2,and the test in modo v701 sp2.
 #This script does not need the built- in modo python environment to run ,
 #I was using the operating system installed python v3.3.2 tested.
 #-------------------------------------------------------------------------
 import subprocess modocl = "D:\\Program Files\\Luxology\\modo\\701_sp2\\modo_cl.exe"
 modosc = 'scene.open "H:\\modo\\Study\\zx.lxo"\n'
 p = subprocess.Popen(modocl,
                stdin = subprocess.PIPE,
                stdout = subprocess.PIPE,
                stderr = subprocess.PIPE,
                universal_newlines=True,
                shell = False)
 print(p.stdout.readline())
 p.stdin.write(modosc)
 p.stdin.write('query sceneservice scene.name ? current\n')
 p.stdin.write('app.quit\n')
 print(p.stdout.read())

Two way pipes can be opened from other programs and scripts. This permits full two way communication with modo, allowing commands to be sent and results to be received. Programs can also capture stdin and stdout and handle input and output that way. See the documentation for your scripting language or platform API for more information on using stdin, stdout, pipes and controlling command line programs.

Logging to the Console ¶

By default, the logged messages are not output in the console. The log.toConsole command will cause entries that would normally appear in the ‘’Event Log Viewport’’ to go to the console. log.toConsoleRolling does the same for rolling log entries that would normally appear in the Feedback Viewport. These events are prefixed with an exclamation point and the subsystem name in parentheses.

 log.toConsole true
 log.toConsoleRolling true

Logging rolling log output to the console is most useful to get Network Rendering#Extended Render Progress Information while rendering. This will also enable the messageDialogs output, which contains the human-readable output of various dialogs that would open in the full version of modo, but which are suppressed in headless mode.

Another example might be dialogs created with the dialog.??? commands. Output of the most recent dialog is always logged to the messageDialogs rolling log. For example, the following loginfo.py shows the modo version in a dialog:

#python

import lx

x = lx.eval('query platformservice appversion ?')
if x > 401:
        lx.eval('dialog.setup info')
        lx.eval("dialog.title {Version...}")
        lx.eval("dialog.msg {Your modo version is %d}" % x)
        lx.eval("dialog.open")

Dialogs will not open in headless mode, but they are still logged. After executing log.toConsoleRolling command, you will see the following in the console:

 @start  modo_cl [xxxxx]  Luxology LLC
 >log.toConsoleRolling true
 + ok
 >@loginfo.py
 ! (messageDialogs) [Info] - Version... | Your modo version is 701
 + ok
 >

What Gets Output ¶

By default, all enabled log subsystems are output to the console (and displayed in the Log View). Subsystems are enabled and disabled with ‘’log.subEnable’’. Many subsystems are enabled by default, but some of the more esoteric ones aren’t.

Rather than outputting all enabled subsystems, you can choose a specific subset with the following commands:

log.subToConsole makes it possible to output just a specific subsystem or set of subsystems to the console. Once this is called with ‘’true’’, only that one subsystem will be output. Calling it with true again for other subsystem will output that subsystem’s entries as well. Calling it again with false for all of those subsystems will reset it back to showing all enabled log subsystems. You can think of it as the “when nothing is selected, everything is selected” behavior that modo normally uses.
log.consoleReset turns back on all log subsystem console output, and is equivalent to calling log.subToConsole with false for all subsystems..
log.subToConsoleOnly can be used to stop outputting all log subsystems except for one specific one. This is the same as calling log.consoleReset followed by log.subToConsole for the one system you want enabled.

One-Time Saving ¶

‘’log.masterSave’’ and log.subSave can also be used to save the log to a file, wether or not log.toConsole is enabled. These work in the same way that the Save popup in the Event Log viewport does, and will save the same information – meaning, only entries from subsystems that were enabled at the time they were added, not at the time of saving the log .

Note that rolling log messages cannot currently be saved, since the previous message is discarded as soon as a new one comes in (hence the term “rolling”).

 log.masterSave "c:\masterLog.txt"

Saving On The Fly ¶

‘’log.subToFile’’ and log.subToFileRolling can be used to write log entries to disk as they come in. The master log (meaning, all enabled subsystems, instead of a single specific subsystem) can also be saved by passing an empty string or master as the subsystem. log.subToFileCloseAll stops writing to all open files and closes them.

Other Command Line Switches ¶

There are a few other command line switches used in modo. These can be used from both the headless and GUI modes, unless otherwise specified.

Headless mode: -console and -prompt ¶

-console ¶

The -console switch determines how headless handles input. The default is to use the command parser, like the one used at the bottom of the Command History viewport. The other option is to treat input as Python instructions, thus allowing it to behave as a Python shell.

Windows

modo_cl.exe -console:python

OSX

modo.app/Contents/MacOS/modo_cl -console:python

In older versions of modo, the -console switch was used in older versions of modo to launch the main modo application in headless mode on OS X. This switch is no longer used in that way; instead, a separate modo_cl program (stored within the modo application bundle) is used in exactly the same way as its Windows counterpart, as described above.

-prompt ¶

The -prompt switch is also described above, and allows you to change the prompt modo uses to request input from the user in headless mode. This does nothing in GUI mode.

Windows

modo_cl.exe "-prompt:ready: "

OSX

modo.app/Contents/MacOS/modo_cl "-prompt:ready: "

Executing an Initial Command: -cmd ¶

It is possible to tell modo to run an intiial command at startup through the -cmd switch. This can be thought of as a single startup command, and is executed after all config-based startup commands.

This feature is most useful for Newtork Rendering, allowing them to launch modo and tell it to execute a specific script on startup while also passing arguments to that script. For example, this would pass two arguments with the values path and range to the @myrender.pl script on startup.

Note that the redirection method described above or Telnet might be better than using the -cmd switch, as redirection allows multiple commands to be passed and automatically quits modo when finished.

Windows

modo_cl.exe "-cmd:@myrender.pl {path range}"

OSX

modo.app/Contents/MacOS/modo_cl "-cmd:@myrender.pl {path range}"

Executing a Late Initial Command: -cmdlate ¶

‘’-cmdlate’’ is identical to ‘’-cmd’’, except for when it is executed. -cmd commands are executed immediately after the config-based startup commands, but before licensing and networking are started. -cmdlate commands are executed well after those systems are started up, and are basically the last thing that is done before control is given over to the user.

The main use for this is to open telnet]] or [[Preview Socket listeners on startup from a script. Using conventional startup commands this is not possible, as they would all run before networking is available.

Windows

modo_cl.exe "-cmdlate:@mytelnet.py"

OSX

modo.app/Contents/MacOS/modo_cl "-cmdlate:@mytelnet.py"

Changing the User Config Path: -config ¶

The -config switch tells modo to use a different path for the user configuration file. This can be used by render nodes to load a specific config, or used in conjunction with -license to run modo off of a memory stick without requiring anything to be written to the local machine.

The path provided can either point to an actual config file, or to a directory containing a config file with the standard Standard User Config Filenames. The specified config will used in place of the default, which means that not only will initial settings be loaded from this config, but settings will also be saved to this file on quit.

Note that on OS X all paths must be absolute; relative paths, including the home (~) path, are not supported.

Windows

modo_cl.exe "-config:c:\myUserConfigDir"
modo_cl.exe "-config:c:\myUserConfig.cfg"

OSX

modo.app/Contents/MacOS/modo "-config:/Volumes/Macintosh HD/Users/myusername/myUserConfigDir"
modo.app/Contents/MacOS/modo "-config:/Volumes/Macintosh HD/Users/myusername/myUserConfigDir.cfg"

Changing the License Path: -license ¶

The -license switch allows you to tell modo to search for the license file in a specific path. This must point to the directory containing the license, not the license file itself. When combined with the -config switch, this can be used to run modo off of a memory stick without needing to write anything to the system drive. -license is functionally identical to ‘’-path:license=<path>’’, as described below.

Note that on OS X all paths must be absolute; relative paths, including the home (~) path, are not supported.

Windows

modo_cl.exe "-license:c:\Licenses"

OSX

modo.app/Contents/MacOS/modo "-license:/Volumes/Macintosh HD/Users/myusername/Licenses"

Changing Other Standard Paths: -path ¶

The -path parameter allows you to override many of modo’s standard paths. The format is ‘’-path:<name>=<path>’’. The following names are currently defined.

Name	Description
temp	Directory for temporary files
license	License directory containing license keys
resource	Resource directory used to load default application resources
module	Plug-in auto-search directory
prefs	Location of the user config
help	Directory containing help files
user	User directory, used as a search path for user-specific resources, scripts and other extensions
content	Location of installed content
asset	Location of installed assets, usually a sub-directory of ‘’content’’

Note that on OS X all paths must be absolute; relative paths, including the home (~) path, are not supported.

Windows

modo_cl.exe "-path:temp=c:\temp"

OSX

modo.app/Contents/MacOS/modo "-path:temp=/Volumes/Macintosh HD/Users/myusername/temp"

Changing Paths through Environment Variables ¶

Each of these paths can also be overridden through environment variables named NEXUS_ followed by the name to remap. For example, content can be redirected with the environment variable ‘’NEXUS_CONTENT’’.

Running in slave mode: -slave ¶

The -slave switch forces modo to start up in slave mode for Network Rendering command cannot be executed as a startup command or through the -cmd switch. Furthermore, slave mode can only be run from the GUI version of modo, and will not work from the headless mode.

Windows

modo.exe -slave

OSX

modo.app/Contents/MacOS/modo -slave

Telnet Server ¶

The -telnet switch can be used to launch modo and automatically start the Telnet article for more information on using telnet.

It is also possible to open telnet in ‘’named pipe’’ mode, in which case the port number is replaced with the pipe name. Note that this pipe mode is simply a way of using raw mode telnet-style functionality from a named pipe, and is different from From a pipe.

Windows

modo_cl.exe -telnet:12357
modo_cl.exe -telnet:telnet@12357
modo_cl.exe -telnet:raw@12357
modo_cl.exe -telnet:pipe@myPipeName

OSX

modo.app/Contents/MacOS/modo -telnet:12357
modo.app/Contents/MacOS/modo -telnet:telnet@12357
modo.app/Contents/MacOS/modo -telnet:raw@12357
modo.app/Contents/MacOS/modo -telnet:pipe@myPipeName

Modo Socket comms wrapper, an example wrapper for ‘raw’ socket mode written in Python.

Loading an Initial Scene ¶

Any scene can be loaded at startup by entering its path at the end of the argument list. There is no special argument name for this feature.

Once again, note that on OS X, all paths must be absolute; relative paths, including the home (~) path, are not supported.

Windows

modo_cl.exe "c:\MyScene.lxo"

OSX

modo.app/Contents/MacOS/modo "/Volumes/Macintosh HD/Users/myusername/MyScene.lxo"

Debug Flags: -dblog, -dbon, -dboff and -debug ¶

A few debugging flags exist in modo. These are generally only for internal use, but you may be asked by customer service to enable them to help track down an issue.

-dblog ¶

The -dblog switch instructs modo to write a log to the path provided. The exact contents of this log varies depending on which other debug flags are set.

Windows

modo_cl.exe "-dblog:C:\modolog.txt"

OSX

modo.app/Contents/MacOS/modo "-dblog:/Volumes/Macintosh HD/Users/myusername/modolog.txt"

-dbon and -dboff ¶

The -dbon and -dboff switches toggle specific debugging operations on and off. Most of these are only useful for internal purposes, but there are a few that are useful to end users. For example, -dbon:noconfig will load your user config on startup, but will not save to it when the application quits.

Windows

modo_cl.exe -dbon:noconfig

OSX

modo.app/Contents/MacOS/modo -dbon:noconfig

-debug ¶

This sets the verbosity of the debug output that is saved to the log. The options are ‘’quiet’’, ‘’error’’, ‘’normal’’, track and ‘’verbose’’. Note that turning on track or verbose can affect the performance of the application.

Windows

modo_cl.exe -debug:normal

OSX

modo.app/Contents/MacOS/modo -dbon:normal