Metadata-Version: 2.1
Name: austrakka
Version: 0.31.0
Summary: A CLI to interact with AusTrakka
Home-page: https://github.com/AusTrakka/austrakka2-cli
Author: AusTrakka Dev Team
Author-email: dev@austrakka.net.au
Project-URL: Bug Reports, https://github.com/austrakka/austrakka2-cli/issues
Project-URL: Source, https://github.com/austrakka/austrakka2-cli/
Keywords: sample setuptools development
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Build Tools
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.9, <4
Description-Content-Type: text/markdown
Requires-Dist: azure-identity
Requires-Dist: azure-keyvault-secrets
Requires-Dist: click
Requires-Dist: loguru
Requires-Dist: pandas
Requires-Dist: tabulate
Requires-Dist: cryptography
Requires-Dist: semver
Requires-Dist: httpx
Requires-Dist: biopython
Provides-Extra: dev

# AusTrakka CLI

Command line interface for AusTrakka V2.

## Installation

The AusTrakka CLI requires Python to run. Installation into a conda environment (see below) is the recommended method.

To install without conda, simply install with 
```
python -m pip install austrakka
```

You will need to set the environment variable `AT_URI` to the value provided by the AusTrakka team.
You may wish to add this to your `.bashrc` or `.zshrc` file.

To use the CLI, you must log in by setting the `AT_TOKEN` environment variable using the 
`austrakka auth user` command (see User Authentication, below). You may wish to configure 
a login command for convenience:
```
alias at-login="export AT_TOKEN=\$(austrakka auth user)"
```
You may wish to add this to your `.bashrc` or `.zshrc` file.

### Install into a conda environment (optional but recommended)

If you wish to create a conda environment named `austrakka` with the necessary environment 
variables set and the `at-login` alias, run:
```
conda create -n austrakka python=3.9
conda activate austrakka
python -m pip install austrakka
conda env config vars set AT_URI="[value provided by AusTrakka team]"
mkdir -p ${CONDA_PREFIX}/etc/conda/activate.d
echo "alias at-login=\"export AT_TOKEN=\\\$(austrakka auth user)\"" > ${CONDA_PREFIX}/etc/conda/activate.d/austrakka-alias.sh
```
Note that the last two lines are valid only for Linux/Mac and will not work on Windows.

You can then use
```
conda activate austrakka
at-login
```
in order to use the CLI. See _User Authentication_ below for alternative login methods.

### Updating the CLI

To update to the latest version, run 
```
python -m pip install --upgrade austrakka
```
If you have installed the CLI into a conda environment, you should first activate it with `conda activate austrakka`.

## Running the CLI

Before you can use the CLI, you must log in as described below, to allow the CLI to use your AusTrakka credentials. 
Your authorisation will expire after a period and you will need to log in again.

### User Authentication

Most users will want to use the CLI this way.

Set the following environment variable:
```
export AT_TOKEN=$(austrakka auth user)
```

If you have configured a login command as described above, you can instead run 
```
at-login
```

In Windows, you can set the AT_TOKEN environment variable by first running
```
austrakka auth user
```
to obtain a token string, and then running 
```
set AT_TOKEN=<output of previous command>
```
to set the environment variable.

For any of these methods, you should be directed to log in via a browser and enter a code to authorise the CLI.

### Process Authentication

This authentication mode is intended for long-term automated processes. Most users will not need it. 

To authenticate a process, you'll need to set the following environment variables:
```bash
AT_AUTH_PROCESS_ID
AT_AUTH_PROCESS_SECRET
```
Values for `AT_AUTH_PROCESS_ID` and `AT_AUTH_PROCESS_SECRET` will be provided to you by the AusTrakka team. Note that the secret value is sensitive.

Once these variables are set, run the following to authorise:
```
export AT_TOKEN=$(austrakka auth process)
```

### Using the CLI

The CLI has a subcommand structure. Run 
```
austrakka -h
```
to see available subcommands.

Run e.g. 
```
austrakka metadata -h
```
to see available commands to manipulate metadata.

Run e.g. 
```
austrakka metadata add -h
```
to see the usage of the `metadata add` command to upload metadata files.

## Environment Variables Reference

| Name             | Description                                                                                                                                     |
|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|
| `AT_TOKEN`       | AusTrakka auth token                                                                                                                            |
| `AT_URI`         | URI for API endpoint                                                                                                                            |
| `AT_ENV`         | Set to `dev` to log debugging                                                                                                                   |
| `AT_LOG`         | Set to `file` to redirecting logging to a temp file                                                                                             |
| `AT_CMD_SET`     | Set to `austrakka-admin` to display admin commands (these will not actually run successfully unless you have an appropriate role on the server) |
| `AT_VERIFY_CERT` | Verifies the cert used by the AusTrakka backend                                                                                                 |
| `AT_USE_HTTP2`   | Uses HTTP2 (experimental)                                                                                                                       |

All commands require `AT_URI` and `AT_TOKEN` to be set, except for `auth` commands.

## Project Structure

Each logical component of the system has its own package under `austrakka/`. Eg. `austrakka/job`.
Components that are children of another component are nested beneath. Eg. `austrakka/job/instance`.

Each component package contains the following files:

| File          | Purpose                                                                                                                                                                                                                                      |
|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `__init__.py` | Contains the Click commands offered by the component. Note that even if a component does not have any commands associated with it, this file must exist for the final build to include it.                                                   |
| `funcs.py`    | Any functions associated with the component.                                                                                                                                                                                                 |
| `opts.py`     | Click command line options associated with the component. Defined here so they can be reused across the CLI. Eg. `--species` is used for multiple commands. The species CLI option is defined here and imported to all commands that use it. |
| `enums.py`    | Any enumerations associated with the component.                                                                                                                                                                                              |
