lab-env

lab-env is a command-line toolkit for consistent research computing environments on macOS and Linux. It keeps personal host configuration outside the installed package and provides diagnostics without connecting to remote systems or changing shell startup files.

lab-env provides personal TOML configuration, shared and user-defined hosts, SSH and resumable rsync commands, local diagnostics, and managed Bash/Zsh shell integration. Shell setup preserves existing dotfiles and can be previewed before installation.

Installation

Python 3.11 or newer is supported. For an isolated command-line installation, use pipx:

pipx install lab-env

For development from a checkout:

python -m pip install -e ".[dev]"

Quick Start

lab --help
lab init
lab hosts
lab doctor
lab connect HOST
lab pull HOST REMOTE_PATH [LOCAL_PATH]
lab push HOST LOCAL_PATH REMOTE_PATH
lab tecplot export figure.lay
lab shell preview
lab shell install
lab shell status

After lab shell install, the legacy-compatible shortcut exports PNG images at 2000 pixels wide by default:

lay2pic figure.lay

By default, configuration is stored at ~/.config/lab-env/config.toml. XDG_CONFIG_HOME is honored when set. Use an explicit path for testing or multiple environments:

lab --config ./example.toml init
lab --config ./example.toml doctor

lab init refuses to overwrite an existing file. lab shell install is the only current command that modifies shell startup configuration. Preview the exact paths and managed block first with lab shell preview.

Documentation

The user guide is available at uahypersonics.github.io/lab-env. Development and contribution instructions are in CONTRIBUTING.md.

License

lab-env is distributed under the GNU General Public License v3.0 or later.