====== Command line interface ======

Workcraft command line usage is as follows ''workcraft [OPTIONS] [FILES]''
  * ''OPTIONS'' -- space-separated list of the following options:
    * ''-dir:DIR''           -- path to the working directory
    * ''-config:CONFIG''     -- user config file (default is global ''config.xml'') <wrap info>since **v3.3.6**</wrap>
    * ''-config-add:CONFIG'' -- additional read-only config file to override user config settings <wrap info>since **v3.3.8**</wrap>
    * ''-exec:SCRIPT''       -- JavaScript file or one-liner to execute on startup
    * ''-port:PORT''         -- reuse running instance on ''PORT'' to open ''FILES''
    * ''-nogui''             -- run in console mode
    * ''-noconfig-load''     -- use default settings instead of loading them from user config <wrap info>since **v3.3.8**</wrap>
    * ''-noconfig-save''     -- do not overwrite user config on exit <wrap info>since **v3.3.8**</wrap>
    * ''-noconfig''          -- use default settings and do not overwrite user config
    * ''-version''           -- report the version information and exit
    * ''-help''              -- display this help message and exit
  * ''FILES'' -- space-separated list of work files to open or arguments for ''SCRIPT''

Note that file path parameters ''CONFIG'', ''SCRIPT'' and ''FILES'' are relative to the working directory.

<wrap info>since **v3.3.8**</wrap> Use environment variables ''WORKCRAFT_CONFIG'' and ''WORKCRAFT_CONFIG_ADD'' as lower priority alternatives to command line options ''-config:'' and ''-config-add:'' respectively.

<wrap info>since **v3.4.0**</wrap> To run Workcraft with a specific version of Java Runtime Environment supply it in ''jre'' subdirectory of Workcraft installation. If this directory is not found or if ''WORKCRAFT_USE_NATIVE_JAVA'' environment variable is defined, then a natively installed Java is used.

===== Special symbols in file names =====

If your command line refers to a path containing spaces or other suspicious symbols, then surround it by quotation marks (both ''%%'%%'' and ''%%"%%'' are supported). For example, if you want to set a working directory to //%%"C:\Workcraft Projects"%%// and run a script //%%"Example scripts\test1.js"%%// in there, then Windows command line would look as follows:

<code shell>
workcraft.bat -nogui -dir:"C:\Workcraft Projects" -exec:'Example scripts\test1.js'
</code>

Note that backslash symbols ''\'' in scripts (e.g. in a Windows file path) need to be escaped as in this example (notice the double backslashes):

<code javascript test1.js>
work = load("models\\test1.work");
stat = statModel(work);
write(stat, "C:\\Temp\\test1.txt");
exit();
</code>

Alternatively, Unix-style file hierarchy separator ''/'' can be used, as it does not require escaping and is recognised in all Linux, OSX and Windows:
<code javascript test1.js>
work = load("models/test1.work");
stat = statModel(work);
write(stat, "C:/Temp/test1.txt");
exit();
</code>

In the above examples //%%"Example scripts\test1.js"%%// and //%%"models\test1.work"%%// are relative to the working directory //%%"C:\Workcraft Projects"%%//, while the file //%%"C:\Temp\test1.txt"%%// is specified by its absolute path.
===== Examples of working with scripts =====

  * Execute a script given by its absolute path, running Workcraft without GUI and using all default settings <code bash>
workcraft -nogui -noconfig -exec:'/path/to/script.js'
</code>

  * Execute a script whose path is relative to a given working directory, running Workcraft without GUI and using all default settings <code bash>
workcraft -nogui -noconfig -exec:script.js -dir:'/path/to/working/directory/'
</code>

  * Execute a short JavaScript snippet directly, without creating a script file <code bash>
workcraft -nogui -exec:'print("Hello!");exit();'
</code>


===== Examples of custom config =====

  * Start Workcraft with all default settings and write them into global //config.xml// on exit <code bash>
workcraft -noconfig-load
</code>

  * Start Workcraft with all the settings in global //config.xml// and override some of them by the settings in local //config-specific.xml// (//config.xml// will be overwritten on exit) <code bash>
workcraft -config-add:config-specific.xml
</code>

  * Start Workcraft with all the settings in //config-base.xml//, override some of them by the settings in //config-specific.xml// and do not overwrite config.xml on exit <code bash>
workcraft -config:config-base.xml -config-add:config-specific.xml -noconfig-save
</code>

  * Start Workcraft with default settings, override some of them by the settings in //config-specific.xml// (passed via environment variable) and on exit write all the settings into //config-new.xml// (also passed via environment variable) <code bash>
export WORKCRAFT_CONFIG=config-new.xml
export WORKCRAFT_CONFIG_ADD=config-specific.xml
workcraft -noconfig-load
</code>

===== Reuse running Workcraft instance =====

In order to reuse the same instance of Workcraft for opening ''.work'' files from a command line use ''-port:NUMBER'' option. This will enable Workcraft to check if its instance is already running and listening on that port, and if this is the case, pass data to the running instance via the specified port.

For example, the following sequence of commands would first start Workcraft on port //12345//, then open //file.work//, and finally execute //script.js//, all in the same instance of Workcraft (so //script.js// can refer for model in //file.work//):

<code bash>
workcraft -port:12345
workcraft -port:12345 file.work
workcraft -port:12345 -exec:script.js
</code>

This feature is is also convenient when associating ''.work'' files with Workcraft, so they can be open directly from a file browser. By default, a new instance of Workcraft would start each time a ''.work'' file is open this way. If you prefer to reuse a single instance of Workcraft, this can be achieved by //hard-coding// an unoccupied port number directly into ''workcraft'' runner script (e.g. add ''-port:12345'' just before ''-dir:'' option).