Getting Started

This guide will help you get up and running with the Varvis Download CLI tool quickly.

Prerequisites

Before installing Varvis Download CLI, ensure you have:

• Node.js v22.22.2 or higher
• NPM or Yarn for package management
• Access to a varvis® API instance
• Valid varvis® credentials

External Tools (Optional)

For genomic range downloads, you'll need these bioinformatics tools:

• samtools v1.17+ - For BAM file manipulation
• tabix v1.20+ - For VCF file indexing and querying
• bgzip v1.20+ - For VCF file compression

TIP

The tool will automatically check for these dependencies when using range download features and provide helpful error messages if they're missing.

Installation

1. Clone the Repository

git clone https://github.com/LaborBerlin/varvis-download.git
cd varvis-download

2. Install Dependencies

npm install

3. Make Executable

chmod +x varvis-download.cjs

4. Optional: Global Installation

npm link

After linking, you can use varvis-download from anywhere on your system.

Basic Usage

Set Up Authentication

The most secure way to provide credentials is through environment variables:

export VARVIS_USER="your_username"
export VARVIS_PASSWORD="your_password"

For automation and other non-interactive runs (no terminal), supply the password via VARVIS_PASSWORD or --password-stdin — the tool cannot show a prompt there and will exit with an error otherwise. See Authentication for details.

Your First Download

Download BAM files for a specific analysis:

./varvis-download.cjs -t mytarget -a 12345

This command will:

• Connect to the mytarget varvis® instance
• Download BAM and BAI files for analysis ID 12345
• Save files to the current directory

List Available Files

Before downloading, you can preview what files are available:

./varvis-download.cjs -t mytarget -a 12345 --list

Common Use Cases

Download Multiple Analyses

./varvis-download.cjs -t mytarget -a "12345,67890,11111"

Download Specific File Types

./varvis-download.cjs -t mytarget -a 12345 -f "vcf.gz,vcf.gz.tbi"

Download to Custom Directory

./varvis-download.cjs -t mytarget -a 12345 -d "./downloads"

Download with Filters

./varvis-download.cjs -t mytarget -s "LIMS-001,LIMS-002" -F "analysisType=SNV"

Configuration File

Create a .config.json file for persistent settings:

{
  "username": "your_username",
  "target": "mytarget",
  "destination": "./downloads",
  "loglevel": "info",
  "filetypes": ["bam", "bam.bai"]
}

Then run with minimal arguments:

./varvis-download.cjs -a 12345

Next Steps

Now that you have the basics working, explore these advanced features:

• Authentication Methods - Learn about different ways to provide credentials
• File Downloads - Understand file type selection and output options
• Filtering & Search - Master the filtering system for precise file selection
• Range Downloads - Extract specific genomic regions

Getting Help

• Use ./varvis-download.cjs --help for command-line help
• Check the API Reference for detailed parameter documentation
• Browse Examples for real-world usage patterns

Troubleshooting

Common Issues

Permission denied error:

chmod +x varvis-download.cjs

Node.js version too old:

node --version  # Check your version
# Update Node.js if needed

Authentication failures:

• Verify your credentials are correct
• Check network connectivity to the Varvis API
• Ensure your account has appropriate permissions

External tool errors (for range downloads):

• Install samtools, tabix, and bgzip
• Verify they're in your PATH: which samtools tabix bgzip