Command-Line Interface

The bl command is BioLang's unified CLI. It handles script execution, the interactive REPL, the language server, syntax checking, packages, plugins, notebooks, source import, environment diagnostics, and upgrades.

bl run

Execute a BioLang script. This is the most common command:

# Run a script
bl run analysis.bl

# Run with verbose execution tracing
bl run analysis.bl --verbose

# Emit JSON Lines lifecycle and output events for tool integrations
bl run analysis.bl --events

bl repl

Launch the interactive Read-Eval-Print Loop. See the REPL page for full details:

# Start the REPL
bl repl

# Use the newline-delimited JSON protocol used by editor integrations
bl repl --json

bl lsp

Start the Language Server Protocol server. Typically launched by your editor, not run directly. See the LSP page for editor configuration:

# Start LSP server (communicates over stdin/stdout)
bl lsp

bl check

Parse one or more scripts without executing them. Each argument must be a file:

# Check a single file
bl check analysis.bl

# Check several files in one invocation
bl check src/main.bl tests/test_sequences.bl

Example output:

analysis.bl:12:5: error: undefined variable 'samplse' (did you mean 'samples'?)
1 error

bl add / bl remove

Add or remove locally installed plugins:

# Add a plugin from a local directory
bl add somer.align --path ../somer-align

# Remove a plugin
bl remove plot-tools

# List installed plugins
bl plugins

bl plugins

List installed plugins:

# List installed plugins
bl plugins

bl init

Create biolang.toml in the current directory:

# Create a new project in the current directory
bl init

# Override the package name
bl init --name my-analysis

bl install

Install dependencies from biolang.toml, a local package path, or Git:

# Install all project dependencies
bl install

# Install a local package
bl install ../packages/oric

# Install a package from Git
bl install oric --git https://github.com/example/oric.git --branch main

bl stats

Start from a scientific question and generate an editable statistics notebook. The selected method and input-column order are written into ordinary BioLang; the command does not inspect the values and silently choose a test.

# List supported questions, required columns, and methods
bl stats

# Generate a task-first notebook
bl stats compare measurements.csv --columns control,treated --method welch --output comparison.bln
bl notebook comparison.bln

The release includes the question-oriented statistics package. If a source/Cargo installation lacks companion packages, use bl install statistics. The optional rstats package adds a small set of familiar R-style names through bl install rstats; it is an MIT-licensed naming façade, not an R interpreter.

bl import

Convert Python, R, Jupyter, or R Markdown source into BioLang.

# Auto-detect the source format from its extension
bl import analysis.py --output analysis.bl --validate

# Emit the generated source and validation diagnostics as JSON
bl import notebook.ipynb --json

# Import stdin when a source name and format are supplied
bl import - --from r --name analysis.R --output analysis.bl

bl doctor / bl metadata

Inspect native and container capability readiness, or export the authoritative language metadata consumed by editors and documentation checks.

bl doctor
bl metadata --format json

bl convert

Delegate safe biological and tabular file conversion to the optional, separate bl-convert executable, which ships in the same release archive. Both must sit beside each other or be available on PATH:

bl convert input.csv output.tsv
bl convert variants.vcf.gz variants.bed.gz
bl convert tool list

See the BL Convert guide for installation, supported formats, local/WSL registration, BioContainers, detailed tool arguments, mounts, limits, and provenance reports.

Testing scripts

Write test functions with assert, call them from the script, and run the file with bl run:

bl run tests/test_sequences.bl

Example test file:

# tests/test_sequences.bl

fn test_gc_content() {
  let seq = dna"ATCGATCG"
  assert gc_content(seq) == 0.5, "GC content"
}

fn test_reverse_complement() {
  let seq = dna"ATCG"
  assert reverse_complement(seq) == dna"CGAT", "reverse complement"
}

fn test_transcribe() {
  let seq = dna"ATCG"
  let rna = seq |> transcribe()
  assert rna == rna"AUCG", "transcription"
}

test_gc_content()
test_reverse_complement()
test_transcribe()

Benchmark scripts

Use time_it around named functions and run the benchmark as a normal BioLang script:

bl run benchmarks/bench_kmers.bl

Example benchmark file:

# benchmarks/bench_kmers.bl

fn bench_kmer_count() {
  let seq = dna"ATCGATCGATCG" * 1000    # Repeat 1000 times
  seq |> kmer_count(21)
}

fn bench_gc_content() {
  let seq = dna"ATCGATCGATCG" * 10000
  seq |> gc_content()
}

time_it(bench_kmer_count)
time_it(bench_gc_content)

bl version

Show the current BioLang version and check for updates from GitHub Releases:

bl version
# BioLang v1.0.0

If a newer version is available, it will tell you to run bl upgrade.

bl upgrade

Download and install the latest BioLang release. Automatically detects your platform and downloads the correct binary from GitHub Releases:

bl upgrade

BioLang also checks for updates automatically in the background when you run bl run or bl repl. This check runs at most once per 24 hours, never blocks startup, and prints a one-line notice to stderr if a newer version is available. Disable with BIOLANG_NO_UPDATE_CHECK=1.

Global Options

The root command supports:

Environment Variables

# Run a notebook in the terminal
bl notebook analysis.bln

# Export to standalone HTML with syntax highlighting
bl notebook analysis.bln --export html

# Convert Jupyter .ipynb to .bln format
bl notebook experiment.ipynb --from-ipynb

# Convert .bln to Jupyter .ipynb format
bl notebook analysis.bln --to-ipynb

## Load Data
Read the FASTQ file and compute basic stats.

```biolang
let reads = read_fastq("sample.fq")
let stats = fastq_stats(reads)
println(stats)
```

## Filter Results

```bl
# @echo
let filtered = reads |> filter(|r| mean_phred(r.quality) > 25)
println(f"Kept {len(filtered)} of {len(reads)} reads")
```