Command-Line Interface

The bl command is BioLang's unified CLI. It handles script execution, the interactive REPL, the language server, code formatting, type checking, project management, plugin management, testing, and benchmarking. Install it once and you have everything you need.

bl run

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

# Run a script
bl run analysis.bl

# Run with arguments (accessible via args() builtin)
bl run pipeline.bl --input reads.fastq --output results/

# Run from stdin
echo 'print("hello")' | bl run -

# Run with verbose output (shows timing info)
bl run analysis.bl --verbose

# Run with a specific data directory
bl run analysis.bl --data-dir /mnt/data/

# Dry run — parse and type-check without executing
bl run analysis.bl --dry-run

bl repl

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

# Start the REPL
bl repl

# Start with a script pre-loaded into the environment
bl repl --load setup.bl

# Start with specific plugins enabled
bl repl --plugin my-plugin

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

# Start with debug logging
bl lsp --log-level debug --log-file /tmp/bl-lsp.log

bl check

Type-check and validate a script without executing it. Reports errors and warnings:

# Check a single file
bl check analysis.bl

# Check all .bl files in a directory
bl check src/

# Check with strict mode (warnings become errors)
bl check --strict analysis.bl

# Output in JSON format (for CI integration)
bl check --format json analysis.bl

Example output:

analysis.bl:12:5: error: undefined variable 'samplse' (did you mean 'samples'?)
analysis.bl:24:1: warning: unused variable 'temp_result'
analysis.bl:31:10: error: type mismatch: expected DNA, got RNA

2 errors, 1 warning

bl fmt

Format BioLang source code according to the standard style. Handles indentation, spacing, pipe chain formatting, and comment alignment:

# Format a file in place
bl fmt analysis.bl

# Format all .bl files in current directory
bl fmt .

# Check if files are formatted (exit code 1 if not — useful in CI)
bl fmt --check analysis.bl

# Print formatted output to stdout instead of modifying the file
bl fmt --stdout analysis.bl

# Format with specific options
bl fmt --indent-width 4 --max-line-length 100 analysis.bl

bl add / bl remove

Manage project dependencies (plugins):

# Add a plugin to the current project
bl add plot-tools
bl add stats-extra

# Add a specific version
bl add plot-tools@1.2.0

# Add from a git repository
bl add git:https://github.com/user/bl-plugin.git

# Add from a local path
bl add path:../my-plugin

# Remove a plugin
bl remove plot-tools

# List installed plugins
bl plugins

bl plugins

List, search, and manage plugins:

# List installed plugins
bl plugins

# List with details
bl plugins --verbose

# Search the plugin registry
bl plugins search "statistics"

# Show details for a specific plugin
bl plugins info plot-tools

# Update all plugins
bl plugins update

# Update a specific plugin
bl plugins update plot-tools

bl init

Initialize a new BioLang project with standard directory structure:

# Create a new project in the current directory
bl init

# Create a new project in a named directory
bl init my-analysis

# Initialize with a specific template
bl init --template rnaseq-pipeline my-project
bl init --template variant-calling my-project

Generated project structure:

my-analysis/
  biolang.toml       # Project manifest
  src/
    main.bl          # Entry point
  data/              # Input data directory
  results/           # Output directory
  tests/
    test_main.bl     # Test file

bl install

Install all dependencies listed in biolang.toml:

# Install all project dependencies
bl install

# Install with verbose output
bl install --verbose

# Install and lock versions
bl install --lock

bl test

Run tests defined in .bl files. Test functions are any function whose name starts with test_:

# Run all tests
bl test

# Run tests in a specific file
bl test tests/test_pipeline.bl

# Run tests matching a pattern
bl test --filter "test_gc_content"

# Run with verbose output (shows each test name)
bl test --verbose

Example test file:

# tests/test_sequences.bl

let test_gc_content = || {
  let seq = dna"ATCGATCG"
  assert(seq |> gc_content() == 0.5)
}

let test_reverse_complement = || {
  let seq = dna"ATCG"
  assert(seq |> reverse_complement() == dna"CGAT")
}

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

bl bench

Run benchmarks to measure performance of BioLang code. Benchmark functions are prefixed with bench_:

# Run all benchmarks
bl bench

# Run benchmarks in a specific file
bl bench benchmarks/bench_kmers.bl

# Run with specific iteration count
bl bench --iterations 100

# Output in JSON format
bl bench --format json

Example benchmark file:

# benchmarks/bench_kmers.bl

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

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

bl version

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

bl version
# BioLang v0.1.0
#
# Checking for updates... up to date.

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 v0.1.0
#
# Checking for latest release... v0.2.0 found.
# Downloading biolang-linux-x86_64.tar.gz...
# Extracting...
# Replacing /usr/local/bin/bl...
# Upgraded to BioLang v0.2.0!

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

These flags are available on all bl subcommands:

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)
print(stats)
```

## Filter Results

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