menu_bookOverview

gene.zip compresses genomic archives ~40% smaller while keeping instant, random access and a byte-exact restore. Run it from the CLI on your own machine, or spin up a managed compute instance next to your data in AWS, GCP, or Azure.

Quickstart

Install the CLI, authenticate, and run a no-cost pilot on a sample of your own archive.

# 1. install
curl -fsSL https://gene.zip/install.sh | bash

# 2. authenticate with your API key (from the dashboard)
gene login gz_live_…

# 3. compress a BAM — keeps instant access on the server
gene compress sample.bam -o sample.bcz --tier active

# 4. pull a region instantly, or restore the whole file
gene cat sample.bcz chr22:20000000-21000000 > region.bam
gene restore sample.bcz -o sample.bam

Install the CLI

The installer drops a single static gene binary on your PATH. No runtime or dependencies required.

macOS · Linux · WSL

curl -fsSL https://gene.zip/install.sh | bash

Windows

curl -fsSL https://gene.zip/install.cmd -o install.cmd && install.cmd && del install.cmd

Verify the install with gene --version.

Authentication

Create an API key on your dashboard, then save it with gene login.

# save your API key (stored in the OS config dir)
gene login gz_live_…

# point at a different server (optional)
gene login gz_live_… --server https://gene.zip

Credentials live in ~/.config/gene/config.toml (chmod 600).

Compress & restore

Pick a tier per workload — active for live pipelines, economy for archives, clinical for byte-exact regulatory retention.

# compress (BAM / CRAM / FASTQ / VCF)
gene compress cohort.bam -o cohort.bcz --tier economy

# choose a codec mode and (for ref-coded modes) a reference
gene compress cohort.bam -o cohort.bcz --mode 2bin --ref GRCh38.fa

# restore the original file
gene restore cohort.bcz -o cohort.bam

# list your uploads
gene list

Codec modes

The --mode flag trades quality fidelity for size. Sequence and alignment columns (1–10) are byte-exact in every mode; the modes differ in how base-quality scores (column 11) are stored. Ref-coded modes need a reference FASTA via --ref (or your server-side reference registry).

• 4bin — 2 bits/base quality (~2.2 Phred RMS). The clinical-tolerant default; no reference required.
• 8bin — 4 bits/base (~1.7 Phred RMS), research near-lossless; no reference required.
• 2bin — 1 bit/base, the smallest footprint; requires --ref.
• lossless — full Phred scores preserved (column 11 byte-exact); requires --ref.
• archive-strict — fully lossless including all aux tags (OQ kept); requires --ref.

Tiers (--tier) map to billing and retention; --mode controls the codec itself. If you omit --mode, gene.zip picks a sensible default for your tier.

Deep mode — BAM + FASTQ co-compression

If you keep both an aligned .bam and its source .fastq files, Deep mode stores them together in a single container. Reads that already exist in the BAM become tiny pointers instead of being compressed twice, so the combined file is dramatically smaller than compressing each separately — with a byte-exact restore of all inputs.

# co-compress a BAM with its paired-end FASTQ (R1 + R2)
gene deep cohort.bam reads_R1.fq.gz reads_R2.fq.gz -o cohort.bcz

# single-end, with a data-type profile and explicit reference
gene deep cohort.bam reads.fq.gz --type wes --ref GRCh38.fa

# restore — reconstructs the BAM and every FASTQ, byte-exact
gene restore cohort.bcz -o ./restored/

• Accepts 1–4 FASTQ streams (single-end, paired-end, or extra index reads).
• --bam-mode sets how the embedded BAM is stored (default lossless; lossless/2bin/archive-strict need a reference).
• --type tunes the FASTQ path for your assay: auto, amplicon, scrna, wes, rnaseq, cfdna, wgs.
• By default the reference is resolved from your server-side registry; pass --ref to name one explicitly.
• gene restore on a Deep upload writes the BAM and FASTQ(s) into the output directory.

Random region access

Pull any locus or time-slice straight from a .bcz — no full rehydration, no temp copy.

# stream a region as BAM to stdout
gene cat cohort.bcz chr1:1,000,000-1,050,000 > region.bam

# server-side metadata (sizes, ratio, checksums) without downloading
gene stat cohort.bcz

Your tools, unchanged

Pull regions straight into the tools you already run — real BAM out, no full rehydration. gene run also transparently restores any .bcz referenced in a command.

# pipe a region straight into samtools
gene cat cohort.bcz chr7:5000000-5001000 | samtools view -

# transparent mode: auto-restore any .bcz in the command's args
gene run -- samtools view cohort.bcz

# a FUSE virtual-BAM mount is coming soon:
#   gene mount cohort.bcz --as cohort.bam

Command reference

• gene login <api-key> [--server URL] — save credentials
• gene compress <in> -o <out.bcz> [--tier …] [--mode 4bin|8bin|lossless|2bin|archive-strict] [--ref <fasta>] — upload & compress
• gene deep <bam> <fq1> [fq2 …] -o <out.bcz> [--bam-mode …] [--type …] [--ref <fasta>] — co-compress a BAM + its FASTQ(s)
• gene restore <in.bcz> -o <out> — download & restore the original (a directory for Deep uploads)
• gene cat <in.bcz> <region> [-o file] — stream a region, no rehydration
• gene list · gene info <in.bcz> · gene stat <in.bcz> · gene delete <in.bcz>
• gene run -- <cmd> … — transparent restore of any .bcz in the args
• gene mount · gene verify · gene cloud … — coming soon

Add --help to any command for the full flag list.

Cloud instances

For multi-PB archives it is cheapest to compress next to the data. gene cloud launches a pre-built, right-sized instance in your own account, reads and writes object storage directly, and tears down when finished — you are billed by your cloud provider for the compute, plus your gene.zip tier for stored data.

• Runs in your account / VPC — data never leaves your cloud.
• Reads & writes s3://, gs://, and az:// URIs natively.
• Pre-tuned compute-optimized images per provider.

Note: the gene cloud CLI commands below are coming soon. The backend itself runs today on private Cloud Run (see the cloud-infra deploy scripts).

AWS

Launch from the gene.zip AMI (or via the CLI) and grant it read/write on your S3 bucket.

# launch a compute-optimized instance in your account
gene cloud launch --provider aws --region us-east-1 \
  --instance-type c6i.8xlarge --iam-role gene-s3-access

# compress straight from / to S3 (no local copy)
gene compress s3://my-bucket/in/cohort.bam \
  -o s3://my-bucket/bcz/cohort.bcz --tier economy

# tear the instance down when the job is finished
gene cloud terminate --provider aws

The instance needs an IAM role with s3:GetObject / s3:PutObject on the bucket. A ready-made policy is printed by gene cloud iam --provider aws.

Google Cloud

Authenticate with gcloud, then launch a Compute Engine instance and stream from GCS.

# one-time auth
gcloud auth login

# launch in your project
gene cloud launch --provider gcp --zone us-central1-a \
  --machine-type n2-standard-32 --project my-gcp-project

# compress from / to a GCS bucket
gene compress gs://my-bucket/in/cohort.bam \
  -o gs://my-bucket/bcz/cohort.bcz --tier economy

Grant the instance service account the roles/storage.objectAdmin role on the bucket.

Azure

Sign in with the Azure CLI, launch a VM, and read/write Blob Storage with az:// URIs.

# one-time auth
az login

# launch a compute-optimized VM
gene cloud launch --provider azure --location eastus \
  --vm-size Standard_F32s_v2 --resource-group gene-rg

# compress from / to a Blob container
gene compress az://mycontainer/in/cohort.bam \
  -o az://mycontainer/bcz/cohort.bcz --tier economy

Assign the VM's managed identity the Storage Blob Data Contributor role on the storage account.

Pricing tiers

Storage is billed per source PB·yr; compute is billed by your cloud provider. See the pricing & live calculator on the main site.

• Active — $28,000 / source PB·yr · live pipelines, instant reads.
• Economy — $19,000 / source PB·yr · analyzed cohorts & archives.
• Clinical — $42,000 / source PB·yr · byte-exact, BAA/HIPAA, audit.

Support

Questions, a pilot, or an enterprise quote? Reach the team from the main site or run gene support to open a ticket from the CLI.