Skip to content
MetaGEAR

MetaGEAR Tools (CLI)

MetaGEAR Tools is a small command-line wrapper (metagear) that installs the pipeline, configures defaults for your machine, manages reference databases, and launches workflows — so you can run a full metagenomic analysis without writing Nextflow.

→ schirmer-lab/metagear-tools ↗ — installer, CLI source, configuration templates, and full reference.

Why a wrapper

Nextflow and nf-core are powerful but have a learning curve. MetaGEAR Tools removes it by:

  • Detecting your hardware (CPUs, RAM) and setting resource limits to roughly 80% of available capacity, capped at 48 CPUs and 80 GB.
  • Installing the matching pipeline version alongside itself, so you don’t have to coordinate Nextflow + pipeline versions yourself.
  • Centralizing configuration under ~/.metagear/ with editable defaults.
  • Wrapping every workflow behind a one-word subcommand.

Prerequisites

Install

1. Run the installer.

Terminal window
curl -L https://get-metagear.schirmerlab.de | bash

Latest stable release, installed to ~/.metagear/.

2. (Optional) Pin a specific pipeline version.

Terminal window
curl -L https://get-metagear.schirmerlab.de | bash -s -- --pipeline 26.09.1

3. Review generated configuration in ~/.metagear/metagear.config and ~/.metagear/metagear.env. Adjust paths or resource limits if needed.

Basic usage

Terminal window
# Install reference databases (one-time, per machine)
metagear download_databases


# Run workflows
metagear qc_dna --input samples.csv
metagear microbial_profiles --input samples.csv


# Generate the launch script without executing it (useful for HPC)
metagear qc_dna --input samples.csv -preview

Input samplesheet:

sample,fastq_1,fastq_2
SAMPLE-01,/path/to/sample1_R1.fastq.gz,/path/to/sample1_R2.fastq.gz
SAMPLE-02,/path/to/sample2_R1.fastq.gz,/path/to/sample2_R2.fastq.gz

Presets

A preset runs several workflows in dependency order in one workspace, with --reuse-outputs switched on so each step picks up what the ones before it produced instead of recomputing:

PresetRuns
profilesmicrobial_profiles
genomesgenes → classification → mag → msp
microbiomegenomes + virus

→ Presets — what each one produces and what it costs.

Terminal window
metagear microbiome --input samples.csv --outdir results/


# show the plan without running anything
metagear microbiome --input samples.csv --outdir results/ --preview

If a step fails, the ones after it do not start. Fix what it reported and run the same command again — the steps that already finished resume from their own caches rather than starting over.

Running across machines

metagear cluster brings up a HyperQueue cluster across the machines listed in nodes.conf, so one cohort spreads over all of them:

Terminal window
metagear cluster up --pct 75      # also: ensure, down, status, restart, jobs, scratch, db, sweep
METAGEAR_MODE=cluster metagear microbiome --input samples.csv --outdir results/

METAGEAR_MODE=single, the default, keeps a run on the machine you launched it from.

Where to go next