CLI Reference

This document provides a comprehensive reference for all command-line options available in the Varvis Download CLI.

Usage

varvis-download [options]

Options

Option	Type	Default	Description
--config, c	string	.config.json	Path to the configuration file
--username, u	string	-	Varvis API username
--password, p	string	-	Varvis API password
--password-stdin	boolean	false	Read the password from the first line of stdin (recommended for automation; mirrors docker login).
--target, t	string	-	Target for the Varvis API (instance short name, e.g. laborberlin)
--analysisIds, a	array	-	Analysis IDs to download files for (comma-separated)
--sampleIds, s	array	-	Sample IDs to filter analyses (comma-separated)
--limsIds, l	array	-	LIMS IDs to filter analyses (comma-separated)
--list, L	boolean	false	List available files for the specified analysis IDs
--destination, d	string	.	Destination folder for the downloaded files
--proxy, x	string	-	Proxy URL
--proxyUsername, pxu	string	-	Proxy username
--proxyPassword, pxp	string	-	Proxy password
--overwrite, o	boolean	false	Overwrite existing files
--filetypes, f	array	bam,bam.bai	File types to download (comma-separated): bam, bam.bai, vcf.gz, vcf.gz.tbi
--loglevel, ll	string	info	Logging level (info, warn, error, debug)
--logfile, lf	string	-	Path to the log file
--reportfile, r	string	-	Path to the report file
--filter, F	array	[]	Filter expressions with AND logic. Operators: = != > < >= <= ~= (contains) ^= (starts with).
--latest	boolean	false	Keep only the newest analysis per sample (highest analysis ID). Useful for repeat sequencing.
--range, g	string	-	Genomic range for ranged download (e.g., chr1:1-100000)
--bed, b	string	-	Path to BED file containing multiple regions
--unmapped, um	boolean	false	Extract unmapped reads from BAM files. Can be combined with --range to produce a single BAM with both.
--restoreArchived, ra	string	ask	Restore archived files. Accepts "no", "ask" (default), "all", or "force".
--restorationFile, rf	string	awaiting-restoration.json	Path and name for the awaiting-restoration JSON file
--resumeArchivedDownloads, rad	boolean	false	Resume downloads for archived files from the awaiting-restoration JSON file if restoreEstimation has passed.
--list-urls, U	boolean	false	List the direct download URLs for the selected files instead of downloading them. Useful for piping to other tools.
--url-file	string	-	Path to a file to save the download URLs when using --list-urls.
--version, v	boolean	false	Show version information
--help, h	boolean	false	Show help

Examples

Basic Usage

# Download BAM files for specific analysis IDs
varvis-download -u username -p password -t target -a "analysis1,analysis2"

# List available files without downloading
varvis-download -u username -p password -t target -a "analysis1" --list

# Download with custom destination
varvis-download -u username -p password -t target -a "analysis1" -d "/path/to/download"

Advanced Usage

# Download with filters
varvis-download -u username -p password -t target -s "sample1,sample2" --filter "analysisType=SNV"

# Ranged download for specific genomic region (BAM files)
varvis-download -u username -p password -t target -a "analysis1" --range "chr1:1-100000" -f "bam,bam.bai"

# Ranged download for VCF files (uses tabix + bgzip pipeline)
varvis-download -u username -p password -t target -a "analysis1" --range "chr1:155000000-156000000" -f "vcf.gz,vcf.gz.tbi"

# Multiple regions (creates separate files for each region)
varvis-download -u username -p password -t target -a "analysis1" --range "chr1:1000000-2000000 chr17:41000000-42000000" -f "vcf.gz,vcf.gz.tbi"

# Download with BED file for multiple regions
varvis-download -u username -p password -t target -a "analysis1" --bed "/path/to/regions.bed" -f "vcf.gz,vcf.gz.tbi"

# Resume archived downloads
varvis-download --resumeArchivedDownloads

# List download URLs instead of downloading
varvis-download -u username -p password -t target -a "analysis1" --list-urls

# Save URLs to a file for later use
varvis-download -u username -p password -t target -a "analysis1" --list-urls --url-file urls.txt

# Pipe URLs to wget for parallel downloading
varvis-download -u username -p password -t target -a "analysis1" --list-urls | wget -i -

# Use with aria2c for accelerated downloads
varvis-download -u username -p password -t target -a "analysis1" --list-urls | aria2c -i -

Genomic Range Downloads

VCF Range Downloads:

• Requires tabix v1.20+ and bgzip v1.20+
• Automatically downloads .tbi index files
• Uses tabix -h | bgzip pipeline for proper VCF format
• Creates files with format: basename.region.vcf.gz
• Each region creates a separate output file

BAM Range Downloads:

• Requires samtools v1.17+
• Automatically downloads .bai index files
• Uses samtools view -b for region extraction
• Single output file for all regions in BED file

Unmapped Read Extraction (--unmapped):

• Requires samtools v1.17+ (no tabix/bgzip needed)
• Extracts reads with no reference assignment using wildcard chromosome *
• Standalone: creates basename.unmapped.bam
• Combined with --range: produces a single BAM with both ranged and unmapped reads
• Only applies to BAM files (VCF files are skipped)

Configuration File

You can use a configuration file to store commonly used options:

varvis-download --config /path/to/config.json

Example configuration file:

{
  "username": "your-username",
  "target": "mytarget",
  "destination": "/path/to/downloads",
  "filetypes": "bam,bam.bai,vcf.gz",
  "loglevel": "info"
}