> For the complete documentation index, see [llms.txt](https://guide.cryosparc.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guide.cryosparc.com/setup-configuration-and-management/management-and-monitoring-4.7/cryosparcm-4.7.md). # cryosparcm reference (≤v4.7) {% hint style="warning" %} This page refers to CryoSPARC ≤v4.7. For v5.0+, please see [cryosparcm reference (v5.0+)](/setup-configuration-and-management/management-and-monitoring-v5.0/cryosparcm-reference-v5.0.md) {% endhint %} ## Access the command line utility, cryosparcm 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 [command-line](https://en.wikipedia.org/wiki/Command-line_interface) utility for all administrative, management and advanced usage tasks. To use it, log into the machine onto which [CryoSPARC was installed](/setup-configuration-and-management/how-to-download-install-and-configure/downloading-and-installing-cryosparc.md). Open a Terminal running a shell (such as `bash`) and enter any of the commands described below. ```bash cryosparcuser@emserver1:~$ cryosparcm status ---------------------------------------------------------------------------- CryoSPARC System master node installed at /home/cryosparcuser/sw/cryosparc_master Current cryoSPARC version: v4.3.1 ---------------------------------------------------------------------------- CryoSPARC process status: app RUNNING pid 1599310, uptime 0:30:11 app_api RUNNING pid 1599643, uptime 0:30:10 app_api_dev STOPPED Not started app_legacy STOPPED Not started app_legacy_dev STOPPED Not started command_core RUNNING pid 1593955, uptime 0:30:26 command_rtp RUNNING pid 1595620, uptime 0:30:16 command_vis RUNNING pid 1594923, uptime 0:30:17 database RUNNING pid 1593553, uptime 0:30:29 ---------------------------------------------------------------------------- License is valid ---------------------------------------------------------------------------- global config variables: export CRYOSPARC_LICENSE_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" export CRYOSPARC_MASTER_HOSTNAME=emserver1.internal export CRYOSPARC_DB_PATH="/home/cryosparcuser/sw/cryosparc_db_61561" export CRYOSPARC_BASE_PORT=61560 export CRYOSPARC_DB_CONNECTION_TIMEOUT_MS=20000 export CRYOSPARC_INSECURE=false export CRYOSPARC_DB_ENABLE_AUTH=true export CRYOSPARC_CLUSTER_JOB_MONITOR_INTERVAL=10 export CRYOSPARC_CLUSTER_JOB_MONITOR_MAX_RETRIES=1000000 export CRYOSPARC_PROJECT_DIR_PREFIX='CS-' export CRYOSPARC_DEVELOP=false export CRYOSPARC_CLICK_WRAP=true cryosparcuser@emserver1:~$ ``` {% hint style="info" %} For systems that do not support this, navigate to the `cryosparc_master` installation directory and run `./bin/cryosparcm` instead of `cryosparcm` {% endhint %} ## Instance Setup ### `cryosparcm update` See [**Software Updates**](/setup-configuration-and-management/software-updates.md) for details. {% content-ref url="/pages/-M7DHIJwDbQvhcKm7avb" %} [Software Updates and Patches](/setup-configuration-and-management/software-updates.md) {% endcontent-ref %} {% hint style="warning" %} This command can only be run by the UNIX user that owns the CryoSPARC installation directory. {% endhint %} ### `cryosparcm patch` Apply the latest patches available for your installed version of CryoSPARC without doing a full version update. Specify the `--help` flag to see full usage ``` $ cryosparcm patch --help usage: cryosparcm patch [-h] [-f] [-y] [--check] [--download] [--install] Download and apply cryoSPARC patches. Run cryosparcm patch to automatically install the latest patches on master and worker nodes optional arguments: -h, --help show this help message and exit -f, --force install latest patch again even if already installed -y, --yes confirm patch installation without prompt --check check to see if a patch is available --download download master and worker patches for manual installation --install manually install a downloaded patch file ``` 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. [See also `cryosparcw patch`](/setup-configuration-and-management/management-and-monitoring-4.7/cryosparcw-4.7.md#cryosparcw-patch) {% hint style="info" %} Some patches require restarting CryoSPARC. After running `cryosparcm patch`, when prompted restart with [`cryosparcm restart`](#cryosparcm-restart). {% endhint %} {% hint style="warning" %} This command can only be run by the UNIX user that owns the CryoSPARC installation directory. {% endhint %} ### `cryosparcm cluster` Configures cluster installation. See the [**Download and Installation**](/setup-configuration-and-management/how-to-download-install-and-configure/downloading-and-installing-cryosparc.md) page for details. {% content-ref url="/pages/-M7DHIJu6M1ubOlnm8Vp" %} [Downloading and Installing CryoSPARC](/setup-configuration-and-management/how-to-download-install-and-configure/downloading-and-installing-cryosparc.md) {% endcontent-ref %} Use with one of the following sub-commands. #### `cryosparcm cluster example ` Writes config and script template files to current working directory, `cluster_info.json` and `cluster_script.sh` respectively. Examples are available for [Portable Batch System](https://en.wikipedia.org/wiki/Portable_Batch_System) (`cryosparcm cluster example pbs`) and [SLURM](https://slurm.schedmd.com/documentation.html) (`cryosparcm cluster example slurm`) schedulers. Other systems are similar; run one of the two `cluster example` commands and modify the output files accordingly. #### `cryosparcm cluster dump ` Outputs the existing config and script to current working directory for the cluster with the given name. #### `cryosparcm cluster connect` Reads `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 ` Removes a cluster configuration from the scheduler. ### `cryosparcm test` Verifies 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](/setup-configuration-and-management/software-system-guides/guide-installation-testing-with-cryosparcm-test.md) 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 `** 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. ## Instance Status and Management The following commands are only allowed to be executed by `` (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: ![Error message shown when a core command is not executed on the master node](/files/-M7DHKOR70dnethQAE2N) You can mitigate errors temporarily by specifying the `CRYOSPARC_FORCE_HOSTNAME` variable just before calling the command: ```bash cryosparcuser@wrong.server:~$ CRYOSPARC_FORCE_HOSTNAME="true" cryosparcuser@wrong.server:~$ cryosparcm status ---------------------------------------------------------------------------- CryoSPARC System master node installed at /home/cryosparcuser/cryosparc/cryosparc_master ---------------------------------------------------------------------------- cryosparcm process status: ... ``` 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. ``` File: /home/cryosparcuser/cryosparc/cryosparc_master/config.sh export CRYOSPARC_LICENSE_ID="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" export CRYOSPARC_MASTER_HOSTNAME="uoft" export CRYOSPARC_DB_PATH="/home/cryosparcuser/cryosparc/cryosparc_master" export CRYOSPARC_BASE_PORT=61000 export CRYOSPARC_HOSTNAME_CHECK="uoft" ``` ### Available CryoSPARC Services * `app` * `app_api` * `app_legacy` * `command_core` * `command_rtp` * `command_vis` * `database` ### `cryosparcm status` Prints 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. {% hint style="warning" %} This command can only be run by the UNIX user that owns the CryoSPARC installation directory. {% endhint %} ### `cryosparcm start []` 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`. Providing an optional service name will only start that specific service. For a list of all available services, see [Available CryoSPARC Services](#undefined). {% hint style="warning" %} In v4.0.0, `app_legacy` (the original web application, formerly "`webapp`") is not started by default, but can be at any time. {% endhint %} {% hint style="warning" %} This command can only be run by the UNIX user that owns the CryoSPARC installation directory. {% endhint %} ### `cryosparcm stop []` 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. Providing an optional service name will only stop that specific service. For a list of all available services, see [Available CryoSPARC Services](#undefined). {% hint style="warning" %} This command can only be run by the UNIX user that owns the CryoSPARC installation directory. {% endhint %} ### `cryosparcm restart []` Equivalent to running `cryosparcm stop && cryosparcm start` Providing an optional service name will only restart that specific service. For a list of all available services, see [Available CryoSPARC Services](#undefined). 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 jobstatus` Show a summary of how many jobs are active. ### `cryosparcm backup` Backs 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. {% hint style="danger" %} 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. {% endhint %} 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. {% hint style="danger" %} CryoSPARC can be running when `cryosparcm backup` is run, but the backup will impact the performance of your running database. ([source](https://www.mongodb.com/docs/v3.6/tutorial/backup-and-restore-tools/#back-up-and-restore-with-mongodb-tools)). 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. {% endhint %} ```bash cryosparcm backup \ --dir=/path/to/backups \ --file=custombackupfile ``` ### `cryosparcm restore` Restore your database from a backup file (see [`cryosparcm backup`](#cryosparcm-backup)). {% hint style="danger" %} A 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. {% endhint %} {% hint style="info" %} CryoSPARC must be turned off before running this command. {% endhint %} {% hint style="info" %} The database directory (`CRYOSPARC_DB_PATH` found in `cryosparc_master/config.sh`) must exist and be empty before running this command. {% endhint %} ``` cryosparcm restore --file=/path/to/backups/backupfile ``` {% hint style="warning" %} This command can only be run by the UNIX user that owns the CryoSPARC installation directory. {% endhint %} ### `cryosparcm changeport ` Change CryoSPARC's base port to something else. Use the `--yes` or `-y` flag to proceed without confirmation. ``` cryosparcm changeport 40000 ``` {% hint style="warning" %} This command can only be run by the UNIX user that owns the CryoSPARC installation directory. {% endhint %} ### `cryosparcm checkdb` Ensure the database is running with the correct host configuration ### `cryosparcm fixdbport` Run this command after manually changing CryoSPARC's base port number to ensure the Mongo database registers the change. ### `cryosparcm licensestatus` Check 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](/setup-configuration-and-management/software-system-guides/guide-maintenance-mode-and-configurable-user-facing-messages.md) ### `cryosparcm test` Run `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](/setup-configuration-and-management/software-system-guides/guide-installation-testing-with-cryosparcm-test.md) ## Logs 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 ` Tails the output log of the master node process denoted by `` which can be one of the following: * `command_core` * `command_rtp` * `command_vis` * `database` * `app` * `app_legacy` * `app_api` For example ``` cryosparcm log command_core ``` 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 log command_core > command_core.log ``` To show only the last $$x$$ lines of the log, use `tail`. For example, to see the last 1000 lines of the log: ``` cryosparcm log command_core | tail -n 1000 ``` ### `cryosparcm filterlog ` Shows the output log of the master node process denoted by `` which can be one of the following: * `command_core` * `command_rtp` * `command_vis` * `database` * `app` * `app_legacy` * `app_api` For example ``` cryosparcm filterlog command_core ``` 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. #### Additional Arguments To see `cryosparcm filterlog` usage, run `cryosparcm filterlog -h`: ``` Usage: cryosparcm filterlog SERVICE cryosparcm filterlog [--days|-d N] [--date|-D YYYY-MM-DD] [--max_lines|-m MAX_LINES] [--name|-n NAME] [--func|-f FUNCTION] [--level|-l LEVEL] [--tail|-t] SERVICE Where SERVICE is one of: app app_legacy app_api command_core command_rtp command_vis database Some flags not available for all services. ``` 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 JXX` Shows 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 joblog P3 J123 ``` {% hint style="info" %} `joblog` shows the full `stdout` for the job, which is more comprehensive than the job log in the web interface and is more helpful for debugging. {% endhint %} To stop logging, save the full log or view only the last few log lines, see instructions for [`cryosparcm log`](#cryosparcm-log-less-than-process-greater-than) ### `cryosparcm eventlog PX JXX` Prints 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 snaplogs` Compresses all `.log` files in the `cryosparc_master/run` folder into a `.tgz` file inside `cryosparc_master/run`. ### `cryosparcm errorreport` Run `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](/setup-configuration-and-management/software-system-guides/guide-download-error-reports.md) ## User Management ### `cryosparcm listusers` Outputs a table of users registered with the system, including their names, email addresses and admin status. ### `cryosparcm createuser` Creates a new user account for log in through the web interface. Full use: ```bash cryosparcm createuser \ --email "" \ --username "" \ --firstname ""\ --lastname "" \ [--password ""] ``` {% hint style="info" %} If the`--password` argument is not specified, a silent input prompt is provided. {% endhint %} {% hint style="warning" %} This command can only be run by the UNIX user that owns the CryoSPARC installation directory. {% endhint %} ### `cryosparcm resetpassword` Resets the password for indicated user with the new `` provided. Full use: ```bash cryosparcm resetpassword \ --email "" \ [--password ""] ``` {% hint style="info" %} If the `--password` argument is not specified, a silent input prompt is provided. {% endhint %} {% hint style="warning" %} This command can only be run by the UNIX user that owns the CryoSPARC installation directory. {% endhint %} ### `cryosparcm updateuser` Updates a user profile to change the user name or set admin privileges. Full use: ```bash cryosparcm updateuser \ --email "" \ --username "" \ --firstname "" \ --lastname "" \ --admin "" \ [--password ""] ``` {% hint style="info" %} If the `--password` argument is not specified, a silent input prompt is provided. {% endhint %} `--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: {% content-ref url="/pages/-MNecrUQzW1CYEnJCepj" %} [Guide: User Management](/setup-configuration-and-management/software-system-guides/tutorial-user-management.md) {% endcontent-ref %} {% hint style="warning" %} This command can only be run by the UNIX user that owns the CryoSPARC installation directory. {% endhint %} ## Command-Line Interface ### `cryosparcm env` Prints 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. ``` eval $(cryosparcm env) ``` This may be used to, for example, run the [**Python**](https://www.python.org/) distribution that ships with CryoSPARC. ### `cryosparcm cli` Runs a command using with cryoSPARC's command-line interface ``` cryosparcm cli ``` See the full command reference {% content-ref url="/pages/-M7DHIJzq3PnUov4PO7G" %} [cryosparcm cli reference (≤v4.7)](/setup-configuration-and-management/management-and-monitoring-4.7/cli-4.7.md) {% endcontent-ref %} ### `cryosparcm icli` Runs an an interactive cryosparc shell that connects to the master processes. Use this to interactively run Python commands in the same environment as CryoSPARC. ![](/files/-M7DHKOWSMop88e2BjWb) {% content-ref url="/pages/-M7DHIJzq3PnUov4PO7G" %} [cryosparcm cli reference (≤v4.7)](/setup-configuration-and-management/management-and-monitoring-4.7/cli-4.7.md) {% endcontent-ref %} ### `cryosparcm rtpcli` Similar to [`cryosparcm cli`](/setup-configuration-and-management/management-and-monitoring-4.7/cryosparcw-4.7.md#cryosparcm-cli), but for running interactive commands with CryoSPARC Live. **Additional details coming soon.** See our guide on Managing a CryoSPARC Live Session from the CLI: {% embed url="" %} {% endembed %} ### `cryosparcm downloadtest` Download test data (subset of 20 movies from the EMPIAR-10025 dataset) to the current working directory for use with the [**T20S Introductory Tutorial**](/guides-for-v3/cryo-em-data-processing-in-cryosparc-introductory-tutorial.md#t-20-s-tutorial). ### `cryosparcm help` Prints a help message ### `cryosparcm mongo` Starts a [`mongo` **shell**](https://docs.mongodb.com/manual/mongo/) for CryoSPARC's local mongoDB instance. ### `cryosparcm call ` Execute a shell command in CryoSPARC's shell environment, such as Python. Equivalent to calling: `eval $(cryosparcm env)` followed by another shell command.