Metadata-Version: 2.4
Name: lab-env
Version: 0.0.5
Summary: Tools for consistent research computing environments
Author-email: Christoph Hader <chader@arizona.edu>
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.

## Status

The initial foundation implements:

- `lab init` to create personal TOML configuration safely;
- `lab hosts` to inspect configured SSH aliases;
- `lab doctor` to validate configuration, shell support, and local clients;
- `lab connect` to open SSH or run a remote command;
- `lab pull` and `lab push` for resumable rsync transfers;
- `lab shell preview/install/status/uninstall` for managed Bash or Zsh aliases and startup integration;
- an explicit global `--config` option for isolated or alternate setups.

Navigation shortcuts, optional shell features, and study orchestration are
planned but are not implemented yet.

## 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 shell preview
lab shell install
lab shell status
```

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).
