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) since v3.3.6
  • -config-add:CONFIG – additional read-only config file to override user config settings since v3.3.8
  • -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 since v3.3.8
  • -noconfig-save – do not overwrite user config on exit since v3.3.8
  • -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.

since v3.3.8 Use environment variables WORKCRAFT_CONFIG and WORKCRAFT_CONFIG_ADD as lower priority alternatives to command line options -config: and -config-add: respectively.

since v3.5.2 Multiple additional config files can be passed by using -config-add: several times, each next file overriding the matching setting in the preceding ones.

since v3.4.0 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.

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:

workcraft.bat -nogui -dir:"C:\Workcraft Projects" -exec:'Example scripts\test1.js'

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):

test1.js

work = load("models\\test1.work");
stat = statModel(work);
write(stat, "C:\\Temp\\test1.txt");
exit();

Alternatively, Unix-style file hierarchy separator / can be used, as it does not require escaping and is recognised in all Linux, OSX and Windows:

test1.js

work = load("models/test1.work");
stat = statModel(work);
write(stat, "C:/Temp/test1.txt");
exit();

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.

• Execute a script given by its absolute path, running Workcraft without GUI and using all default settings

  workcraft -nogui -noconfig -exec:'/path/to/script.js'

• Execute a script whose path is relative to a given working directory, running Workcraft without GUI and using all default settings

  workcraft -nogui -noconfig -exec:script.js -dir:'/path/to/working/directory/'

• Execute a short JavaScript snippet directly, without creating a script file

  workcraft -nogui -exec:'print("Hello!");exit();'

• Start Workcraft with all default settings and write them into global config.xml on exit

  workcraft -noconfig-load

• 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)

  workcraft -config-add:config-specific.xml

• 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

  workcraft -config:config-base.xml -config-add:config-specific.xml -noconfig-save

• 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)

  export WORKCRAFT_CONFIG=config-new.xml
  export WORKCRAFT_CONFIG_ADD=config-specific.xml
  workcraft -noconfig-load

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):

workcraft -port:12345
workcraft -port:12345 file.work
workcraft -port:12345 -exec:script.js

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).