CLI Reference
The Copick CLI provides a comprehensive set of commands for managing Copick projects, configurations, and data.
Environment Variable Support
The configuration file path can be set using the COPICK_CONFIG
environment variable instead of passing --config
every time:
Commands
copick browse
Browse Copick projects interactively using a terminal user interface.
Usage:
Options:
Option | Type | Description | Default |
---|---|---|---|
-c, --config PATH |
Path | Path to the configuration file | Uses COPICK_CONFIG env var |
-ds, --dataset-ids ID |
Integer | Dataset IDs to include (multiple inputs possible) | None |
--debug / --no-debug |
Boolean | Enable debug logging | no-debug |
Examples:
# Browse a local project
copick browse --config my_project.json
# Browse CryoET Data Portal datasets
copick browse --dataset-ids 10000 --dataset-ids 10001
# Using environment variable
export COPICK_CONFIG=my_project.json
copick browse
copick config
Manage Copick configuration files.
Subcommands:
copick config dataportal
- Set up a configuration file from CZDP dataset IDscopick config filesystem
- Set up a configuration file for a local project
copick config dataportal
Generate a configuration file from CryoET Data Portal datasets.
Usage:
Options:
Option | Type | Description | Default |
---|---|---|---|
-ds, --dataset-id INTEGER |
Integer | Dataset IDs from the CryoET Data Portal (required, multiple allowed) | None |
--overlay TEXT |
Path | Path to the local overlay directory (required) | None |
--output TEXT |
Path | Path to save the generated configuration file | config.json |
--debug / --no-debug |
Boolean | Enable debug logging | no-debug |
Examples:
# Single dataset
copick config dataportal --dataset-id 10000 --overlay ./overlay --output my_config.json
# Multiple datasets
copick config dataportal -ds 10000 -ds 10001 --overlay ./overlay --output multi_config.json
copick config filesystem
Generate a configuration file for a local project directory.
Usage:
Options:
Option | Type | Description | Default |
---|---|---|---|
--overlay-root TEXT |
Path | Overlay root path (required) | None |
--objects TEXT |
String | List of desired objects in the format: name,is_particle,[radius],[pdb_id] (required, multiple allowed) |
None |
--config TEXT |
Path | Path to the output JSON configuration file | config.json |
--proj-name TEXT |
String | Name of the project configuration | project |
--proj-description TEXT |
String | Description of the project configuration | Config Project for SessionXXa |
--debug / --no-debug |
Boolean | Enable debug logging | no-debug |
Object Format:
Objects are specified using the format: name,is_particle,[radius],[pdb_id]
name
: The name of the object (required, cannot contain underscores)is_particle
:True
orFalse
indicating if this is a particle (required)radius
: Radius in pixels for particles (optional, only for particles)pdb_id
: PDB ID for the particle structure (optional, only for particles)
Examples:
# Basic filesystem config with membrane and ribosome
copick config filesystem \
--overlay-root /path/to/project \
--objects membrane,False \
--objects ribosome,True,120,4V9D \
--config my_project.json
# Complex project with multiple particles
copick config filesystem \
--overlay-root /mnt/data/experiment \
--objects membrane,False \
--objects ribosome,True,120,4V9D \
--objects proteasome,True,80,6MSB \
--objects apoferritin,True,60,4V1W \
--proj-name "Cellular_Tomography" \
--proj-description "Cellular structures from cryo-ET experiment" \
--config cellular_config.json
# Minimal config
copick config filesystem \
--overlay-root ./data \
--objects virus,True,150
copick add
Add entities to Copick projects.
Subcommands:
copick add tomogram
- Add a tomogram to the project
copick add tomogram
Add one or more tomograms to the project from MRC or Zarr files.
Usage:
Arguments:
Argument | Type | Description |
---|---|---|
PATH |
Path | Path to tomogram file(s) (MRC or Zarr format) or glob pattern (e.g., *.mrc ) |
Options:
Option | Type | Description | Default |
---|---|---|---|
-c, --config PATH |
Path | Path to the configuration file | Uses COPICK_CONFIG env var |
--run TEXT |
String | The name of the run. If not specified, will use the name of the file (stripping extension), ignored if PATH is glob pattern. | "" |
--tomo-type TEXT |
String | The name of the tomogram (e.g. wbp) | wbp |
--file-type TEXT |
String | The file type ('mrc' or 'zarr') | Auto-detected |
--voxel_size FLOAT |
Float | Voxel size in Angstrom (overrides header value) | None |
--create-pyramid / --no-create-pyramid |
Boolean | Compute the multiscale pyramid | create-pyramid |
--pyramid-levels INTEGER |
Integer | Number of pyramid levels (each level is 2x downscaling) | 3 |
--chunk-size TEXT |
String | Chunk size for the output Zarr file | 256,256,256 |
--overwrite / --no-overwrite |
Boolean | Overwrite the object if it exists | no-overwrite |
--create / --no-create |
Boolean | Create the object if it does not exist | create |
--debug / --no-debug |
Boolean | Enable debug logging | no-debug |
Batch Processing with Glob Patterns
You can add multiple tomograms at once using glob patterns. When using glob patterns, run names are automatically derived from filenames, and a progress bar shows the processing status.
Examples:
# Add single MRC tomogram with default settings
copick add tomogram --config config.json --run TS_001 data/tomogram.mrc
# Add multiple tomograms using glob pattern (auto-detects run names from filenames)
copick add tomogram --config config.json data/tomograms/*.mrc
# Add all MRC files in current directory
copick add tomogram --config config.json *.mrc
# Add tomograms with specific naming pattern
copick add tomogram --config config.json "data/TS_*_recon.mrc"
# Add Zarr tomogram with custom voxel size and pyramid levels
copick add tomogram --config config.json --voxel_size 10.0 --pyramid-levels 4 data/tomogram.zarr
# Add multiple Zarr files without pyramid generation (faster)
copick add tomogram --config config.json --no-create-pyramid data/*.zarr
# Add tomogram with custom chunk size
copick add tomogram --config config.json --chunk-size "128,128,128" data/tomogram.mrc
# Add multiple tomograms with custom settings
copick add tomogram --config config.json --tomo-type "denoised" --voxel_size 8.0 data/processed_*.mrc
copick new
Create new Copick entities.
Subcommands:
copick new picks
- Create empty picks for a given particle namecopick new run
- Create an empty run with the given namecopick new voxelspacing
- Create an empty voxelspacing with the given name
copick new picks
Create empty picks for a given particle name.
Usage:
Options:
Option | Type | Description | Default |
---|---|---|---|
-c, --config PATH |
Path | Path to the configuration file | Uses COPICK_CONFIG env var |
--particle-name TEXT |
String | Name of the particle to create picks for (required) | None |
--out-user TEXT |
String | User ID to write picks to | copick |
--out-session TEXT |
String | Session ID to write picks to | 0 |
--overwrite BOOLEAN |
Boolean | Overwrite existing picks | False |
--debug / --no-debug |
Boolean | Enable debug logging | no-debug |
Examples:
# Create empty picks for ribosomes
copick new picks --config config.json --particle-name ribosome
# Create picks with custom user and session
copick new picks --config config.json --particle-name proteasome --out-user alice --out-session 1
# Create picks with overwrite enabled
copick new picks --config config.json --particle-name ribosome --overwrite True
copick new run
Create an empty run with the given name.
Usage:
Arguments:
Argument | Type | Description |
---|---|---|
NAME |
String | The name of the new run to be created |
Options:
Option | Type | Description | Default |
---|---|---|---|
-c, --config PATH |
Path | Path to the configuration file | Uses COPICK_CONFIG env var |
--overwrite / --no-overwrite |
Boolean | Overwrite the object if it exists | no-overwrite |
--create / --no-create |
Boolean | Create the object if it does not exist | create |
--debug / --no-debug |
Boolean | Enable debug logging | no-debug |
Examples:
# Create a new run
copick new run --config config.json TS_005
# Create run with overwrite enabled
copick new run --config config.json --overwrite TS_005
copick new voxelspacing
Create an empty voxelspacing with the given name.
Usage:
Arguments:
Argument | Type | Description |
---|---|---|
VOXEL_SPACING |
Float | The voxel spacing in Angstrom to be added to the run |
Options:
Option | Type | Description | Default |
---|---|---|---|
-c, --config PATH |
Path | Path to the configuration file | Uses COPICK_CONFIG env var |
--run RUN |
String | Name of the run to add voxel spacing to (required) | None |
--overwrite / --no-overwrite |
Boolean | Overwrite the object if it exists | no-overwrite |
--create / --no-create |
Boolean | Create the object if it does not exist | create |
--debug / --no-debug |
Boolean | Enable debug logging | no-debug |
Examples:
# Add 10.0 Angstrom voxel spacing to run
copick new voxelspacing --config config.json --run TS_001 10.0
# Add voxel spacing with overwrite enabled
copick new voxelspacing --config config.json --run TS_001 --overwrite 5.0
copick info
Display information about the Copick CLI and available plugins.
Usage:
Examples:
Plugin System
Extensibility
The Copick CLI supports extensibility through plugins. External packages can register additional commands by defining entry points in the copick.commands
group.
Plugin Registration
Using setup.py:
from setuptools import setup
setup(
name="my-copick-plugin",
entry_points={
"copick.commands": [
"my-command = my_package.cli:my_command",
],
},
)
Using pyproject.toml:
Plugin Implementation
Creating a Click Command:
import click
from copick.cli.util import add_config_option, add_debug_option
from copick.util.log import get_logger
@click.command()
@add_config_option
@add_debug_option
def my_command(config: str, debug: bool):
"""My custom copick command."""
logger = get_logger(__name__, debug=debug)
logger.info(f"Running my command with config: {config}")
Usage: After installing your package, the command will be available:
Common Workflows
Setup from Data Portal
Create a new project from CryoET Data Portal datasets:
# Create configuration from data portal
copick config dataportal --dataset-id 10000 --overlay ./overlay --output project.json
# Set environment variable for convenience
export COPICK_CONFIG=project.json
# Browse the project
copick browse
Add Data to Project
Add tomograms and create annotation templates:
# Add a single tomogram
copick add tomogram --run TS_001 data/tomogram.mrc
# Add multiple tomograms using glob pattern
copick add tomogram data/tomograms/*.mrc
# Create empty picks for annotation
copick new picks --particle-name ribosome
# Browse to verify
copick browse
Work with Multiple Datasets
Combine multiple datasets in one project:
# Create configuration with multiple datasets
copick config dataportal -ds 10000 -ds 10001 -ds 10002 --overlay ./overlay --output multi_project.json
# Browse all datasets together
copick browse --config multi_project.json
Development and Debugging
Debug and test your Copick workflows:
# Run commands with debug logging
copick browse --config project.json --debug
# Create a new run for testing
copick new run --config project.json TEST_RUN
# Add a voxel spacing to the test run
copick new voxelspacing --config project.json --run TEST_RUN 10.0
# Add a tomogram with detailed output
copick add tomogram --config project.json --run TEST_RUN --debug data/test_tomogram.mrc