cryosparcm reference
How to use the cryosparcm utility for starting and stopping the CryoSPARC instance, checking status or logs, managing users and using CryoSPARC's command-line interface.
Last updated
How to use the cryosparcm utility for starting and stopping the CryoSPARC instance, checking status or logs, managing users and using CryoSPARC's command-line interface.
Last updated
The CryoSPARC master node hosts the web server and manages job resource allocation.
Workstations or master nodes with a cryosparc_master installation have access to cryosparcm, CryoSPARC's built-in utility for all administrative, management and advanced usage tasks.
To use it, log into the machine onto which . Open a Terminal running a shell (such as bash) and enter any of the commands described below.
cryosparcm updateThis command can only be run by the UNIX user that owns the CryoSPARC installation directory.
cryosparcm patchApply the latest patches available for your installed version of CryoSPARC without doing a full version update.
Specify the --help flag to see full usage
Frequently used commands:
cryosparcm patch: Automatically installs the latest patches on workstations or master node and connected workers. Not recommended for clusters: Use the --download and --install flags instead.
cryosparcm patch --force: Reinstalls the latest patches in case something went wrong with a previous attempt
cryosparcm patch --check: Shows information about the latest patches without installing
cryosparcm patch --download: Downloads the latest patches without installing them. Follow the resulting instructions to install the master and worker patches
cryosparcm patch --install: Run this command immediately after a --download to install the patch on the master node.
This command can only be run by the UNIX user that owns the CryoSPARC installation directory.
cryosparcm clusterUse with one of the following sub-commands.
cryosparcm cluster example <cluster_type>Writes config and script template files to current working directory, cluster_info.json and cluster_script.sh respectively.
cryosparcm cluster dump <name>Outputs the existing config and script to current working directory for the cluster with the given name.
cryosparcm cluster connectReads cluster_info.json and cluster_script.sh from the current directory. Connects a new or updates an existing cluster configuration using the name from cluster_info.json.
cryosparcm cluster remove <name>Removes a cluster configuration from the scheduler.
cryosparcm testVerifies the instance has been correctly installed by running several tests. Provides a report upon completion. For more information, see Guide: Installation Testing with cryosparcm test
Specify the --help flag to see full usage
cryosparcm test install
Tests the core components of CryoSPARC (HTTP connections, licensing, workers, etc.) that are required to start running jobs and provides information on the status of the CryoSPARC instance (e.g., which version is running, whether a patch is available, etc.).
cryosparcm test workers <project_uid>
Tests workers connected to CryoSPARC to ensure they can correctly run CryoSPARC jobs by testing if the worker can launch jobs, cache particles to an SSD (if an SSD is configured), and utilize the GPU correctly.
The following commands are only allowed to be executed by <cryosparcuser> (the user that installed CryoSPARC), and can only be executed on the master node. If these conditions are not met, you may see the following error:
You can mitigate errors temporarily by specifying the CRYOSPARC_FORCE_HOSTNAME variable just before calling the command:
If this error message is incorrect (the hostname specified in the error message is actually the same host, just a different identifier), you can set the hostname that the management script will use to compare by adding the variable CRYOSPARC_HOSTNAME_CHECK to cryosparc_master/config.sh. You can also set CRYOSPARC_FORCE_HOSTNAME in this file to permanently suppress this error.
app
app_api
app_legacy
command_core
command_rtp
command_vis
database
cryosparcm statusPrints out current status of the CryoSPARC master system, including the status of all individual processes (database, app, command_core, etc). Also prints out configuration environment variables.
This command can only be run by the UNIX user that owns the CryoSPARC installation directory.
cryosparcm start [<service name>]Starts the CryoSPARC instance if stopped, including the database, the command server, the web interface, etc.
All processes start in the background, including all jobs and the web interface; the command line may be closed after running start.
In v4.0.0, app_legacy (the original web application, formerly "webapp") is not started by default, but can be at any time.
This command can only be run by the UNIX user that owns the CryoSPARC installation directory.
cryosparcm stop [<service name>]Stops the CryoSPARC instance if running. This will gracefully kill all the master processes, and will cause any running jobs (potentially on other nodes) to fail.
This command can only be run by the UNIX user that owns the CryoSPARC installation directory.
cryosparcm restart [<service name>]Equivalent to running cryosparcm stop && cryosparcm start
Stops the CryoSPARC instance if running. This will gracefully kill all the master processes, and will cause any running jobs (potentially on other nodes) to fail.
cryosparcm jobstatusShow a summary of how many jobs are active.
cryosparcm backupBacks up the CryoSPARC MongoDB database using mongodump. By default, the function creates a folder named backup inside the database path specified by the CRYOSPARC_DB_PATH environment variable in cryosparc_master/config.sh (e.g., /u/cryosparcuser/cryosparc_db/backup) and saves the backup as an .archive file with the current date and time in its path (e.g., cryosparc_backup_2021_06_14_11h27.archive) inside this folder.
Do not allow the backup to fill up the filesystem on which the database is stored. If needed, specify a custom alternative path where the backup will be written.
To change the directory the backup will be written to, specify the --dir flag. To change the name of the backup file, specify the --file flag.
Moreover, and perhaps more importantly, once CryoSPARC projects or jobs are created, deleted, or otherwise modified during or after the backup, a database restored from the resulting backup file will no longer be compatible with the modified project directories.
cryosparcm restoreA database backup becomes outdated and incompatible with project directories as soon as CryoSPARC projects or jobs are created, deleted or modified following the the database backup. Do not restore an outdated database backup. Restoration of an outdated database backup and subsequent use with CryoSPARC is likely to corrupt CryoSPARC projects.
This command can only be run by the UNIX user that owns the CryoSPARC installation directory.
cryosparcm changeport <port>Change CryoSPARC's base port to something else. Use the --yes or -y flag to proceed without confirmation.
This command can only be run by the UNIX user that owns the CryoSPARC installation directory.
cryosparcm checkdbEnsure the database is running with the correct host configuration
cryosparcm fixdbportRun this command after manually changing CryoSPARC's base port number to ensure the Mongo database registers the change.
cryosparcm licensestatusCheck configured CryoSPARC license ID to see if there are any issues with verifying it.
cryosparcm maintenancemode [on|off|status]Stops queued jobs from running while allowing running jobs to finish. Can be used to facilitate a better user experience while CryoSPARC is undergoing maintenance, for example during restart, patch, or update. For more information, see Guide: Maintenance Mode and Configurable User Facing Messages
cryosparcm testRun cryosparcm test --help for usage information.
Test all components of a CryoSPARC instance to confirm it is working properly. For more information, see Guide: Installation Testing with cryosparcm test
The CryoSPARC system maintains several log files for its various processes that help with debugging any components of the CryoSPARC system that are not working.
cryosparcm log <process>Tails the output log of the master node process denoted by <process> which can be one of the following:
command_core
command_rtp
command_vis
database
app
app_legacy
app_api
For example
The log is live and automatically updates while the command-line remains open and new data is added to the log. To stop live updates and return to the shell, press control C on your keyboard, and then q.
To save the full log, redirect the output to a file
cryosparcm filterlog <process>Shows the output log of the master node process denoted by <process> which can be one of the following:
command_core
command_rtp
command_vis
database
app
app_legacy
app_api
For example
The log is live and automatically updates while the command-line remains open and new data is added to the log. To stop live updates and return to the shell, press control C on your keyboard.
To see cryosparcm filterlog usage, run cryosparcm filterlog -h:
Please note that only command_core, command_rtp and command_vis support the following arguments with the exception of database, which also supports the date filter.
--days|-d N
Show last N days worth of logs
--date|-D YYYY-MM-DD
Show only logs from the given date
--max_lines|-m MAX_LINES
the maximum number of lines to return
--name|-n NAME
Show only logs with the given log name as a prefix (before dots). For example: cryosparcm filterlog command_core -n COMMAND.SCHEDULER
--func|-f FUNCTION
Show only logs from the given log function. For example cryosparcm filterlog command_core -f get_gpu_info_run
--level|-l LEVEL
Show only logs with the given level. For example: cryosparcm filterlog command_core -l ERROR
--tail|-t
Will tail the log with the filters applied. To stop live updates and return to the shell, press control C.
cryosparcm joblog PX JXXShows a live output log for job JXX in project PX. Includes the standard input and error from the python process for the job.
For example, to show the output of Job 123 in Project 3, run the following
cryosparcm eventlog PX JXXPrints the text of the processing log for job JXX in project PX to stdout.
For example, to write text components of the processing log for CryoSPARC job J123 in project P3 to a file in the current working directory, run:
cryosparcm eventlog P3 J123 > P3_J123_events.log
cryosparcm snaplogsCompresses all .log files in the cryosparc_master/run folder into a .tgz file inside cryosparc_master/run.
cryosparcm errorreportRun cryosparcm errorreport --help for usage information.
Create a CryoSPARC error report which includes diagnostic information and CryoSPARC instance logs. For more information, see Guide: Download Error Reports
cryosparcm listusersOutputs a table of users registered with the system, including their names, email addresses and admin status.
cryosparcm createuserCreates a new user account for log in through the web interface. Full use:
This command can only be run by the UNIX user that owns the CryoSPARC installation directory.
cryosparcm resetpasswordResets the password for indicated user with the new <password> provided. Full use:
This command can only be run by the UNIX user that owns the CryoSPARC installation directory.
cryosparcm updateuserUpdates a user profile to change the user name or set admin privileges. Full use:
--email is required and can not be changed with this command.
--username, --firstname, --lastname are used for display and do not otherwise affect CryoSPARC function.
Other than for the first-created user account, new users do not have administrative privileges applied by default. Following creation of the first-created user account, other accounts can also be created through the user interface if preferred:
This command can only be run by the UNIX user that owns the CryoSPARC installation directory.
cryosparcm envPrints a list of environment variables for use in a command-line shell to replicate the exact environment used to when running CryoSPARC processes.
Run this command with eval to define the variables output by the env command.
cryosparcm cliRuns a command using with cryoSPARC's command-line interface
See the full command reference
cryosparcm icliRuns an an interactive cryosparc shell that connects to the master processes. Use this to interactively run Python commands in the same environment as CryoSPARC.
cryosparcm rtpcliAdditional details coming soon.
See our guide on Managing a CryoSPARC Live Session from the CLI:
cryosparcm downloadtestcryosparcm helpPrints a help message
cryosparcm mongocryosparcm call <command>Execute a shell command in CryoSPARC's shell environment, such as Python. Equivalent to calling:
eval $(cryosparcm env) followed by another shell command.
See for details.
Some patches require restarting CryoSPARC. After running cryosparcm patch, when prompted restart with .
Configures cluster installation. See the page for details.
Examples are available for (cryosparcm cluster example pbs) and (cryosparcm cluster example slurm) schedulers. Other systems are similar; run one of the two cluster example commands and modify the output files accordingly.
Providing an optional service name will only start that specific service. For a list of all available services, see .
Providing an optional service name will only stop that specific service. For a list of all available services, see .
Providing an optional service name will only restart that specific service. For a list of all available services, see .
CryoSPARC can be running when cryosparcm backup is run, but the backup will impact the performance of your running database. ().
Restore your database from a backup file (see ).
To show only the last lines of the log, use tail. For example, to see the last 1000 lines of the log:
To stop logging, save the full log or view only the last few log lines, see instructions for
This may be used to, for example, run the distribution that ships with CryoSPARC.
Similar to , but for running interactive commands with CryoSPARC Live.
Download test data (subset of 20 movies from the EMPIAR-10025 dataset) to the current working directory for use with the .
Starts a for CryoSPARC's local mongoDB instance.
