Skip to content

Command Line Examples

The Cirro command-line interface (CLI) provides an easy way to access your Cirro data from the command prompt. The most common uses of the CLI are to upload new datasets or to download either partial or entire datasets. To get started with the CLI, first learn about installing the Cirro client and then see the examples below.

Quick Hint: Uploading and Downloading Large Files from the Command Line

# Install the CLI
pip install cirro

# Upload
cirro upload -i

# or Download
cirro download -i

Initial Configuration

When running the CLI for the first time, Cirro will ask you to provide details on what Cirro instance you wish to use and if the login information should be cached.

The Cirro instance URL is just the [org].cirro.bio part, not the entire path to your project or dataset.

$ cirro upload -i

? Enter the URL of the Cirro instance you'd like to connect to: app.cirro.bio

? Would you like to save your login? (do not use this on shared devices) Yes

It will then prompt you to authenticate. You can Control - click the link to open it up in your default web browser.

To sign in, use a web browser to open the page
   https://app.cirro.bio/authorize?user_code=<SNIPPED>

Automated Uploading Datasets

To automate the process of dataset upload, cirro can be used in non-interactive mode. To use this method, run: 

cirro upload [OPTIONS]
with the following options: 
[OPTIONS]:
  --name TEXT                  Name of the dataset
  --description TEXT           Description of the dataset (optional)
  --project TEXT               Name or ID of the project
  --data-type, --process TEXT  Name or ID of the data type (--process is deprecated)
  --data-directory TEXT        Directory you wish to upload
  --file TEXT                  Relative path of the file(s) to upload (optional, can be used multiple times)
  -i, --interactive            Gather arguments interactively
  --include-hidden             Include hidden files in the upload (e.g., files starting with .)
  --help                       Show this message and exit.

Full example:

$ cirro upload \
  --project "Test Project 1" \
  --name "test" \
  --file "sample1.fastq.gz" \
  --file "sample2.fastq.gz" \
  --data-directory "~/data" \
  --data-type "Paired DNAseq (FASTQ)"

Interactive Uploading Datasets

To start the interactive upload process, run: 

cirro upload --interactive
You will be prompted to enter the following information. Follow the directions in the command line and hit enter after each of the following:

  1. Select the project which the new dataset should be uploaded to using the arrow keys. E.g. Test Project
  2. Enter the path to the directory on your filesystem which should be uploaded. E.g. /shared/biodata/test
  3. Confirm the number and size of files to upload. E.g. Yes
  4. Select the dataset type using the arrow keys. E.g. RNAseq (FASTQ)
  5. Enter the dataset name. E.g. Test Dataset
  6. Enter the dataset description (optional). E.g. Test data for practice

After providing all of the required information, the files will be uploaded into the new dataset. Once the upload process is complete, the dataset will become visible in Cirro.

Automated Downloading Datasets

To automate the process of dataset download, cirro can be used in non-interactive mode. To use this method, run the command: 

cirro download [OPTIONS]
with the following options: 
[OPTIONS]:
  --project TEXT         Name or ID of the project
  --dataset TEXT         ID of the dataset
  --file TEXT            Relative path of the file(s) to download (optional, can be used multiple times)
  --data-directory TEXT  Directory to store the files
  -i, --interactive      Gather arguments interactively
  --help                 Show this message and exit.

Full example:

$ cirro download \
  --project "Test Project 1" \
  --dataset "test" \
  --data-directory "~/download"

Interactive Downloading Datasets

To interactively download a dataset (or part of a dataset) from Cirro to your local hard drive, run: 

cirro download --interactive

You will be prompted to enter the following information. Follow the directions in the command line and hit enter after each of the following:

  1. Select the project which contains the dataset of interest
  2. Select the dataset to download. Here you can paste your full dataset name and ID and hit enter. You can also start typing your dataset name, then press TAB and once you see your dataset, you can use the arrows keys to walk through the options and hit enter to select a dataset. Or pressing TAB immediately will provide a list of all available options, and you can arrow down to your selection and hit enter.
  3. Edit the local folder to use as the destination of the download if necessary
  4. Select if you want to download the entire dataset, only some of the files by choosing from a list of file names, or only some of the files by providing a glob naming pattern (e.g. *.fastq.gz)
    • If you choose to download some of the files by selecting them, use the up/down arrows keys to walk through the list and hit space to select a file and space again to deselect it. If you want to select all the files, you can hit a. If it is easier, you can also select the files you don't want to download and then hit i to switch all the selected and unselected files. When you are happy with your selection, hit enter.
    • If you choose to download some of the files using a pattern, type the glob naming pattern and hit enter. Then you will see a list of the files you've selected and you can choose y to continue downloading or n to go back and re-enter your naming pattern.

All files from the dataset will be downloaded to a folder named data/ in your selected destination.

Listing Datasets in a Project

To list all the datasets available in a project (often used before downloading files), you can run: 

cirro list-datasets [OPTIONS]
with the following options: 
[OPTIONS]:
  --project TEXT         ID of the project
  -i, --interactive      Gather arguments interactively
  --help                 Show this message and exit.

Dataset File Validation

To ensure data integrity and consistency, use the cirro validate command, which compares local files against a dataset stored in Cirro.

Usage: cirro validate [OPTIONS]

  Validate that the contents of a local folder match those of a dataset in Cirro

Options:
  --dataset TEXT               Name or ID of the dataset
  --project TEXT               Name or ID of the project
  --data-directory TEXT        Local directory you wish to validate
  -i, --interactive            Gather arguments interactively
  --help                       Show this message and exit.

Uploading a Reference

To upload a reference to a Cirro project, use the cirro upload-reference command.

Usage: cirro upload-reference [OPTIONS]

  Upload a reference to a project

Options:
  --name TEXT            Name of the reference
  --reference-type TEXT  Type of the reference (e.g., Reference Genome (FASTA))
  --project TEXT         Name or ID of the project
  --reference-file TEXT  Location of reference file(s) to upload (can be used multiple times)
  -i, --interactive      Gather arguments interactively
  --help                 Show this message and exit.

Configuring pipelines

You can use the Cirro CLI to configure custom pipelines.

Important

To enable pipeline configuration with the Cirro CLI you need to install extras using:

pip install cirro[nextflow]      # just nextflow pipeline configuration support
pip install cirro[wdl]           # just wdl pipeline configuraiton support
pip install cirro[nextflow,wdl]  # both nextflow and wdl pipeline configuration support

Configuring Nextflow pipelines also requires a local installation of nextflow.

Usage: cirro create-pipeline-config [OPTIONS]

  Create pipeline configuration files

Options:
  -p, --pipeline-dir DIRECTORY  Directory containing the pipeline definition
                                files (e.g., WDL or Nextflow)  [default: .]
  -e, --entrypoint TEXT         Entrypoint WDL file (optional, if not
                                specified, the first WDL file found will be
                                used). Ignored for Nextflow pipelines.
  -o, --output-dir TEXT         Directory to store the generated configuration
                                files  [default: .cirro]
  -i, --interactive             Gather arguments interactively
  --help                        Show this message and exit.

For example: 

cd my/pipeline/folder
cirro create-pipeline-config

# --or--

cirro create-pipeline-config -p /path/to/my/pipeline/folder/

For a Nextflow pipeline, you should see something like:

2025-09-09 16:44:44,230 INFO     [Cirro CLI] Creating pipeline configuration files...
2025-09-09 16:44:57,247 INFO     [Cirro CLI] Writing pipeline configuration files to .cirro
2025-09-09 16:44:57,251 INFO     [Cirro CLI] Writing form configuration to .cirro/process-form.json
2025-09-09 16:44:57,701 INFO     [Cirro CLI] Nextflow schema found at ./nextflow_schema.json
2025-09-09 16:44:57,705 INFO     [Cirro CLI] Writing input configuration to .cirro/process-input.json
2025-09-09 16:44:57,706 INFO     [Cirro CLI] Pipeline configuration files created successfully.

This will generate the following files which are used when adding a Custom pipeline:

  • process-form.json: this is a JSON Schema used to configure the form in the Cirro UI that collects inputs for running a pipeline.
  • process-input.json: this is a JSON mapping of form fields to pipeline parameters.

To learn more about these files, refer to Configuring a Pipeline for Cirro