CLI Reference

The Bystro command-line interface provides a convenient way to interact with our services directly from your terminal. This page covers the most commonly used commands.

Installation

Installing Bystro Python Library

To install the Bystro Python package, run:

pip install bystro

Installing bystro-vcf (Required for Ancestry CLI)

The Bystro ancestry CLI score tool (bystro-api ancestry score) parses VCF files to generate dosage matrices. This requires bystro-vcf, a Go program which can be installed with:

# Requires Go: install from https://golang.org/doc/install go install github.com/bystrogenomics/bystro-vcf@2.2.3

Platform Support

Bystro is compatible with Linux and MacOS. Windows support is experimental.

If you are installing on MacOS as a native binary (Arm), you will need to install the following additional dependencies:

brew install cmake

Please refer to INSTALL.md for more details.

Authentication

Login

Authenticate with your Bystro account:

bystro-vcf login

You'll be prompted to enter your email and password.

Check Authentication Status

Verify that you're logged in:

bystro-vcf whoami

File Operations

Upload Files

Upload a file for annotation:

# Upload a single file bystro-vcf upload myfile.vcf # Upload with custom job name bystro-vcf upload myfile.vcf --name "My Analysis"# Upload multiple files bystro-vcf upload file1.vcf file2.vcf file3.vcf

Check Job Status

Monitor the progress of your jobs:

# List all jobs bystro-vcf jobs # Check specific job status bystro-vcf status <job-id># Watch job progress (updates automatically) bystro-vcf status <job-id> --watch

Download Results

Download completed annotation results:

# Download results for a specific job bystro-vcf download <job-id># Download to specific directory bystro-vcf download <job-id> --output /path/to/directory # Download specific file types only bystro-vcf download <job-id> --type annotation

Search and Query

Basic Search

Search your annotation results:

# Search by gene name bystro-vcf search --gene "BRCA1"# Search by chromosome and position bystro-vcf search --chr 17 --pos 43044295 # Search with multiple criteria bystro-vcf search --gene "BRCA1" --type "missense"

Export Search Results

Save search results to files:

# Export to CSV bystro-vcf search --gene "BRCA1" --output results.csv # Export to JSON bystro-vcf search --gene "BRCA1" --format json --output results.json

Configuration

View Configuration

Check your current CLI configuration:

bystro-vcf config --list

Set Configuration Options

Configure default settings:

# Set default output directory bystro-vcf config set output_dir /path/to/default/output # Set default file format bystro-vcf config set default_format csv

Help and Information

Get help for any command:

# General help bystro-vcf --help # Help for specific commands bystro-vcf upload --help bystro-vcf search --help bystro-vcf download --help