Metadata-Version: 2.4
Name: lab-env
Version: 0.0.8
Summary: Tools for consistent research computing environments
Author-email: Christoph Hader <christoph.hader@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/uahypersonics/lab-env
Project-URL: Repository, https://github.com/uahypersonics/lab-env
Project-URL: Documentation, https://uahypersonics.github.io/lab-env
Project-URL: Issues, https://github.com/uahypersonics/lab-env/issues
Keywords: research-computing,hpc,environment,ssh,shell
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Requires-Dist: zensical; extra == "dev"
Dynamic: license-file

# lab-env

[![Test](https://github.com/uahypersonics/lab-env/actions/workflows/test.yml/badge.svg)](https://github.com/uahypersonics/lab-env/actions/workflows/test.yml)
[![Docs](https://img.shields.io/badge/docs-zensical-blue)](https://uahypersonics.github.io/lab-env/)
[![License](https://img.shields.io/badge/license-GPL--3.0--or--later-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-≥3.11-blue.svg)](https://www.python.org/downloads/)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)

`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](https://pipx.pypa.io/):

```bash
pipx install lab-env
```

For development from a checkout:

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

## Quick Start

```bash
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:

```bash
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:

```bash
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](https://uahypersonics.github.io/lab-env).
Development and contribution instructions are in [CONTRIBUTING.md](CONTRIBUTING.md).

## License

`lab-env` is distributed under the
[GNU General Public License v3.0 or later](LICENSE).
