BL Convert

bl-convert is BioLang's optional, separate command-line companion for safe file conversion and reproducible execution of common bioinformatics tools. Built-in conversions run without Docker. External tools can use an existing native or WSL installation, or an explicitly installed container image.

Safe output

Parse, validate, write temporarily, then move atomically.

No hidden installs

Container images are pulled only by an explicit install command.

Auditable runs

Save the backend, version, arguments, limits, and timing as JSON.

Install

bl-convert is included in every release archive beside bl. To build it from a BioLang source checkout instead:

cargo install --path crates/bl-convert

bl-convert --version
bl-convert formats

The executable remains independent of bl. When both executables are beside each other or on PATH, BioLang provides a delegating shortcut:

bl convert input.csv output.tsv
bl convert formats
bl convert tool list

Built-in conversions

These conversions need no external program or container runtime:

Input	Output	Behaviour
CSV / TSV	CSV, TSV, JSON	Correct quoting; preserves string identifiers such as `001`.
JSON objects	CSV, TSV, JSON	Nested values become JSON text in tabular cells.
BED	BED	Validates coordinates and normalizes records. `track`/`browser` headers pass through; a contig named `track...` is data.
VCF	BED6	Converts 1-based VCF positions to 0-based BED starts.
GFF3 / GTF	BED6	Converts inclusive coordinates to half-open BED intervals.
FASTA	FASTA	Validates records and applies the requested line width.
FASTQ	FASTQ, FASTA	Normalizes four-line records and keeps the `+` line description; reports quality loss for FASTA.

Add .gz for gzip input or output. .bgz input is readable, but BGZF output is rejected until it can be written with a true indexed BGZF writer. JSON input is materialized to discover all object keys; other supported record types stream with bounded buffers.

Convert and inspect

bl-convert inspect variants.vcf.gz
bl-convert convert samples.csv samples.tsv
bl-convert convert variants.vcf.gz variants.bed.gz
bl-convert convert genes.gff3 genes.bed --feature gene
bl-convert convert reads.fastq reads.fasta --report conversion.json

Override extension detection and preview a conversion when needed:

bl-convert inspect unknown.data --from bed --json
bl-convert convert incoming.data normalized.tsv --from csv --to tsv --dry-run

Conversion option	Purpose
--force	Replace an existing output.
--dry-run	Parse and convert without creating output.
--json	Print a machine-readable result.
--report FILE	Save records, warnings, and information loss as JSON.
--feature TYPE	Keep one GFF/GTF feature, such as `gene` or `exon`.
--name-attribute NAME	Choose the GFF/GTF attribute used for the BED name.
--line-width N	Set FASTA wrapping; default 80.

Choose an external-tool backend

bl-convert doctor
bl-convert doctor --json
bl-convert tool catalog
bl-convert tool list

Prefer an existing local installation when it is already managed by your system. Use WSL when the tool is installed there. Use a container for a pinned, isolated backend, or Apptainer/Singularity on a compatible HPC system.

Register a native or WSL tool

# Find an existing native executable on PATH
bl-convert tool register samtools --local

# Record one exact executable
bl-convert tool register samtools --path C:\tools\samtools.exe

# Verify an existing tool inside WSL
bl-convert tool register samtools --wsl
bl-convert tool register samtools --wsl --distribution Ubuntu

Registration verifies and records the executable; it does not install or copy it. Only one of --local, --path, or --wsl may be used.

Explicitly install a container tool

bl-convert tool install samtools
bl-convert tool install bcftools --runtime podman
bl-convert tool status samtools

Docker, Podman, Apptainer, and Singularity are supported. Finding a Docker command does not mean its daemon is running; doctor checks readiness. Images use pinned BioContainers tags, never latest.

Pass any upstream parameter

Options before -- configure BL Convert. Everything after -- is passed directly to the selected program as separate arguments, without a shell:

bl-convert tool run samtools --workdir C:\analysis --cpus 4 --memory 8g --report samtools-run.json -- view -@ 4 -b -o reads.bam reads.sam

Multi-command images allow only their catalogued executables:

bl-convert tool run htslib --executable tabix --workdir C:\analysis -- -p vcf variants.vcf.gz

A tested samtools tutorial sequence

BL Convert's opt-in integration suite executes this sequence against a tiny real SAM file through the pinned samtools container. It asserts biological outputs, not only successful exit codes:

bl-convert tool run samtools --workdir ./tutorial -- view -bo aln.bam tutorial.sam
bl-convert tool run samtools --workdir ./tutorial -- sort -@ 2 -m 1M -o aln.sorted.bam aln.bam
bl-convert tool run samtools --workdir ./tutorial -- index aln.sorted.bam
bl-convert tool run samtools --workdir ./tutorial -- quickcheck -v aln.sorted.bam
bl-convert tool run samtools --workdir ./tutorial -- view -c aln.sorted.bam
bl-convert tool run samtools --workdir ./tutorial -- view aln.sorted.bam chr1:10-24
bl-convert tool run samtools --workdir ./tutorial -- flagstat -O json aln.sorted.bam
bl-convert tool run samtools --workdir ./tutorial -- stats aln.sorted.bam

The same test covers FASTA indexing, a reference-backed CRAM round trip, paths with spaces, invalid options, malformed SAM input, provenance, and bl convert delegation. Keep shell redirection outside the -- boundary, and prefer samtools' -o FILE for binary output on Windows.

Files, mounts, and isolation

For a container run, --workdir is mounted at /data and becomes the process working directory. Refer to files there using relative paths. Mount references separately with a container path:

bl-convert tool run samtools --workdir C:\analysis --mount C:\refs=/refs:ro -- view -T /refs/hg38.fa reads.cram

--mount accepts HOST=/container/path[:ro|:rw] and may be repeated. It defaults to read-only. Docker and Podman networking is disabled unless --allow-network is given. Use --read-only when the working directory itself should not be writable.

Native and WSL programs are not sandboxes. Container-only mounts, CPU limits, memory limits, and network controls are rejected for those backends rather than reported as protections that cannot be enforced.

Provenance and removal

A run report records the backend, exact image or executable, detected version, selected command, arguments, mounts, resource settings, network policy, exit code, and elapsed time. Keep it with the output and analysis script.

bl-convert tool run samtools --workdir ./analysis --report samtools-view.json -- view -b reads.sam

# Forget a registration but retain the external software/image
bl-convert tool remove samtools

# Also remove a managed container image
bl-convert tool remove samtools --purge

Tool state is stored below ~/.biolang/convert/tools.json, or below BL_CONVERT_HOME when that variable is set. Removing a native or WSL registration never uninstalls the external program.

Curated tools

The initial catalog includes samtools, bcftools, HTSlib (bgzip and tabix), bedtools, seqkit, fastp, FastQC, MultiQC, cutadapt, minimap2, Bowtie2, and STAR. Run bl-convert tool catalog --json for the exact current images, tags, executables, and version checks.

Troubleshooting

No runtime is ready: start Docker/Podman, install a suitable runtime, or register a local/WSL tool.
Tool is not installed: the catalog knows it, but you must choose a backend with tool register or tool install.
Output exists: review the path, then use --force for conversion or --force-report for a run report.
Container cannot find a file: use a relative path under --workdir, or mount the host directory and use its container path.
Tool option rejected: place all external-tool arguments after --.

Scope and licences

BL Convert and BioLang are MIT licensed. External programs and images retain their own licences and run across a process/container boundary; their code is not linked into BioLang. Check each tool's licence and citation requirements when distributing images or publishing results.

The generic runner exposes a registered tool's full command line. Typed wrappers such as bl-convert sort, and built-in BAM, Parquet, or indexed BGZF conversion, are not currently implemented.