BioDex

BioDex is a terminal-native species atlas: part field guide, part taxonomy browser, part cached research notebook.

It opens into a fast three-pane TUI with species portraits, range maps, lineage history, compact biological stats, and two ways to browse: a curated A-Z species list or a taxonomy tree.

Demo

Click the preview to open the full demo clip.

Highlights

• Browse a curated 100-species starter pack with bundled local cached profiles
• Move through species alphabetically, with auto-loading as you pause on entries
• Switch into taxonomy mode when you want to explore by kingdom, phylum, class, order, family, genus, and species
• View portraits, range maps, lineage, genome metadata, conservation status, and life-history stats in one terminal screen
• Reuse cached SQLite data so repeat browsing stays fast and mostly offline

Install

Install from crates.io:

cargo install biodex

If your system has a small /tmp quota, point Cargo at directories with more space:

mkdir -p ~/.cargo-install-tmp ~/.cargo-install-target
TMPDIR=~/.cargo-install-tmp \
CARGO_TARGET_DIR=~/.cargo-install-target \
cargo install biodex

Then run it:

biodex

To download portraits and raster range maps for the starter browsing pack after install:

biodex --prefetch

That is the simplest one-command way to materialize the default hot cache locally.

Build from source when you want to work on the project locally:

git clone https://github.com/Jakeelamb/BioDex.git
cd BioDex
cargo build --release

Run the optimized binary:

./target/release/biodex

Optionally install it locally so biodex is available on your PATH:

cargo install --path .

Open a specific species:

./target/release/biodex "Homo sapiens"

Run from source without keeping a release binary:

cargo run --release -- "Panthera leo"

Requirements

• Rust toolchain
• A modern terminal
• An image-capable terminal for portraits and raster range maps; otherwise BioDex falls back to text placeholders

Common Commands

The examples below assume biodex is on your PATH. If not, use ./target/release/biodex from the repo root.

• biodex: open the TUI at Animalia
• biodex "Ailuropoda melanoleuca": open a species directly
• biodex --text "Homo sapiens": print species data without launching the TUI
• biodex --prefetch: seed the default 100-species hot cache
• biodex --prefetch-animals: refresh curated Animalia candidates and cache media
• biodex --import-backbone: import the GBIF backbone for offline taxonomy search, roughly 200 MB
• biodex --cache-all-rich: run a long resumable sweep for richer cached species rows
• biodex --stats: show local cache statistics

Controls

• ↑/↓ or j/k: move through the active navigator
• t: switch between the A-Z species list and taxonomy browser
• Enter / l / →: open the selected entry
• h / ←: move up a taxonomy level
• /: search
• r: refresh from live sources
• f: toggle saved status
• ?: help
• q / Esc: quit or close the active panel

Data Sources

BioDex merges public data from several sources and caches the result locally:

Caching

BioDex stores its local database and media cache under biodex app directories.

The published crate ships with a bundled starter SQLite database for the curated 100-species pack, so species profiles and taxonomy browsing are available immediately after install.

Portraits and raster range maps are still cached lazily on demand. They are not bundled into the crate because shipping third-party media would make the package dramatically larger and complicate downstream licensing.

If you want the starter-pack media cached immediately after install, run:

biodex --prefetch

This downloads and stores the default browsing pack locally from the upstream public data sources used by BioDex. Those fetched media assets remain subject to the original source terms and attribution requirements; BioDex does not relicense them.

Offline taxonomy search depends on the GBIF backbone import:

biodex --import-backbone

That import is larger than the bundled starter cache, but it makes search and taxonomy navigation much more useful without repeated network calls.

Status

BioDex is early but usable. The current focus is a fast, polished terminal atlas with strong cached browsing. Future directions include broader curated packs, better offline packaging, and an optional nostalgic desktop/window-shell presentation.

License

BioDex source code is licensed under the MIT License. See LICENSE.

Species data, images, range maps, and other third-party content fetched or cached by BioDex are not relicensed by this repository and remain subject to the terms of their original sources.