# 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_LOG_LEVEL` | Level of logging |
| `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. |
Raw data
{
"_id": null,
"home_page": "https://github.com/AusTrakka/austrakka2-cli",
"name": "austrakka",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9, <4",
"maintainer_email": "",
"keywords": "sample setuptools development",
"author": "AusTrakka Dev Team",
"author_email": "dev@austrakka.net.au",
"download_url": "",
"platform": null,
"description": "# AusTrakka CLI\n\nCommand line interface for AusTrakka V2.\n\n## Installation\n\nThe AusTrakka CLI requires Python to run. Installation into a conda environment (see below) is the recommended method.\n\nTo install without conda, simply install with \n```\npython -m pip install austrakka\n```\n\nYou will need to set the environment variable `AT_URI` to the value provided by the AusTrakka team.\nYou may wish to add this to your `.bashrc` or `.zshrc` file.\n\nTo use the CLI, you must log in by setting the `AT_TOKEN` environment variable using the \n`austrakka auth user` command (see User Authentication, below). You may wish to configure \na login command for convenience:\n```\nalias at-login=\"export AT_TOKEN=\\$(austrakka auth user)\"\n```\nYou may wish to add this to your `.bashrc` or `.zshrc` file.\n\n### Install into a conda environment (optional but recommended)\n\nIf you wish to create a conda environment named `austrakka` with the necessary environment \nvariables set and the `at-login` alias, run:\n```\nconda create -n austrakka python=3.9\nconda activate austrakka\npython -m pip install austrakka\nconda env config vars set AT_URI=\"[value provided by AusTrakka team]\"\nmkdir -p ${CONDA_PREFIX}/etc/conda/activate.d\necho \"alias at-login=\\\"export AT_TOKEN=\\\\\\$(austrakka auth user)\\\"\" > ${CONDA_PREFIX}/etc/conda/activate.d/austrakka-alias.sh\n```\nNote that the last two lines are valid only for Linux/Mac and will not work on Windows.\n\nYou can then use\n```\nconda activate austrakka\nat-login\n```\nin order to use the CLI. See _User Authentication_ below for alternative login methods.\n\n### Updating the CLI\n\nTo update to the latest version, run \n```\npython -m pip install --upgrade austrakka\n```\nIf you have installed the CLI into a conda environment, you should first activate it with `conda activate austrakka`.\n\n## Running the CLI\n\nBefore you can use the CLI, you must log in as described below, to allow the CLI to use your AusTrakka credentials. \nYour authorisation will expire after a period and you will need to log in again.\n\n### User Authentication\n\nMost users will want to use the CLI this way.\n\nSet the following environment variable:\n```\nexport AT_TOKEN=$(austrakka auth user)\n```\n\nIf you have configured a login command as described above, you can instead run \n```\nat-login\n```\n\nIn Windows, you can set the AT_TOKEN environment variable by first running\n```\naustrakka auth user\n```\nto obtain a token string, and then running \n```\nset AT_TOKEN=<output of previous command>\n```\nto set the environment variable.\n\nFor any of these methods, you should be directed to log in via a browser and enter a code to authorise the CLI.\n\n### Process Authentication\n\nThis authentication mode is intended for long-term automated processes. Most users will not need it. \n\nTo authenticate a process, you'll need to set the following environment variables:\n```bash\nAT_AUTH_PROCESS_ID\nAT_AUTH_PROCESS_SECRET\n```\nValues 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.\n\nOnce these variables are set, run the following to authorise:\n```\nexport AT_TOKEN=$(austrakka auth process)\n```\n\n### Using the CLI\n\nThe CLI has a subcommand structure. Run \n```\naustrakka -h\n```\nto see available subcommands.\n\nRun e.g. \n```\naustrakka metadata -h\n```\nto see available commands to manipulate metadata.\n\nRun e.g. \n```\naustrakka metadata add -h\n```\nto see the usage of the `metadata add` command to upload metadata files.\n\n## Environment Variables Reference\n\n| Name | Description |\n|------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|\n| `AT_TOKEN` | AusTrakka auth token |\n| `AT_URI` | URI for API endpoint |\n| `AT_LOG_LEVEL` | Level of logging |\n| `AT_LOG` | Set to `file` to redirecting logging to a temp file |\n| `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) |\n| `AT_VERIFY_CERT` | Verifies the cert used by the AusTrakka backend |\n| `AT_USE_HTTP2` | Uses HTTP2 (experimental) |\n\nAll commands require `AT_URI` and `AT_TOKEN` to be set, except for `auth` commands.\n\n## Project Structure\n\nEach logical component of the system has its own package under `austrakka/`. Eg. `austrakka/job`.\nComponents that are children of another component are nested beneath. Eg. `austrakka/job/instance`.\n\nEach component package contains the following files:\n\n| File | Purpose |\n|---------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `__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. |\n| `funcs.py` | Any functions associated with the component. |\n| `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. |\n| `enums.py` | Any enumerations associated with the component. |\n",
"bugtrack_url": null,
"license": "",
"summary": "A CLI to interact with AusTrakka",
"version": "0.35.1",
"project_urls": {
"Bug Reports": "https://github.com/austrakka/austrakka2-cli/issues",
"Homepage": "https://github.com/AusTrakka/austrakka2-cli",
"Source": "https://github.com/austrakka/austrakka2-cli/"
},
"split_keywords": [
"sample",
"setuptools",
"development"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3f1648ddfccbf1b07dab297e0f75e4ada526574db129059efd401d099736a621",
"md5": "14d2178ebf49fbd3ea96f58a2dff1d40",
"sha256": "c903ed6db1e4fbe01b0135981bcfa491180583e79f39a31d6ffa814e1519ecbf"
},
"downloads": -1,
"filename": "austrakka-0.35.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "14d2178ebf49fbd3ea96f58a2dff1d40",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9, <4",
"size": 74048,
"upload_time": "2023-09-18T10:57:46",
"upload_time_iso_8601": "2023-09-18T10:57:46.788882Z",
"url": "https://files.pythonhosted.org/packages/3f/16/48ddfccbf1b07dab297e0f75e4ada526574db129059efd401d099736a621/austrakka-0.35.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-18 10:57:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AusTrakka",
"github_project": "austrakka2-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "austrakka"
}
JSON
