Skip to main content

​
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: 
mamba create -n latch python=3.11
pip install latch
For best behavior, it is recommended to install 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.
Description: Initiates a OAuth2.0 flow. If a browser is available, the user will be redirected to login. Otherwise, the user will be instructed manually enter their API key from the Latch console. The API key can be found by navigating to the Developer Settings page of the workspace they want to work in. In the case where the user logs in with a SSO connection, a connection string needs to be provided to the latch login command. Latch supports Okta and Microsoft Azure as IdP providers. Visit documentation below to see how to configure SSO for your organization.
https://www.celigo.com/wp-content/uploads/2022/11/okta-logo.png

Okta

Okta SSO Configuration
https://upload.wikimedia.org/wikipedia/commons/thumb/f/fa/Microsoft_Azure.svg/2048px-Microsoft_Azure.svg.png

Microsoft Azure

Microsoft Azure SSO Configuration
Example: 
latch login
latch login --connection "sso-connection"

​
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: 
latch workspace

​
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)
Description: Creates a new workflow package with the specified name and optional template. Sets up the basic directory structure and files needed for a Latch workflow. The template determines the initial code structure and dependencies. Available Templates:
  • empty: Minimal workflow structure with basic files
  • docker: Workflow example for running a Docker container
  • subprocess: Workflow example with Python subprocess calling commands
  • r: Workflow example with R environment setup
  • conda: Workflow example with conda environment setup
  • nfcore: Workflow example using subprocess to call a Nextflow nf-core workflow (Not recommended. If you have Nextflow workflows, use the Nextflow SDK instead.)
Available Base Images:
  • default: Standard base image for most workflows
  • cuda: CUDA-enabled base image for GPU workflows
  • opencl: OpenCL-enabled base image for GPU workflows
Example: 
# Create a basic workflow
latch init my-workflow

# Create an R-based workflow with Dockerfile
latch init my-r-workflow --template r --dockerfile

# Create a CUDA-enabled workflow
latch init my-gpu-workflow --template docker --base-image cuda

# Create a Nextflow workflow
latch init my-nextflow-workflow --template nfcore

​
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
Description: Creates a Dockerfile tailored for the specified workflow type and dependencies. Supports various package managers and environment configurations. Recommended Usage: Use this command when starting a new Python SDK workflow or uploading an existing Snakemake or Nextflow workflow to Latch. It generates a Dockerfile with the correct arguments. Re-running it will overwrite any existing Dockerfile(s). Example: 
latch dockerfile my-workflow --snakemake

​
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 existing parameters.py file without confirming
  • --snakemake, -s [DEPRECATED]: Generate Latch metadata for Snakemake. This command is deprecated and no longer works for latch >= 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 for latch >= 2.55.0.a6
  • --no-defaults, -D: Don’t generate defaults for parameters
Description: Automatically generates Latch metadata files from workflow configuration files. Supports both Snakemake and Nextflow workflows. Example: 
latch generate-metadata nextflow_schema.json --nextflow

​
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)
Description: Creates a cloud-based development environment that mirrors the workflow’s runtime environment. Allows testing and debugging workflows in their intended execution context. Example: 
latch develop my-workflow --instance-size large_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)
To find these values, navigate to the Executions tab → Double click on the Execution you want to inspect → Go to the Graph & Logs tab → Click on the rectangle representing the task you want to inspect → Copy the latch exec command from the right sidebar. Example: 
latch exec --execution-id abc123

​
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.
Description: Builds and registers a workflow on the Latch platform. Registration triggers a new container image build and automatically creates a new workflow version in the Latch Console. When the —staging flag is used, no version is published. Example: 
latch register my-workflow
latch register my-workflow --nf-script main.nf --nf-execution-profile test, docker

​
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: 
latch preview my-workflow

​
Workflow Management Commands

​
latch get-wf [--name <name>] [DEPRECATED]

This command is deprecated and will be removed in a future version of the CLI.
Lists workflows. Options:
  • --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.
Description: Displays a list of all workflows in the current workspace, including their IDs, names, and versions. Example: 
latch get-wf
latch get-wf --name "nf_nf_core_rnaseq"

​
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.
Description: Provides an interactive interface to view workflow executions and their statuses. Example: 
latch get-executions

​
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)
Description: Behaves like cp -R in Unix. Directories are copied recursively. Supports copying between local and remote locations, and between remote locations. Example: 
latch cp local_file.txt latch://<account_id>.account/path/on/latch
latch cp latch://<account_id>.account/path/on/latch latch://<account_id>.account/path/on/latch
latch cp latch://<account_id>.account/path/on/latch*.txt ./local_folder/
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
Description: Moves files and directories within the Latch Data storage system. Example: 
latch mv latch://<account_id>.account/old/path/on/latch latch://<account_id>.account/new/path/on/latch

​
latch ls [paths]

List the contents of a Latch Data directory. Options:
  • --group-directories-first, --gdf: List directories before files
Description: Lists the contents of specified remote directories. If no paths are provided, defaults to the root directory. Example: 
latch ls
latch ls latch://<account_id>.account/my-folder/
latch ls latch://<account_id>.account/folder1/ latch://<account_id>.account/folder2/ --group-directories-first

​
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
Description: Recursively deletes files and directories from Latch Data storage. Example: 
latch rmr latch://<account_id>.account/old-folder/ --yes

​
latch mkdirp <remote_directory>

Creates a new remote directory. Description: Creates directories in Latch Data storage, including parent directories as needed. Example: 
latch mkdirp latch://<account_id>.account/new-folder/subfolder/

​
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
Description: Synchronizes local files and directories with remote storage, similar to rsync. Currently only supports local to remote synchronization. Example: 
latch sync ./local_folder/ latch://remote/path/
latch sync ./file1.txt ./file2.txt latch://remote/destination/ --delete

​
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 version my-nextflow-workflow-directory

​
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
Description: Creates a Python entrypoint file that wraps the Nextflow workflow for execution on Latch. Example: 
# currently in the root directory of the nextflow workflow
latch nextflow generate-entrypoint . --nf-script main.nf

​
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.
Description: Provides interactive access to Nextflow workflow execution directories for debugging and inspection. Example: 
latch nextflow attach --execution-id abc123

​
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.
Register a Nextflow workflow with Latch. Options:
  • --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”)
Description: Registers a Nextflow workflow with Latch, handling versioning and packaging automatically. Example: 
latch nextflow register my-nextflow-workflow-directory --script-path workflow.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: 
latch pods stop 12345
latch pods stop  # Stops the current pod

​
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
Description: Uploads test data files to a managed public Latch S3 bucket for use in workflow development and testing. Example: 
latch test-data upload ./test_data.csv

​
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 ls

​
latch test-data remove <object_url>

Remove test data object. Description: Removes test data objects from the managed bucket. Example: 
latch test-data remove s3://latch-public/test_data.csv

​
Deprecated Commands

​
latch get-params <wf_name> [DEPRECATED]

This command is deprecated and will be removed in a future version of the CLI.
Generate a python parameter map for a workflow. Description: This command is deprecated and frequently broken. For programmatic workflow execution, use the Python API instead.

​
latch launch <params_file> [DEPRECATED]

This command is deprecated and will be removed in a future version of the CLI.
Launch a workflow using a python parameter map. Description: This command is deprecated and frequently broken. For programmatic workflow execution, use the Python API instead.

​
Global Options

  • --version: Show the version and exit
  • --help: Show help message and exit

​
Examples

​
Complete Nextflow Workflow Upload Flow

# 1. Navigate to your Nextflow workflow directory
cd my-nextflow-workflow

# 2. Generate Latch metadata to define the graphical user interface on Latch from your Nextflow schema
latch generate-metadata nextflow_schema.json --nextflow

# 3. Register the workflow with Latch
latch register . --nf-script main.nf --nf-execution-profile docker,test

# 4. The workflow is now available in the Latch Console
# You can launch it via the web interface or programmatically

​
Data Management Workflow

# 1. Upload data
latch cp ./local_data/ latch://<account_id>.account/folder/on/latch

# 2. List contents
latch ls latch://<account_id>.account/folder/on/latch

# 3. Sync updates
latch sync ./updated_data/ latch://<account_id>.account/folder/on/latch 

# 4. Clean up
latch rmr latch://<account_id>.account/folder/on/latch

​
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
⌘I