Command-line interface (CLI) for headless batch mode

Command-line arguments offer a variety of options that generally override the corresponding parameters in the preferences. The CLI option for mzmine offers to run one batch file (-batch). This batch file can be easily generated by another script or can be a standardized batch file for an analytical method that is applied to multiple datasets.

The most convenient way to apply a batch file to other datasets is to specify the -input and -output arguments to process all import files and to redirect all outputs to another directory. See examples below for how to process all .mzML files in a folder and to redirect outputs to a new directory and base filename.

Selecting a user

Running mzmine in CLI mode requires a user with a valid license. There are three ways to provide one:

• -cli-token "\<TOKEN>" (recommended for pipelines and servers): a token created in the mzio user account console under CLI tokens. Every run automatically claims a free license from your license pool, so parallel runs need one free license each. See CLI tokens for pipelines.
• -login (web browser support required): signs in interactively and stores the user on this computer. The most recently active user is then automatically selected for mzmine processing. Without -batch, mzmine closes again after the login.
• -user "path/to/user.mzuser4": uses a specific user file. Alternatively, provide only the user name, e.g. -user testuser, to use testuser.mzuser4 from your system USER directory under /.mzmine/users/. This is mainly intended for offline (airplane mode) licenses, which are bound to one computer and do not require an internet connection.

Use -list-users to print all users available on this computer together with their license state.

Note

Legacy .mzuser files from older mzmine versions use a different format and are rejected. Log in again via the graphical user interface, -login, or -cli-token to create a new user file.

Windows

For command-line mode, the mzmine_console.exe is preferred as it will print the logging output to the console.

An easy way to start mzmine with arguments is to create a shortcut to the mzmine.exe or the mzmine_console.exe, right-click, and define the target with additional arguments. This example runs mzmine in batch mode (headless), imports the specified batch file, overrides the memory management to none (which is the default), effectively using memory mapping to store and access spectral, centroid, and feature data from temporary files stored in the defined temp directory. By leaving out the memory or temp arguments, the values stored in the current preferences file will be used, or the default values if no preferences file was found.

Login to a user in command-line mode

# login in browser
"C:\Program Files\mzmine\mzmine_console.exe" -login

# list all users available on this computer
"C:\Program Files\mzmine\mzmine_console.exe" -list-users

Run headless with a CLI token (no interactive login)

"C:\Program Files\mzmine\mzmine_console.exe" -cli-token "TOKEN" -batch "D:\batch\my_batch_file.mzbatch" -input "D:\Data\*.mzML" -output "D:\Results\basename"

Process all .mzML files in a folder by the provided batch file, redirect output files to results folder and use a base filename, various export modules add a specific suffix

"C:\Program Files\mzmine\mzmine_console.exe" -user "D:\user\testuser.mzuser4" -batch "D:\batch\my_batch_file.mzbatch" -input "D:\Data\*.mzML" -output "D:\Results\basename"

Defining the temp folder, otherwise uses the one specified in local configuration

"C:\Program Files\mzmine\mzmine_console.exe" -user "D:\user\testuser.mzuser4" -batch "D:\batch\my_batch_file.mzbatch" -temp "D:\tmpmzmine"

Start mzmine batch with memory mapping (DEFAULT)

"C:\Program Files\mzmine\mzmine_console.exe" -user "D:\user\testuser.mzuser4" -batch "D:\batch\my_batch_file.mzbatch" -memory none -temp "D:\tmpmzmine"

Start mzmine batch on machines with enough memory (RAM) with -memory all this will disable memory mapping to temporary files.

"C:\Program Files\mzmine\mzmine_console.exe" -user "D:\user\testuser.mzuser4" -batch "D:\batch\my_batch_file.mzbatch" -memory all -temp "D:\tmpmzmine"

macOS

If the app was installed to the Applications folder, run this command in the terminal to run a batch file:

/Applications/mzmine.app/Contents/MacOS/mzmine -user "path/to/testuser.mzuser4" -batch /path/to/batch_file.mzbatch

/Applications/mzmine.app/Contents/MacOS/mzmine -user "path/to/testuser.mzuser4" -batch /path/to/batch_file.mzbatch -input "/path/to/data/*.mzML"

Linux

If mzmine was installed (see instructions) correctly, run the code below to start mzmine in GUI mode or CLI batch mode:

/opt/mzmine/bin/mzmine
# some older versions or bad installations may be in:
# /opt/mzmine-linux-installer/bin/mzmine

# run headless with a CLI token
/opt/mzmine/bin/mzmine -cli-token "<TOKEN>" -batch /path/to/batch_file.mzbatch

# or login in the browser once, then run a batch
/opt/mzmine/bin/mzmine -login
/opt/mzmine/bin/mzmine -batch /path/to/batch_file.mzbatch

Argument table

Argument	Options (default)	Description	Available since
-v and -version	no argument	show version
-h and -help	no argument	show help
-u and -user	a path, e.g., "D:\myuser.mzuser4", or a user name, e.g., testuser	Path to an .mzuser4 file to login a user. This file is copied to the users directory. Alternatively, provide only the user name to use that user from the users directory. To obtain a user file, login in the mzmine graphical user interface (GUI) or claim an offline license in the mzio user account console. User files can be found in your system USER directory in /.mzmine/users/ after login. Legacy .mzuser files from older mzmine versions are rejected, login again to create a new user file. Intended for offline (airplane mode) licenses; for online users prefer -cli-token to automatically claim and release licenses from the floating pool.
-cli-token	a token, e.g., "TOKEN"	Login with a pregenerated token and automatically claim a license from the license pool for this run. Create the token in the mzio user account console under CLI tokens. Intended for headless runs such as CI pipelines or cloud jobs. Parallel runs each claim their own license. See CLI tokens.	4.11
-login	no argument	Use the command-line to login to a user. This will open the login website in the system internet browser, if supported. After successful login, a user file will be copied to your system USER directory in /.mzmine/users/. And the current user will be saved to the configuration. The created user file can be accessed with the -user argument on the next startup. Without -batch, mzmine closes again after the login.
-list-users	no argument	List all users available on this system. The users are read from the system USER directory /.mzmine/users/.
-b and -batch	a path, e.g., "D:\batch.mzbatch"	Path to batch file that will be run in command-line mode.
-i and -input	a txt file or glob pattern, e.g., "D:\Data*.mzML"	input data files. Either defined in a .txt text file with one file per line or by glob pattern matching. To match all .mzML files in a path: -i "D:\Data\*.mzML"
-l and -libraries	a txt file or glob pattern, e.g., "D:\Data*.json"	spectral library files. Either defined in a .txt text file with one file per line or by glob pattern matching. To match all .json or .mgf files in a path: -libraries "D:\Data\*.json"
-o and -output	An output path and base filename, e.g., "D:\basename"	The base file name will be extended by default module names to export all files.
-m and -memory	none, all, features, centroids, raw, masses_features	Defines what data is kept in memory (RAM) or otherwise memory mapped to the temp directory. Generally this setting should be none. If memory is no issue this option might be set to all process all spectral and feature data in memory. The option masses_features keeps centroid mass lists and features in memory while memory mapping raw spectral data.
-t and -temp	a path, e.g., "-temp "D:\tmpmzmine\"	The defined directory should be on a fast drive (usually SSD > HDD > network drive) with enough free space. Local drives are usually preferred. mzmine uses memory mapping to efficiently store and access spectral and feature data. This can lead to a considerable temporary consumption of disk space. Make sure that the selected drive has enough space (maybe 20 GB + 1 GB/10 files; generously over estimated).
-p and -pref	a path, e.g., "D:\config.mzconfig"	An mzmine configuration file in xml format. The general preferences.
-threads	int number of threads or 'auto'	replace the preference parameter with either 'auto' to detect the number of available cores - or an int number of threads for processing.
-ignore-parameter-warnings	no argument	When a .mzbatch file from an older mzmine version was loaded that may have an influence on the mzmine processing, the cli mode will fail by default, printing a message of the affected parameters. If this argument is set, the warnings will be ignored and the batch will be run anyway.	4.6.14

Robin Schmid, Steffen Heuckeroth, omokshyna