> ## Documentation Index > Fetch the complete documentation index at: https://wiki.latch.bio/llms.txt > Use this file to discover all available pages before exploring further. # Commands # 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: ```bash theme={null} 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 `: 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 prompted to paste a Personal API Token (or Workspace API Token if they only need to access a single workspace from this machine), which can be generated from the [Developer Settings](https://console.latch.bio/settings/developer) page under **Access Tokens**. 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. Okta SSO Configuration Microsoft Azure SSO Configuration **Example:** ```bash theme={null} 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:** ```bash theme={null} latch workspace ``` ## Workflow Development Commands ### `latch init ` Initializes boilerplate for local workflow code. Only used for the [Python SDK](/workflows/sdk/python/quick-start). Not applicable for [Nextflow](/workflows/sdk/nextflow/overview) or [Snakemake](/workflows/sdk/snakemake-v2/overview) workflows. **Options:** * `-t, --template `: 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 `: 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](/workflows/sdk/nextflow/overview) 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:** ```bash theme={null} # 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 ` Generates a user editable Dockerfile for a workflow. **Options:** * `-s, --snakemake`: Generate a Dockerfile with arguments needed for [Snakemake workflows](/workflows/sdk/snakemake-v2/overview). * `-n, --nextflow`: Generate a Dockerfile with arguments needed for [Nextflow workflows](/workflows/sdk/nextflow/overview). * `-f, --force`: Overwrite existing Dockerfile without confirming * `-a, --apt-requirements `: Path to a text file containing apt packages to install * `-r, --r-env `: Path to an environment.R file containing R packages to install * `-c, --conda-env `: Path to an environment.yml file to install via conda * `-i, --pyproject `: Path to a setup.py / buildable pyproject.toml file to install * `-p, --pip-requirements `: Path to a requirements.txt file to install via pip * `-d, --direnv `: 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:** ```bash theme={null} 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 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:** ```bash theme={null} latch generate-metadata nextflow_schema.json --nextflow ``` ### `latch develop ` Starts a local development session for workflow development. **Options:** * `--yes, -y`: Skip the confirmation dialog * `--wf-version, -v `: 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 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:** ```bash theme={null} 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 `: Optional execution ID to inspect * `--egn-id, -g `: Optional task execution ID to inspect * `--container-index, -c `: Optional container index to inspect (only used for Map Tasks) To find these values, navigate to the [Executions tab](https://console.latch.bio/executions) → 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:** ```bash theme={null} latch exec --execution-id abc123 ``` ## Workflow Registration Commands ### `latch register ` 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 `: 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 `: Module containing Latch workflow to register (default: `wf`) * `--metadata-root `: Directory containing Latch metadata (Nextflow and Snakemake only) * `--snakefile ` \[**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 to a nextflow script to register * `--nf-execution-profile `: 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:** ```bash theme={null} latch register my-workflow latch register my-workflow --nf-script main.nf --nf-execution-profile test, docker ``` ### `latch preview ` 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:** ```bash theme={null} latch preview my-workflow ``` ## Workflow Management Commands ### `latch get-wf [--name ]` \[**DEPRECATED**] This command is deprecated and will be removed in a future version of the CLI. Lists workflows. **Options:** * `--name `: 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:** ```bash theme={null} 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:** ```bash theme={null} latch get-executions ``` ## Data Management Commands ### Latch URLs Latch URLs are a way to reference files and directories that live on [Latch Data](/data/overview). When you are using the below CLI commands, you must use Latch URLs when refering remote files on Latch. API and Usage Examples ### `latch cp ` Copy files between Latch Data and local, or between two Latch Data locations. **Options:** * `--progress `: 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 `: Manually specify number of cores to parallelize over * `--chunk-size-mib `: 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:** ```bash theme={null} latch cp local_file.txt latch://.account/path/on/latch latch cp latch://.account/path/on/latch latch://.account/path/on/latch latch cp latch://.account/path/on/latch*.txt ./local_folder/ ``` To find your remote Latch Data path: open your workspace, go to the [Latch Data tab](https://console.latch.bio/data), click the file or folder, then check the right sidebar for the path and use the copy icon. ### `latch mv ` 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:** ```bash theme={null} latch mv latch://.account/old/path/on/latch latch://.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:** ```bash theme={null} latch ls latch ls latch://.account/my-folder/ latch ls latch://.account/folder1/ latch://.account/folder2/ --group-directories-first ``` ### `latch rmr ` 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:** ```bash theme={null} latch rmr latch://.account/old-folder/ --yes ``` ### `latch mkdirp ` Creates a new remote directory. **Description:** Creates directories in Latch Data storage, including parent directories as needed. **Example:** ```bash theme={null} latch mkdirp latch://.account/new-folder/subfolder/ ``` ### `latch sync ... ` 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 `: 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:** ```bash theme={null} latch sync ./local_folder/ latch://remote/path/ latch sync ./file1.txt ./file2.txt latch://remote/destination/ --delete ``` ## Nextflow Commands ### `latch nextflow version ` 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:** ```bash theme={null} latch nextflow version my-nextflow-workflow-directory ``` ### `latch nextflow generate-entrypoint ` Generate a `wf/entrypoint.py` file from a Nextflow workflow. **Options:** * `--metadata-root `: Directory containing Latch metadata * `--nf-script `: Path to the nextflow entrypoint to register (required) * `--execution-profile `: Set execution profile for Nextflow workflow **Description:** Creates a Python entrypoint file that wraps the Nextflow workflow for execution on Latch. **Example:** ```bash theme={null} # 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 `: Optional execution ID to inspect. Find the execution ID by navigating to the desired execution in the [Executions tab](https://console.latch.bio/executions) and copying the execution ID from the sidebar. **Description:** Provides interactive access to Nextflow workflow execution directories for debugging and inspection. **Example:** ```bash theme={null} latch nextflow attach --execution-id abc123 ``` ### `latch nextflow register ` \[**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 `: Path to the entrypoint nextflow file (default: "main.nf") **Description:** Registers a Nextflow workflow with Latch, handling versioning and packaging automatically. **Example:** ```bash theme={null} latch nextflow register my-nextflow-workflow-directory --script-path workflow.nf ``` ## Pod Management Commands ### `latch pods stop [pod_id]` Stops a [Latch Pod](/pods/overview) 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:** ```bash theme={null} latch pods stop 12345 latch pods stop # Stops the current pod ``` ## Test Data Commands ### `latch test-data upload ` 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:** ```bash theme={null} 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:** ```bash theme={null} latch test-data ls ``` ### `latch test-data remove ` Remove test data object. **Description:** Removes test data objects from the managed bucket. **Example:** ```bash theme={null} latch test-data remove s3://latch-public/test_data.csv ``` ## Deprecated Commands ### `latch get-params ` \[**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](/workflows/sdk/testing-and-debugging-a-workflow/programmatic-execution) instead. ### `latch launch ` \[**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](/workflows/sdk/testing-and-debugging-a-workflow/programmatic-execution) instead. ## Global Options * `--version`: Show the version and exit * `--help`: Show help message and exit ## Examples ### Complete Nextflow Workflow Upload Flow ```bash theme={null} # 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 ```bash theme={null} # 1. Upload data latch cp ./local_data/ latch://.account/folder/on/latch # 2. List contents latch ls latch://.account/folder/on/latch # 3. Sync updates latch sync ./updated_data/ latch://.account/folder/on/latch # 4. Clean up latch rmr latch://.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