> 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-v5.0/cryosparcm-reference-v5.0.md).

# cryosparcm reference (v5.0+)

## Access the CryoSPARC 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](https://guide.cryosparc.com/setup-configuration-and-management/how-to-download-install-and-configure/downloading-and-installing-cryosparc). Open a Terminal running a shell (such as `bash`) and enter any of the commands described below.

{% hint style="info" %}
If CryoSPARC was installed without adding CryoSPARC’s `bin` path to the shell’s path configuration, navigate to the `cryosparc_master` installation directory and run `./bin/cryosparcm` instead of `cryosparcm`.
{% endhint %}

For help with a specific command, run:

```bash
cryosparcm COMMAND --help
```

For example, for help starting CryoSPARC, run:

```bash
cryosparcm start --help
```

### `cryosparcm`

**Usage**:

```bash
$ cryosparcm [OPTIONS] COMMAND [ARGS]...
```

**Options**:

* `--install-completion`: Install completion for the current shell.
* `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
* `--help`: Show this message and exit.

All available `cryosparcm` commands are listed and documented in the sections below.

## Instance Status and Management

Always run instance management commands in this section from the UNIX user account that owns the CryoSPARC installation, and always on the same machine on the network that `cryosparc_master` was installed on. If these conditions are not met, you may see the following message:

```bash
$ cryosparcm status
────────────────────────────────────────────────────────────────────────────────
CryoSPARC System master node installed at
/home/cryosparcuser/cryosparc_master
Current CryoSPARC version: develop
────────────────────────────────────────────────────────────────────────────────

✕ UnauthorizedException: This command must run on the CryoSPARC master host, but
there is a mismatch between the $CRYOSPARC_MASTER_HOSTNAME definition
(example.edu) and the configured hostname of this host (gpu.example.xyz).

If, and only if, the command ran on the CryoSPARC master host, but the host is
configured with a different hostname, consider the appropriate intervention for
your circumstances:

 1 Ensure $CRYOSPARC_MASTER_HOSTNAME and the output of command hostname -f
   match. CRYOSPARC_MASTER_HOSTNAME may be defined inside
   cryosparc_master/config.sh. Restart CryoSPARC after this change.
 2 Or: re-run this command with the environment variable
   CRYOSPARC_FORCE_HOSTNAME="true". This setting bypasses an important safety
   check and may disrupt CryoSPARC function if used inappropriately.
```

You can temporarily force `cryosparcm` to ignore the current hostname or user by specifying the `CRYOSPARC_FORCE_HOSTNAME` or `CRYOSPARC_FORCE_USER` variables just before calling the command:

```bash
$ CRYOSPARC_FORCE_HOSTNAME=true cryosparcm status
```

If you see the above error message, but the hostname it reports is incorrect (i.e., the hostname specified in the error message is actually the same host, just a different identifier), you can set `CRYOSPARC_MASTER_HOSTNAME` in `cryosparc_master/config.sh` to the correct hostname. You can also set `CRYOSPARC_FORCE_HOSTNAME` or `CRYOSPARC_FORCE_USER` in this file to permanently suppress this message.

### `cryosparcm status`

Show CryoSPARC system status, including the status of all CryoSPARC processes (`database`, `app`, `api`, etc.) and show configuration environment variables.

**Usage**:

```
$ cryosparcm status [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

### `cryosparcm version`

Show CryoSPARC version.

**Usage**:

```bash
$ cryosparcm version [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

### `cryosparcm start`

Start CryoSPARC or one of its services.

All processes start in the background, including all services and the web interface; processes will continue running after the terminal is closed. To stop, use `cryosparcm stop`. Provide an optional service name to only start that specific service.

**Usage**:

```
$ cryosparcm start [OPTIONS] [SERVICE]:[app|database|cache|api|scheduler|command_vis|app_api]
```

**Arguments**:

* `[SERVICE]:[app|database|cache|api|scheduler|command_vis|app_api]`

**Options**:

* `--systemd / --no-systemd`: \[default: no-systemd]
* `--startup / --no-startup`: \[default: startup]
* `--app / --no-app`: \[default: app]
* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

### `cryosparcm stop`

Stop CryoSPARC or one of its services.

Provide an optional service name to only start that specific service.

**Usage**:

```
$ cryosparcm stop [OPTIONS] [SERVICE]:[app|database|cache|api|scheduler|command_vis|app_api]
```

**Arguments**:

* `[SERVICE]:[app|database|cache|api|scheduler|command_vis|app_api]`

**Options**:

* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

### `cryosparcm restart`

Stop and start CryoSPARC or one of its services.

**Usage**:

```
$ cryosparcm restart [OPTIONS] [SERVICE]:[app|database|cache|api|scheduler|command_vis|app_api]
```

**Arguments**:

* `[SERVICE]:[app|database|cache|api|scheduler|command_vis|app_api]`

**Options**:

* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

### `cryosparcm maintenancemode`

Enable, disable or check maintenance mode. While enabled, prevents queued jobs from running while allowing running jobs to finish. Improves user experience user experience while CryoSPARC is undergoing maintenance, for example during restart, patch, or update.

See [Guide: Maintenance Mode and Configurable User Facing Messages](https://guide.cryosparc.com/setup-configuration-and-management/software-system-guides/guide-maintenance-mode-and-configurable-user-facing-messages) for full details.

**Usage**:

```
$ cryosparcm maintenancemode [OPTIONS] COMMAND:{status|on|off}
```

**Arguments**:

* `COMMAND:{status|on|off}`: \[required]

**Options**:

* `--help`: Show this message and exit.

### `cryosparcm resources`

Print a formatted table of available scheduler targets and their properties.

**Usage**:

```
$ cryosparcm resources [OPTIONS] [LANE_NAME]
```

**Arguments**:

* `[LANE_NAME]`: Only show target information for a specific lane

**Options**:

* `--help`: Show this message and exit.

### `cryosparcm changeport`

Change instance base port.

**Usage**:

```
$ cryosparcm changeport [OPTIONS] PORT
```

**Arguments**:

* `PORT`: \[required]

**Options**:

* `-y, --yes`: Confirm without prompting
* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

### `cryosparcm asset-stats`

Show asset storage statistics.

**Usage**:

```
$ cryosparcm asset-stats [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

### `cryosparcm recover`

Restore instance configuration and recover projects from an exported instance configuration file. Should only run when the database has no projects. For full instructions, see [Instance Recovery](/setup-configuration-and-management/software-system-guides/guide-instance-recovery-v5.0.md).

**Usage**:

```
$ cryosparcm recover [OPTIONS]
```

**Options**:

* `-f, --file FILE`: Path to input file \[required]
* `--claim-project-ownership`: Take over projects locked to other instances
* `-y, --yes`: Confirm without prompting
* `--help`: Show this message and exit.

## Instance Setup

### `cryosparcm update`

Install the latest CryoSPARC update. See [**Software Updates**](https://guide.cryosparc.com/setup-configuration-and-management/software-updates) for full details.

**Usage**:

```
$ cryosparcm update [OPTIONS]
```

**Options**:

* `--version TEXT`: Version to update to \[default: latest]
* `--list`: List available versions
* `--check`: Check for update
* `--download`: Download only
* `--install`: Install previous download
* `--force`: Force install the latest or specified version
* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

### `cryosparcm patch`

Download and install the latest patch for this version.

**Usage**:

```
$ cryosparcm patch [OPTIONS] [PATCH_NAME]
```

**Arguments**:

* `[PATCH_NAME]`: Name of patch to download

**Options**:

* `--check`: Check to see if a patch is available
* `--download`: Download patches for manual installation
* `--install`: Manually install a downloaded patch file
* `-f, --force`: Force install or re-install latest patch
* `-y, --yes`: Confirm patch installation without prompt
* `--help`: Show this message and exit.

Frequently used commands:

* `cryosparcm patch`: Automatically install 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`: Reinstall the latest patches in case something went wrong with a previous attempt
* `cryosparcm patch --check`: Show information about the latest patches without installing
* `cryosparcm patch --download`: Download 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.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

### `cryosparcm worker`

Worker management commands.

{% hint style="warning" %}
Ensure CryoSPARC is running before running worker management commands.
{% endhint %}

**Usage**:

```
$ cryosparcm worker [OPTIONS] COMMAND [ARGS]...
```

**Options**:

* `--help`: Show this message and exit.

**Commands**:

* `update`: Install a cryosparc worker update on all connected workers.
* `patch`: Install a cryosparc worker patch on all connected workers.
* `connect`: Connect a worker node that jobs can be scheduled on.
* `disconnect`: Remove a worker node from the scheduler.

#### `cryosparcm worker update`

Install a cryosparc worker update on all workers or the given worker.

**Usage**:

**Arguments**:

* `[WORKER]`: Target name. Applies to all targets if not specified

**Options**:

* `--file FILE`: \[default: cryosparc\_worker.tar.gz]
* `--force`
* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

#### `cryosparcm worker patch`

Install a cryosparc worker patch on all workers or the given worker.

**Usage**:

```
$ cryosparcm worker patch [OPTIONS] [WORKER]

```

**Arguments**:

* `[WORKER]`: Target name. Applies to all targets if not specified

**Options**:

* `--file FILE`: \[default: cryosparc\_worker\_patch.tar.gz]
* `--force`
* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

#### `cryosparcm worker connect`

Connect a worker node that jobs can be scheduled on, or update an existing worker configuration. Similar to [cryosparcw reference (v5.0+)](/setup-configuration-and-management/management-and-monitoring-v5.0/cryosparcw-reference-v5.0.md#cryosparcw-connect).

**Usage**:

```
$ cryosparcm worker connect [OPTIONS]
```

**Options**:

* `--path TEXT`: Path to cryosparc\_worker folder \[required]
* `--worker TEXT`: Name of worker. Defaults to $(hostname) if not specified.
* `--lane TEXT`: Scheduler lane for worker (create if does not exist). \[default: default]
* `--sshstr TEXT`: SSH login string to access worker, required if the worker's hostname or UNIX user differs when connecting from master, or to specify additional SSH flags. Defaults to "$(whoami)@worker".
* `--cpus INTEGER RANGE`: Number of CPU cores to enable for jobs. Enable all cores if not specified. \[x>=1]
* `--rams INTEGER RANGE`: Number of 8GiB RAM slots to enable for jobs. Enable all RAM if not specified. \[x>=1]
* `--gpus TEXT`: Comma-separated list of GPU device IDs, e.g., '0,1,2'. Selects all GPUs if not specified. Cannot be specified with --no-gpu.
* `--gpu / --no-gpu`: Do not attempt to select any GPUs. Don't specify both --no-gpu and --gpus flag. \[default: gpu]
* `--ssdpath TEXT`: Local SSD scratch path. Strongly recommended.
* `--ssdquota INTEGER`: Maximum amount of SSD space to use for caching, in megabytes (MB).
* `--ssdreserve INTEGER`: Minimum amount free space to leave on the SSD, in megabytes (MB). \[default: 10000]
* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

#### `cryosparcm worker disconnect`

Remove a worker node from the scheduler.

**Usage**:

```
$ cryosparcm worker disconnect [OPTIONS]
```

**Options**:

* `--worker TEXT`: Name of worker. Defaults to $(hostname) if not specified. \[required]
* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

### `cryosparcm cluster`

Cluster management commands. See the [Download and Installation](https://guide.cryosparc.com/setup-configuration-and-management/how-to-download-install-and-configure/downloading-and-installing-cryosparc) page for full details.

{% hint style="warning" %}
Ensure CryoSPARC is running before running cluster management commands.
{% endhint %}

**Usage**:

```
$ cryosparcm cluster [OPTIONS] COMMAND [ARGS]...
```

**Options**:

* `--help`: Show this message and exit.

**Commands**:

* `connect`: Create or update a cluster with...
* `dump`: Write cluster configuration and script to...
* `validate`
* `remove`: Remove a cluster from the scheduler.
* `example`: Write example cluster configuration and...

#### `cryosparcm cluster example`

Write example cluster configuration (`cluster_info.json`) and script (`cluster_script.sh`) to a directory.

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.

**Usage**:

```
$ cryosparcm cluster example [OPTIONS] TYPE:{pbs|slurm}
```

**Arguments**:

* `TYPE:{pbs|slurm}`: Any cluster scheduler is supported but may require a custom submission script. \[required]

**Options**:

* `-o, --output-dir DIRECTORY`: Path to output directory \[default: .]
* `--help`: Show this message and exit.

#### `cryosparcm cluster connect`

Create or update a cluster with `cluster_info.json` and `cluster_script.sh`.

**Usage**:

```
$ cryosparcm cluster connect [OPTIONS]
```

**Options**:

* `--info FILE`: \[default: cluster\_info.json]
* `--script FILE`: \[default: cluster\_script.sh]
* `--help`: Show this message and exit.

#### `cryosparcm cluster dump`

Write cluster configuration and script to a directory.

**Usage**:

```
$ cryosparcm cluster dump [OPTIONS] NAME
```

**Arguments**:

* `NAME`: Cluster target name \[required]

**Options**:

* `o, --output-dir DIRECTORY`: Path to output directory \[default: .]
* `--help`: Show this message and exit.

#### `cryosparcm cluster remove`

Remove a cluster from the scheduler.

**Usage**:

```
$ cryosparcm cluster remove [OPTIONS] NAME
```

**Arguments**:

* `NAME`: Cluster target name \[required]

**Options**:

* `--help`: Show this message and exit.

### `cryosparcm deps`

Install Python and external dependencies. Specify `--force` to install even if they haven't changed.

**Usage**:

```
$ cryosparcm deps [OPTIONS]
```

**Options**:

* `--force`
* `--help`: Show this message and exit.

### `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](https://guide.cryosparc.com/setup-configuration-and-management/software-system-guides/guide-installation-testing-with-cryosparcm-test).

{% hint style="warning" %}
Ensure CryoSPARC is running before running worker management commands.
{% endhint %}

**Usage**:

```
$ cryosparcm test [OPTIONS] COMMAND [ARGS]...
```

**Options**:

* `--help`: Show this message and exit.

**Commands**:

* `license`: Verify that your CryoSPARC license is valid
* `install`: Test all installation components
* `i`: Alias for install
* `workers`: Test worker installation
* `w`: Alias for workers

#### `cryosparcm test license`

Verify that your CryoSPARC license is valid and that CryoSPARC can verify job runs with the license server at [get.cryosparc.com](http://get.cryosparc.com/).

**Usage**:

```
$ cryosparcm test license [OPTIONS]
```

**Options**:

* `-l, --long`
* `--help`: Show this message and exit.

#### `cryosparcm test install`

Tests the core installation components of CryoSPARC (HTTP connections, licensing, workers, etc.) that are required to start running jobs. Provides information on the status of the CryoSPARC instance (e.g., which version is running, whether a patch is available, etc.).

**Usage**:

```
$ cryosparcm test install [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

#### `cryosparcm test i`

Alias for `cryosparcm test install`

#### `cryosparcm test workers`

Test workers by running validation jobs in the specified project.

**Usage**:

```
$ cryosparcm test workers [OPTIONS] PROJECT
```

**Arguments**:

* `PROJECT`: \[required]

**Options**:

* `--test [all|launch|ssd|gpu]`: Specify either the launch, ssd or gpu test \[required]
* `-t, --target TEXT`: Specify one or more targets to run tests on, tests all if not specified
* `--test-pytorch / --no-test-pytorch`: Test if worker(s) can launch PyTorch jobs on all enabled GPUs \[default: no-test-pytorch]
* `--help`: Show this message and exit.

#### `cryosparcm test w`

Alias for `cryosparcm test workers`

## Logs

### `cryosparcm log`

Show a service output log from the most recent entries. The log is live-updated while the command-line remains open and new data is added to the log. To stop live updates and return to the shell, press `ctrl C` on your keyboard followed by `q`.

**Usage**:

```
$ cryosparcm log [OPTIONS] SERVICE:{app|database|cache|api|scheduler|command_vis|app_api|supervisord}
```

**Arguments**:

* `SERVICE:{app|database|cache|api|scheduler|command_vis|app_api|supervisord}`: \[required]

**Options**:

* `--help`: Show this message and exit.

To save the full log, redirect the output to a file. Example:

```bash
cryosparcm log api > api.log
```

To show only the last x*x* lines of the log, pipe to `tail`. For example, to see the last 1000 lines of the log:

Copy

```
cryosparcm log api | tail -n 1000
```

### `cryosparcm filterlog`

Show a filtered service output log.

**Usage**:

```
$ cryosparcm filterlog [OPTIONS] SERVICE:{app|database|cache|api|scheduler|command_vis|app_api|supervisord}

```

**Arguments**:

* `SERVICE:{app|database|cache|api|scheduler|command_vis|app_api|supervisord}`: \[required]

**Options**:

* `-d, --days INTEGER RANGE`: Show logs within previous N days \[default: 30; x>=0]
* `-D, --date [%Y-%m-%d]`: Show logs on date
* `-m, --max-lines INTEGER RANGE`: Max lines to show \[x>=0]
* `-t, --tail`: Continuously follow this log
* `--help`: Show this message and exit.

Note that only `database`, `api`, `scheduler` and `command_vis` services support date and days filters.

### `cryosparcm snaplogs`

Create an archive with all current master service logs.

**Usage**:

```
$ cryosparcm snaplogs [OPTIONS]
```

**Options**:

* `-o, --output-dir DIRECTORY`: Path to output directory \[default: .]
* `--help`: Show this message and exit.

### `cryosparcm errorreport`

Generate a diagnostic information bundle. For more information, see [Guide: Download Error Reports](https://guide.cryosparc.com/setup-configuration-and-management/software-system-guides/guide-download-error-reports).

**Usage**:

```
$ cryosparcm errorreport [OPTIONS]
```

**Options**:

* `-o, --output-dir DIRECTORY`: Path to output directory \[default: .]
* `-d, --days INTEGER RANGE`: Show logs within previous N days \[default: 30; x>=0]
* `-D, --date [%Y-%m-%d]`: Show logs on date
* `-m, --max-lines INTEGER RANGE`: Max lines to show \[x>=0]
* `--offline / --no-offline`: Skip database and worker data \[default: no-offline]
* `--skip-workers / --no-skip-workers`: Skip worker data \[default: no-skip-workers]
* `--help`: Show this message and exit.

### `cryosparcm get-workspace-report`

Download HTML workspace report from the CryoSPARC app.

**Usage**:

```
$ cryosparcm get-workspace-report [OPTIONS]
```

**Options**:

* `--project TEXT`: \[required]
* `--workspace TEXT`: \[required]
* `-o, --path PATH`: Path to output file or directory \[default: .]
* `--help`: Show this message and exit.

## User Management

Functions provided by these commands are also available from the web interface. For more details, see the [Admin Panel](https://guide.cryosparc.com/application-guide-v4.0+/admin-panel#user-management) guide.

### `cryosparcm user`

User management commands.

**Usage**:

```
$ cryosparcm user [OPTIONS] COMMAND [ARGS]...
```

**Options**:

* `--help`: Show this message and exit.

**Commands**:

* `list`: Show a table of available user accounts
* `exists`: Check if user exists
* `create`: Create a new user account
* `update`: Update user account information
* `resetpassword`: Reset a user account's password

#### `cryosparcm user list`

Show a table of available user accounts, including their names, email address and admin status.

**Usage**:

```
$ cryosparcm user list [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

#### `cryosparcm user exists`

Check if user exists. Command exits with status 0 if user exists, 1 otherwise. Shows an “exists” or “does not exist” message in either case.

**Usage**:

```
$ cryosparcm user exists [OPTIONS]
```

**Options**:

* `--email TEXT`: Email \[required]
* `--help`: Show this message and exit.

#### `cryosparcm user create`

Create a new user account. Call without arguments to create interactively.

**Usage**:

```
$ cryosparcm user create [OPTIONS]
```

**Options**:

* `--email TEXT`: Login email \[required]
* `--password TEXT`: Password \[required]
* `--username TEXT`: User name \[required]
* `--firstname TEXT`: First or given name \[required]
* `--lastname TEXT`: Last or surname \[required]
* `--role [user|admin]`: User role \[default: user]
* `--help`: Show this message and exit.

\<aside> 💡

If any required options are not specified, an input prompt will be provided.

\</aside>

#### `cryosparcm user update`

Update user account information and access, providing the email and password to verify. To change the password, use `cryosparcm users resetpassword`. Note that the user's email cannot be changed with this command.

**Usage**:

```
$ cryosparcm user update [OPTIONS]
```

**Options**:

* `--email TEXT`: Email \[required]
* `--password TEXT`: Password \[required]
* `--username TEXT`: New user name
* `--firstname TEXT`: New first or given name
* `--lastname TEXT`: New last or surname
* `--role [user|admin]`: New user role
* `--help`: Show this message and exit.

\<aside> 💡

If any required options are not specified, an input prompt will be provided.

\</aside>

Other than for the first user account created, new users do not have administrative privileges by default. After creating the first user account, other accounts can also be created [through the user interface](https://guide.cryosparc.com/application-guide-v4.0+/admin-panel#user-management) if preferred.

#### `cryosparcm user resetpassword`

Reset a user account's password.

**Usage**:

```
$ cryosparcm user resetpassword [OPTIONS]
```

**Options**:

* `--email TEXT`: Email \[required]
* `--password TEXT`: Password \[required]
* `--help`: Show this message and exit.

{% hint style="warning" %}
If any required options are not specified, an input prompt will be provided.
{% endhint %}

## Job Management

### `cryosparcm job`

Job management commands.

**Usage**:

```
$ cryosparcm job [OPTIONS] COMMAND [ARGS]...
```

**Options**:

* `--help`: Show this message and exit.

**Commands**:

* `status`: Show a summary of queued and active jobs
* `queue`: Queue a job
* `clear`: Clear a job
* `kill`: Kill a job
* `log`: Show job standard output and error log
* `events`: Show job event log

#### `cryosparcm job status`

Show a summary of queued and active jobs.

**Usage**:

```
$ cryosparcm job status [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

#### `cryosparcm job queue`

Queue a job. Specify either `--lane` or `--hostname`, except for interactive jobs. One or more `--gpu` options may be specified with `--hostname`.

**Usage**:

```
$ cryosparcm job queue [OPTIONS] PROJECT_UID JOB_UID
```

**Arguments**:

* `PROJECT_UID`: \[required]
* `JOB_UID`: \[required]

**Options**:

* `-l, --lane TEXT`: Scheduler lane to queue to
* `-h, --hostname TEXT`: Worker node to queue to
* `-g, --gpu INTEGER`: Specify one or more GPUs to queue to, `--hostname` must also be specified
* `--check-inputs-ready / --no-check-inputs-ready`: If disabled, job will run even if parent input jobs are incomplete \[default: check-inputs-ready]
* `--help`: Show this message and exit.

#### `cryosparcm job clear`

Clear a job.

**Usage**:

```
$ cryosparcm job clear [OPTIONS] PROJECT_UID JOB_UID
```

**Arguments**:

* `PROJECT_UID`: \[required]
* `JOB_UID`: \[required]

**Options**:

* `--help`: Show this message and exit.

#### `cryosparcm job kill`

Kill a job by its project UID and job UID.

**Usage**:

```
$ cryosparcm job kill [OPTIONS] PROJECT_UID JOB_UID
```

**Arguments**:

* `PROJECT_UID`: \[required]
* `JOB_UID`: \[required]

**Options**:

* `--help`: Show this message and exit.

#### `cryosparcm job log`

Show job standard output and error log.

**Usage**:

```
$ cryosparcm job log [OPTIONS] PROJECT_UID JOB_UID
```

**Arguments**:

* `PROJECT_UID`: \[required]
* `JOB_UID`: \[required]

**Options**:

* `--help`: Show this message and exit.

#### `cryosparcm job events`

Show job event log.

**Usage**:

```
$ cryosparcm job events [OPTIONS] PROJECT_UID JOB_UID
```

**Arguments**:

* `PROJECT_UID`: \[required]
* `JOB_UID`: \[required]

**Options**:

* `-c, --checkpoint INTEGER`: Show events from this checkpoint up until the next one. Shows all events if not provided. Specify -1 to show everything after the last checkpoint.
* `--help`: Show this message and exit.

## Database Management

Always run instance management commands in this section from the UNIX user account that owns the CryoSPARC installation, and always on the same machine on the network that `cryosparc_master` was installed on.

{% hint style="danger" %}
Note when using `cryosparcm database backup` and `cryosparcm database restore` commands:

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.

Use the `cryosparcm recover` command instead of the `backup`/`restore` commands to avoid this issue. See [Guide: Instance Recovery (v5.0+)](/setup-configuration-and-management/software-system-guides/guide-instance-recovery-v5.0.md) for details.
{% endhint %}

### `cryosparcm database`

Database management commands.

**Usage**:

```
$ cryosparcm database [OPTIONS] COMMAND [ARGS]...
```

**Options**:

* `--help`: Show this message and exit.

**Commands**:

* `check`: Check that the database is running correctly.
* `configure`: Prepare the database for running.
* `fixport`: Update expected database port.
* `backup`: Make a backup copy of the database.
* `restore`: Restore the database from a backup file.
* `compact`: Attempt to reduce database size.
* `export`: Export the contents of the database.
* `import`: Import a collection from an exported .json file
* `export-instance-config`: Export instance configuration and project information.
* `import-instance-config`: Import instance configuration from an exported file.

#### `cryosparcm database check`

Check that the database is running with the correct host configuration.

**Usage**:

```
$ cryosparcm database check [OPTIONS]
```

**Options**:

* `--quiet / --no-quiet`: \[default: no-quiet]
* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

#### `cryosparcm database configure`

Prepare the database for running. Automatically runs during `start`, manual invocation not typically required.

**Usage**:

```
$ cryosparcm database configure [OPTIONS]
```

**Options**:

* `-v, --verbose`
* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

#### `cryosparcm database fixport`

Update expected database port so that it matches the configured port following a change to `CRYOSPARC_BASE_PORT` in [config.sh](http://config.sh).

**Usage**:

```
$ cryosparcm database fixport [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

#### `cryosparcm database backup`

Make a backup copy of the database with `mongodump`.

By default, and saves the backup as an `.archive` file to the current working directory, with the current date and time in in the filename, e.g., `cryosparc_backup_2021_06_14_11h27.archive`

{% hint style="warning" %}
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 %}

**Usage**:

```
$ cryosparcm database backup [OPTIONS]
```

**Options**:

* `-o, --output PATH`: Path to output file or directory \[default: .]
* `-c, --collection TEXT`
* `--help`: Show this message and exit.

{% hint style="danger" %}
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.

Use the `cryosparcm recover` command instead of the `backup`/`restore` commands to avoid this issue. See [Guide: Instance Recovery (v5.0+)](/setup-configuration-and-management/software-system-guides/guide-instance-recovery-v5.0.md) for details.
{% endhint %}

{% hint style="warning" %}
CryoSPARC can be running when `cryosparcm database 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)).
{% endhint %}

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

#### `cryosparcm database restore`

Restore the database from a backup file.

{% 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 a 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.

Use the `cryosparcm recover` command instead of the `backup`/`restore` commands to avoid this issue. See [Guide: Instance Recovery (v5.0+)](/setup-configuration-and-management/software-system-guides/guide-instance-recovery-v5.0.md) for details.
{% endhint %}

{% hint style="warning" %}
CryoSPARC must be [installed](https://guide.cryosparc.com/setup-configuration-and-management/how-to-download-install-and-configure) and but not started before running this command.
{% endhint %}

**Usage**:

```
$ cryosparcm database restore [OPTIONS]
```

**Options**:

* `-f, --file FILE`: Path to input file \[required]
* `-c, --collection TEXT`
* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

#### `cryosparcm database compact`

Attempt to reduce database size.

**Usage**:

```
$ cryosparcm database compact [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

#### `cryosparcm database export`

Export the contents of a database collection to a .json file.

**Usage**:

```
$ cryosparcm database export [OPTIONS] COLLECTION_NAME
```

**Arguments**:

* `COLLECTION_NAME`: \[required]

**Options**:

* `-o, --output-dir DIRECTORY`: Path to output directory \[default: .]
* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

#### `cryosparcm database import`

Import a collection from an exported .json file. Overwrites existing data in that collection.

**Usage**:

```
$ cryosparcm database import [OPTIONS] COLLECTION_NAME
```

**Arguments**:

* `COLLECTION_NAME`: \[required]

**Options**:

* `-f, --file FILE`: Path to input file \[required]
* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

#### `cryosparcm database export-instance-config`

Export instance configuration and project information to a .tar file.

**Usage**:

```
$ cryosparcm database export-instance-config [OPTIONS]
```

**Options**:

* `-o, --output-dir DIRECTORY`: Path to output directory \[default: .]
* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

#### `cryosparcm database import-instance-config`

Imports instance configuration from an exported instance configuration .tar file.

**Usage**:

```
$ cryosparcm database import-instance-config [OPTIONS]
```

**Options**:

* `-f, --file FILE`: Path to input file \[required]
* `-y, --yes`: Confirm without prompting
* `--help`: Show this message and exit.

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

## Command Line Utilities

### `cryosparcm env`

Export environment variables used by CryoSPARC.

**Usage**:

```
$ cryosparcm env [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

Run this command with `eval` to define the variables output by the `env` command.

```bash
eval $(cryosparcm env)
```

### `cryosparcm call`

Run any command with the CryoSPARC environment. For example:

```bash
cryosparcm call python -c "import sys; print(sys.path)"
```

**Usage**:

```
$ cryosparcm call [COMMAND] [ARGS]...
```

Equivalent to running `eval $(cryosparcm env)` followed by the command.

### `cryosparcm python`

Run python command with the CryoSPARC environment. For example:

```bash
cryosparcm python -c "import sys; print(sys.path)"
```

**Usage**:

```
$ cryosparcm python [OPTIONS] [ARGS]...
```

### `cryosparcm ipython`

Run an interactive python shell with the CryoSPARC environment.

**Usage**:

```
$ cryosparcm ipython [OPTIONS]
```

### `cryosparcm cli`

Interact with CryoSPARC from the command line with Python expressions. See cryosparcm cli reference for full details.

**Usage**:

```
$ cryosparcm cli [OPTIONS] EXPRESSION
```

**Arguments**:

* `EXPRESSION`: \[required] Python expression

**Options**:

* `--help`: Show this message and exit.

### `cryosparcm icli`

Interact with CryoSPARC from an ipython shell. Can use `api` object in Python commands. See cryosparcm cli reference for full details.

**Usage**:

```
$ cryosparcm icli [OPTIONS] [ARGS]...
```

### `cryosparcm downloadtest`

Download a test dataset. For use with the [T20S Introductory Tutorial](https://guide.cryosparc.com/guides-for-v3/cryo-em-data-processing-in-cryosparc-introductory-tutorial#t-20-s-tutorial) or Installation Testing or Performance benchmarking.

**Usage**:

```
$ cryosparcm downloadtest [OPTIONS]
```

**Options**:

* `-o, --output-dir DIRECTORY`: Path to output directory \[default: .]
* `--dataset TEXT`: Which dataset to download. One of '10025', '10305', or 'PERFORMANCE\_BENCHMARK\_DATA' \[default: 10025]
* `--help`: Show this message and exit.

### `cryosparcm mongo`

Start a mongo [shell](https://docs.mongodb.com/manual/mongo/) for CryoSPARC’s local MongoDB database service.

**Usage**:

```
$ cryosparcm mongo [OPTIONS] [ARGS]...
```

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

### `cryosparcm redis`

Start a [redis-cli](https://redis.io/docs/latest/develop/tools/cli/) prompt for command line access to the Redis cache service.

**Usage**:

```
$ cryosparcm redis [OPTIONS] [ARGS]...
```

{% hint style="warning" %}
**Always run this command from the same host and UNIX user account originally used to install CryoSPARC.**
{% endhint %}

## Deprecated Commands

These commands were present in CryoSPARC v4 and remain in CryoSPARC v5 but should no longer be used; instead, the corresponding commands above should be used.

#### `cryosparcm checkdb` (Deprecated)

Use [`cryosparcm database check`](#cryosparcm-database-check) instead.

**Usage**:

```
$ cryosparcm checkdb [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

#### `cryosparcm configuredb` (Deprecated)

Use [`cryosparcm database configure`](#cryosparcm-database-configure) instead.

**Usage**:

```
$ cryosparcm configuredb [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

#### `cryosparcm fixdbport` (Deprecated)

Use [`cryosparcm database fixport`](#cryosparcm-database-fixport) instead.

**Usage**:

```
$ cryosparcm fixdbport [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

#### `cryosparcm backup` (Deprecated)

Use [`cryosparcm database backup`](#cryosparcm-database-backup) instead.

{% hint style="danger" %}
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.

Use the `cryosparcm recover` command instead of the `backup`/`restore` commands to avoid this issue. See [Guide: Instance Recovery (v5.0+)](/setup-configuration-and-management/software-system-guides/guide-instance-recovery-v5.0.md) for details.
{% endhint %}

**Usage**:

```
$ cryosparcm backup [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

#### `cryosparcm restore` (Deprecated)

Use [`cryosparcm database restore`](#cryosparcm-database-restore) instead.

{% hint style="danger" %}
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.

Use the `cryosparcm recover` command instead of the `backup`/`restore` commands to avoid this issue. See [Guide: Instance Recovery (v5.0+)](/setup-configuration-and-management/software-system-guides/guide-instance-recovery-v5.0.md) for details.
{% endhint %}

**Usage**:

```
$ cryosparcm restore [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

#### `cryosparcm compact` (Deprecated)

Use [`cryosparcm database compact`](#cryosparcm-database-compact) instead.

**Usage**:

```
$ cryosparcm compact [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

#### `cryosparcm listusers` (Deprecated)

Use [`cryosparcm user list`](#cryosparcm-user-list) instead.

**Usage**:

```
$ cryosparcm listusers [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

#### `cryosparcm createuser` (Deprecated)

Use [`cryosparcm user create`](#cryosparcm-user-create) instead.

**Usage**:

```
$ cryosparcm createuser [OPTIONS]
```

**Options**:

* `--email TEXT`: \[required]
* `--password TEXT`: \[required]
* `--username TEXT`: \[required]
* `--firstname TEXT`: \[required]
* `--lastname TEXT`: \[required]
* `--role [user|admin]`: \[default: user]
* `--help`: Show this message and exit.

#### `cryosparcm updateuser` (Deprecated)

Use [`cryosparcm user update`](#cryosparcm-user-update) instead.

**Usage**:

```
$ cryosparcm updateuser [OPTIONS]
```

**Options**:

* `--email TEXT`: \[required]
* `--password TEXT`: \[required]
* `--username TEXT`
* `--firstname TEXT`
* `--lastname TEXT`
* `--admin [true|false]`
* `--help`: Show this message and exit.

#### `cryosparcm resetpassword` (Deprecated)

Use [`cryosparcm user resetpassword`](#cryosparcm-user-resetpassword) instead.

**Usage**:

```
$ cryosparcm resetpassword [OPTIONS]
```

**Options**:

* `--email TEXT`: \[required]
* `--password TEXT`: \[required]
* `--help`: Show this message and exit.

#### `cryosparcm jobstatus` (Deprecated)

Use [`cryosparcm job status`](#cryosparcm-job-status) instead.

**Usage**:

```
$ cryosparcm jobstatus [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

#### `cryosparcm joblog` (Deprecated)

Use [`cryosparcm job log`](#cryosparcm-job-log) instead.

**Usage**:

```
$ cryosparcm joblog [OPTIONS] PROJECT JOB
```

**Arguments**:

* `PROJECT`: \[required]
* `JOB`: \[required]

**Options**:

* `--help`: Show this message and exit.

#### `cryosparcm eventlog` (Deprecated)

Use [`cryosparcm job events`](#cryosparcm-job-events) instead.

**Usage**:

```
$ cryosparcm eventlog [OPTIONS] PROJECT JOB
```

**Arguments**:

* `PROJECT`: \[required]
* `JOB`: \[required]

**Options**:

* `--help`: Show this message and exit.

#### `cryosparcm licensestatus` (Deprecated)

Use [`cryosparcm test license`](#cryosparcm-test-license) instead.

**Usage**:

```
$ cryosparcm licensestatus [OPTIONS]
```

**Options**:

* `--help`: Show this message and exit.

#### `cryosparcm cluster validate` (Deprecated)

Use [`cryosparcm test workers`](#cryosparcm-test-workers) instead.

**Usage**:

```
$ cryosparcm cluster validate [OPTIONS] NAME
```

**Arguments**:

* `NAME`: Cluster target name \[required]

**Options**:

* `--projects-dir TEXT`: Absolute path to projects directory \[required]
* `--help`: Show this message and exit.