Overview
The Latch CLI is a command-line interface for interacting with the Latch platform. It provides tools for managing workflows, data, and development sessions. This document covers all available commands and their options.Installation
The Latch CLI is available as a Python package and can be installed with:latch
in a new virtual environment.
The Latch CLI currently requires Python >=3.9
and <=3.11
.
Authentication Commands
latch login
Authenticates a user with Latch and stores an access token in ~/.latch/token
in the machine the command is run on.
Options:
--connection <str>
: Specific Auth0 connection name if Single-Sign-On is enabled for the workspace.
latch login
command.
Latch supports Okta and Microsoft Azure as IdP providers. Visit documentation below to see how to configure SSO for your organization.
Example:
latch workspace
Opens an interactive terminal prompt allowing users to choose which workspace they want to work in.
Description:
Displays a list of available workspaces and allows switching between them. The currently selected workspace is marked.
Example:
Workflow Development Commands
latch init <pkg_name>
Initializes boilerplate for local workflow code. Only used for the Python SDK. Not applicable for Nextflow or Snakemake workflows.
Options:
-t, --template <choice>
: Template to use for the workflow (choices:empty
,docker
,subprocess
,r
,conda
,nfcore
)-d, --dockerfile
: Create a user editable Dockerfile for this workflow-b, --base-image <choice>
: Which base image to use for the Dockerfile (choices:default
,cuda
,opencl
, default:default
)
empty
: Minimal workflow structure with basic filesdocker
: Workflow example for running a Docker containersubprocess
: Workflow example with Pythonsubprocess
calling commandsr
: Workflow example with R environment setupconda
: Workflow example withconda
environment setupnfcore
: Workflow example usingsubprocess
to call a Nextflow nf-core workflow (Not recommended. If you have Nextflow workflows, use the Nextflow SDK instead.)
default
: Standard base image for most workflowscuda
: CUDA-enabled base image for GPU workflowsopencl
: OpenCL-enabled base image for GPU workflows
latch dockerfile <pkg_root>
Generates a user editable Dockerfile for a workflow.
Options:
-s, --snakemake
: Generate a Dockerfile with arguments needed for Snakemake workflows.-n, --nextflow
: Generate a Dockerfile with arguments needed for Nextflow workflows.-f, --force
: Overwrite existing Dockerfile without confirming-a, --apt-requirements <path>
: Path to a text file containing apt packages to install-r, --r-env <path>
: Path to an environment.R file containing R packages to install-c, --conda-env <path>
: Path to an environment.yml file to install via conda-i, --pyproject <path>
: Path to a setup.py / buildable pyproject.toml file to install-p, --pip-requirements <path>
: Path to a requirements.txt file to install via pip-d, --direnv <path>
: Path to a direnv file (.env) containing environment variables
latch generate-metadata [config_file]
Generates a __init__.py
and parameters.py
file from a config file.
Options:
--metadata-root <path>
: Path to directory containing Latch metadata--yes, -y
: Overwrite an existingparameters.py
file without confirming--snakemake, -s
[DEPRECATED]: Generate Latch metadata for Snakemake. This command is deprecated and no longer works forlatch >= 2.55.0.a6
--nextflow, -n
: Generate Latch metadata for Nextflow--no-infer-files, -I
[DEPRECATED]: Don’t parse strings with common file extensions as file parameters (Snakemake only). This command is deprecated and no longer works forlatch >= 2.55.0.a6
--no-defaults, -D
: Don’t generate defaults for parameters
latch develop <pkg_root>
Starts a local development session for workflow development.
Options:
--yes, -y
: Skip the confirmation dialog--wf-version, -v <str>
: Use the container environment of a specific workflow version--disable-sync, -d
: Disable the automatic syncing of local files to develop session--instance-size, --size, -s <size>
: Size of machine to provision (choices: small_task, medium_task, large_task, small_gpu_task, large_gpu_task, v100_x1_task, g6e_xlarge_task)
latch exec
Drops the user into an interactive shell from within a running task on Latch.
Description:
Provides interactive access to running or completed workflow executions for debugging and inspection purposes.
Options:
--execution-id, -e <str>
: Optional execution ID to inspect--egn-id, -g <str>
: Optional task execution ID to inspect--container-index, -c <int>
: Optional container index to inspect (only used for Map Tasks)
latch exec
command from the right sidebar.
Example:
Workflow Registration Commands
latch register <pkg_root>
Registers local workflow code to Latch.
Options:
-d, --disable-auto-version
: Whether to automatically bump the version of the workflow each time register is called--remote/--no-remote
: Use a remote server to build workflow (default: True)--docker-progress <choice>
: Docker build progress display (choices: plain, tty, auto, default: auto)-y, --yes
: Skip the confirmation dialog--open, -o
: Automatically open the registered workflow in the browser--mark-as-release, -m
: Mark the registered workflow as a release--workflow-module, -w <str>
: Module containing Latch workflow to register (default:wf
)--metadata-root <path>
: Directory containing Latch metadata (Nextflow and Snakemake only)--snakefile <path>
[DEPRECATED]: Path to a Snakefile to register.--cache-tasks/--no-cache-tasks, -c/-C
[DEPRECATED]: Whether or not to cache snakemake tasks.--nf-script <path>
: Path to a nextflow script to register--nf-execution-profile <str>
: Set execution profile for Nextflow workflow--staging
: Register the workflow in “staging” mode. Build the workflow container image but do not publish a new workflow version on Latch Console. Recommended for testing and development before registering the workflow to your team workspace.
latch preview <pkg_root>
Creates a preview of your workflow interface.
Description:
Generates a preview of the workflow’s user interface based on the defined parameters and metadata.
Example:
Workflow Management Commands
latch get-wf [--name <name>]
[DEPRECATED]
This command is deprecated and will be removed in a future version of the CLI.
--name <str>
: Filter by workflow name and display all versions. To find a workflow name, run latch get-wf without options and check the “Name” column in the output.
latch get-executions
[DEPRECATED]
Spawns an interactive terminal UI that shows all executions in a given workspace.
This command is deprecated and will be removed in a future version of the CLI.
Data Management Commands
Latch URLs
Latch URLs are a way to reference files and directories that live on Latch Data. When you are using the below CLI commands, you must use Latch URLs when refering remote files on Latch.Latch URLs
API and Usage Examples
latch cp <src> <dest>
Copy files between Latch Data and local, or between two Latch Data locations.
Options:
--progress <choice>
: Type of progress information to show while copying (choices: tasks, none, default: tasks)--verbose, -v
: Print file names as they are copied--no-glob, -G
: Don’t expand globs in remote paths--cores <int>
: Manually specify number of cores to parallelize over--chunk-size-mib <int>
: Manually specify the upload chunk size in MiB (must be >= 5)
cp -R
in Unix. Directories are copied recursively. Supports copying between local and remote locations, and between remote locations.
Example:
To find your remote Latch Data path: open your workspace, go to the Latch Data tab, click the file or folder, then check the right sidebar for the path and use the copy icon.
latch mv <src> <dest>
Move remote files in LatchData.
Options:
--no-glob, -G
: Don’t expand globs in remote paths
latch ls [paths]
List the contents of a Latch Data directory.
Options:
--group-directories-first, --gdf
: List directories before files
latch rmr <remote_path>
Deletes a remote entity.
Options:
-y, --yes
: Skip the confirmation dialog--no-glob, -G
: Don’t expand globs in remote paths--verbose, -v
: Print all files when deleting
latch mkdirp <remote_directory>
Creates a new remote directory.
Description:
Creates directories in Latch Data storage, including parent directories as needed.
Example:
latch sync <srcs>... <dst>
Update the contents of a remote directory with local data.
Options:
--delete
: Delete extraneous files from destination--ignore-unsyncable
: Synchronize even if some source paths do not exist or refer to special files--cores <int>
: Number of cores to use for parallel syncing
rsync
. Currently only supports local to remote synchronization.
Example:
Nextflow Commands
latch nextflow version <pkg_root>
Get the Latch version of Nextflow installed for the current project.
Description:
Displays the Nextflow version that will be used for the workflow execution.
Example:
latch nextflow generate-entrypoint <pkg_root>
Generate a wf/entrypoint.py
file from a Nextflow workflow.
Options:
--metadata-root <path>
: Directory containing Latch metadata--nf-script <path>
: Path to the nextflow entrypoint to register (required)--execution-profile <str>
: Set execution profile for Nextflow workflow
latch nextflow attach
Drops the user into an interactive shell to inspect the workdir of a nextflow execution.
Options:
--execution-id, -e <str>
: Optional execution ID to inspect. Find the execution ID by navigating to the desired execution in the Executions tab and copying the execution ID from the sidebar.
latch nextflow register <pkg_root>
[EXPERIMENTAL]
This command is only applicable if you are using Forch - Latch’s new architecture that allows you to run Nextflow pipelines within your own AWS account.
--yes, -y
: Skip confirmation dialogs--no-ignore, --all, -a
: Add all files (including those excluded by .gitignore/.dockerignore) to workflow archive--disable-auto-version, -d
: Only use the contents of the version file for workflow versioning--disable-git-version, -G
: When the package root is a git repository, do not append the current commit hash to the version--script-path <str>
: Path to the entrypoint nextflow file (default: “main.nf”)
Pod Management Commands
latch pods stop [pod_id]
Stops a Latch Pod given a pod_id or the pod from which the command is run.
Description:
Shuts down a running pod. If no pod_id
is provided, the command attempts to stop the pod from which the command is executed. Useful for autoshutting down the pod after a long-running script finishes to save costs.
Example:
Test Data Commands
latch test-data upload <src_path>
Uploads test data to a public Latch S3 bucket. Useful for releasing public test data for a workflow without setting up your own public S3 bucket.
Options:
--dont-confirm-overwrite, -d
: Automatically overwrite any files without asking for confirmation
latch test-data ls
List test data objects.
Description:
Lists all test data objects in the managed bucket by their full S3 paths.
Example:
latch test-data remove <object_url>
Remove test data object.
Description:
Removes test data objects from the managed bucket.
Example:
Deprecated Commands
latch get-params <wf_name>
[DEPRECATED]
This command is deprecated and will be removed in a future version of the CLI.
latch launch <params_file>
[DEPRECATED]
This command is deprecated and will be removed in a future version of the CLI.
Global Options
--version
: Show the version and exit--help
: Show help message and exit
Examples
Complete Nextflow Workflow Upload Flow
Data Management Workflow
Notes
- Most commands require authentication via
latch login
- The CLI automatically checks for updates and warns if you’re using an outdated version
- Development sessions provide cloud-based environments for testing workflows
- Data operations support both local and remote paths using the
latch://
prefix