Metadata-Version: 2.1
Name: terralab-cli
Version: 0.0.3
Summary: Command line interface for interacting with the Terra Scientific Pipelines Service, or Teaspoons.
Author: Terra Scientific Services
Author-email: teaspoons-developers@broadinstitute.org
Requires-Python: >=3.9,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: PyJWT (>=2.9.0,<3.0.0)
Requires-Dist: click (>=8.1.7,<9.0.0)
Requires-Dist: oauth2-cli-auth (>=1.5.0,<2.0.0)
Requires-Dist: python-dotenv (>=1.0.1,<2.0.0)
Requires-Dist: terra-scientific-pipelines-service-api-client (==0.0.0)
Description-Content-Type: text/markdown

# Teaspoons CLI

[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=DataBiosphere_terra-scientific-pipelines-service-cli&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=DataBiosphere_terra-scientific-pipelines-service-cli)


## Python CLI structure
The CLI code is structured as follows:
```
terra-scientific-pipelines-service-cli
├── terralab
│   └── commands
│   │   └── __init__.py
│   │   └── auth_commands.py
│   │   └── pipelines_commands.py
│   └── logic
│   │   └── __init__.py
│   │   └── auth_logic.py
│   │   └── pipelines_logic.py
│   └── __init__.py
│   └── auth_helper.py
│   └── cli.py
│   └── client.py
│   └── config.py
│   └── teaspoons
├── tests
│   └── commands
│   │   └── test_auth_commands.py
│   │   └── test_pipelines_commands.py
│   └── logic
│   │   └── test_auth_logic.py
│   │   └── test_pipelines_logic.py
│   └── __init__.py
│   └── auth_helper.py
│   └── cli.py
│   └── client.py
│   └── config.py
│   └── terralab
├── .gitignore
├── .terralab-cli-config
├── poetry.lock
├── pyproject.toml
├── README.md
```

In the `terralab` directory, we have the following files and subdirectories:
- `auth_helper.py` contains the code for authenticating with the Terra Scientific Pipelines Service (Terra, via b2c).
- `cli.py` assembles the CLI sub-modules that are defined in `commands/`.
- `client.py` contains the code for wrapping API calls to the Terra Scientific Pipelines Service.
- `config.py` contains the code for managing the CLI configuration via environment variables.
- `terralab` is the entrypoint for the CLI. It contains the main function that is called when the CLI is run.
- `utils.py` contains utility functions that are used across the CLI.
- The `commands` directory contains the CLI sub-modules. This is effectively the controller layer for the CLI.
- The `logic` directory contains the business logic for the CLI, including calling Terra Scientific Pipelines Service APIs via the thin `teaspoons_client`, 
which is autogenerated and published by the [Terra Scientific Pipelines Service repository](https://github.com/DataBiosphere/terra-scientific-pipelines-service).

In the `tests` directory, we have test files that can be run with pytest.

## Using the CLI
For now, the CLI requires poetry to be installed to run. See the [Development](#development) section for instructions on how to install poetry.

To run the CLI, navigate to the root (terra-scientific-pipelines-service-cli) directory and run the following command:
```bash
./terralab COMMAND [ARGS]
```

For example, to authenticate with Terralab (via Terra b2c), run the following command:
```bash
./terralab auth login
```

To list the pipelines you can run using Terralab, run the following command:
```bash
./terralab pipelines list
```

See WIP documentation for the CLI [here](https://docs.google.com/document/d/1ovbcHCzdyuC8RjFfkVJZiuDTQ_UAVrglSxSGaZwppoY/edit?tab=t.0#heading=h.jfsr3j3x0zjr).


## Development
You'll need to have poetry installed to manage python dependencies. Instructions for installing poetry can be found [here](https://python-poetry.org/docs/).

To install the CLI locally, run the following commands from the root project directory:
```
poetry lock      # only needed if you updated dependencies in pyproject.toml
poetry install
```
You do not need to re-run these commands each time you update code locally, unless you've added dependencies in pyproject.toml.

If you do update dependencies in `pyproject.toml`, run `poetry lock` and check in the resulting changes to `poetry.lock` along with the rest of 
your code changes.

To run the tests, execute the following command from the root project (terra-scientific-pipelines-service-cli) directory:
```bash
poetry run pytest
```

To run tests with a coverage report printed to the terminal:
```bash
poetry run pytest --cov-report term --cov=terralab
```

To run the formatter, execute the following command from the root project directory:
```bash
poetry run black .
```

To run the linter with fixes, execute the following command from the root project directory:
```bash
poetry run ruff check --fix
```
To run the linter as a check without fixes, omit the `--fix` flag.

