# AusTrakka CLI
Command line interface for AusTrakka APIs.
## Getting started with the CLI
The AusTrakka CLI is a command-line interface for interacting with the AusTrakka platform.
To use it, you will need an AusTrakka account which grants the relevant roles and permissions in any organisation or
project you wish to interact with.
The CLI can be used for several purposes, including:
- Submitting sequence data
- Submitting metadata (sample, sequence and epidemiological metadata)
- Retrieving data for analysis
- Uploading analysis results (trees and analysis-derived metadata)
Note that currently, sequence data can only be submitted using the CLI, and cannot be submitted via the web interface.
## Installation
The CLI requires Python to run. If you would like to use conda to install Python, install the CLI, and save the necessary environment variables,
you can first install either Miniforge (https://github.com/conda-forge/miniforge) or Miniconda (https://docs.conda.io/en/latest/miniconda.html). We recommend Miniforge for most users.
Note that as a part of installing the CLI, you will need to set the `AT_URI` environment variable. This will be provided by the AusTrakka team.
### 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.12
conda activate austrakka
python -m pip install austrakka
conda env config vars set AT_URI=[VALUE]
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. These lines create an alias `at-login`
in the conda environment, which will log you in to the CLI.
You can then use
```
conda activate austrakka
at-login
```
in order to use the CLI. See _User Authentication_ below for alternative login methods.
### Install without conda
If you are using Windows, and are not a WSL or Powershell user, it is strongly recommended to use conda (see above).
To install without conda, simply install with
```
python -m pip install austrakka
```
You will need to set the environment variable `AT_URI`.
You can do this by running:
> #### Mac / Linux
>```
>export AT_URI=[VALUE]
>```
>You may wish to add this to your `.bashrc` or `.zshrc` file.
>#### Windows: Powershell
>```
>$Env:AT_URI = [VALUE]
>```
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).
> #### Mac / Linux
>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.
> #### Windows: Powershell
>You may wish to configure
>a login command for convenience:
>```
>Function at-login { $Env:AT_TOKEN = austrakka auth user }
>```
>You may wish to add this to your `config.ps1` file.
### 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`:
```
conda activate austrakka
python -m pip install --upgrade austrakka
```
## Logging in
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 log in to the CLI this way.
For any of these methods, you should be directed to log in via a browser and enter a code to authorise the CLI.
This browser-based login uses your institutional credentials, i.e. the same credentials you use to log in
to the AusTrakka web interface, and will authenticate you via your institution's identity provider.
>#### Mac / Linux
>If you have configured a login command as described above, you can simply run
>```
>at-login
>```
>
>Otherwise, you will need to set the `AT_TOKEN` environment variable. In a Mac or Linux environment you can run:
>```
>export AT_TOKEN=$(austrakka auth user)
>```
>#### Windows: Powershell
>
>```
>$Env:AT_TOKEN = austrakka auth user
>```
>#### Windows: Cmd
>
>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>
>```
>:w
> to set the environment variable.
### 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:
>#### Mac/Linux
>```
>export AT_TOKEN=$(austrakka auth process)
>```
>#### Windows: Powershell
>```
>$Env:AT_TOKEN = austrakka auth process
>```
>#### Windows: Cmd
>Set the `AT_TOKEN` environment variable by first running
>```
>austrakka auth process
>```
>to obtain a token string, and then running
>```
>set AT_TOKEN=<output of previous command>
>```
>to set the environment variable.
## 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_SKIP_CERT_VERIFY` | Skips verification of the cert used by the AusTrakka backend |
| `AT_SKIP_VERSION_CHECK` | Skips checking of new CLI version |
| `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": null,
"docs_url": null,
"requires_python": "<4,>=3.9",
"maintainer_email": null,
"keywords": "sample setuptools development",
"author": null,
"author_email": null,
"download_url": null,
"platform": null,
"description": "# AusTrakka CLI\n\nCommand line interface for AusTrakka APIs.\n\n## Getting started with the CLI\n\nThe AusTrakka CLI is a command-line interface for interacting with the AusTrakka platform.\nTo use it, you will need an AusTrakka account which grants the relevant roles and permissions in any organisation or \nproject you wish to interact with.\n\nThe CLI can be used for several purposes, including:\n\n- Submitting sequence data\n- Submitting metadata (sample, sequence and epidemiological metadata)\n- Retrieving data for analysis\n- Uploading analysis results (trees and analysis-derived metadata)\n\nNote that currently, sequence data can only be submitted using the CLI, and cannot be submitted via the web interface.\n\n## Installation\n\nThe CLI requires Python to run. If you would like to use conda to install Python, install the CLI, and save the necessary environment variables,\nyou can first install either Miniforge (https://github.com/conda-forge/miniforge) or Miniconda (https://docs.conda.io/en/latest/miniconda.html). We recommend Miniforge for most users.\n\nNote that as a part of installing the CLI, you will need to set the `AT_URI` environment variable. This will be provided by the AusTrakka team.\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.12\nconda activate austrakka\npython -m pip install austrakka\nconda env config vars set AT_URI=[VALUE]\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. These lines create an alias `at-login` \nin the conda environment, which will log you in to the CLI.\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### Install without conda\n\nIf you are using Windows, and are not a WSL or Powershell user, it is strongly recommended to use conda (see above).\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`.\nYou can do this by running:\n\n> #### Mac / Linux\n>```\n>export AT_URI=[VALUE]\n>```\n>You may wish to add this to your `.bashrc` or `.zshrc` file.\n\n>#### Windows: Powershell\n>```\n>$Env:AT_URI = [VALUE]\n>```\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). \n\n> #### Mac / Linux\n>You may wish to configure \n>a login command for convenience:\n>```\n>alias at-login=\"export AT_TOKEN=\\$(austrakka auth user)\"\n>```\n>You may wish to add this to your `.bashrc` or `.zshrc` file.\n\n> #### Windows: Powershell\n>You may wish to configure \n>a login command for convenience:\n>```\n>Function at-login { $Env:AT_TOKEN = austrakka auth user }\n>```\n>You may wish to add this to your `config.ps1` file.\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```\nconda activate austrakka\npython -m pip install --upgrade austrakka\n```\n\n## Logging in\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 log in to the CLI this way.\n\nFor any of these methods, you should be directed to log in via a browser and enter a code to authorise the CLI. \nThis browser-based login uses your institutional credentials, i.e. the same credentials you use to log in \nto the AusTrakka web interface, and will authenticate you via your institution's identity provider.\n\n>#### Mac / Linux\n>If you have configured a login command as described above, you can simply run\n>```\n>at-login\n>``` \n>\n>Otherwise, you will need to set the `AT_TOKEN` environment variable. In a Mac or Linux environment you can run:\n>```\n>export AT_TOKEN=$(austrakka auth user)\n>```\n\n>#### Windows: Powershell\n>\n>```\n>$Env:AT_TOKEN = austrakka auth user\n>```\n\n>#### Windows: Cmd\n>\n>Set the `AT_TOKEN` environment variable by first running\n>```\n>austrakka auth user\n>```\n>to obtain a token string, and then running \n>```\n>set AT_TOKEN=<output of previous command>\n>```\n>:w\n> to set the environment variable.\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\n>#### Mac/Linux\n>```\n>export AT_TOKEN=$(austrakka auth process)\n>```\n\n>#### Windows: Powershell\n>```\n>$Env:AT_TOKEN = austrakka auth process\n>```\n\n>#### Windows: Cmd\n>Set the `AT_TOKEN` environment variable by first running\n>```\n>austrakka auth process\n>```\n>to obtain a token string, and then running \n>```\n>set AT_TOKEN=<output of previous command>\n>```\n>to set the environment variable.\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_SKIP_CERT_VERIFY` | Skips verification of the cert used by the AusTrakka backend |\n| `AT_SKIP_VERSION_CHECK` | Skips checking of new CLI version |\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": null,
"summary": "A CLI to interact with a AusTrakka instance",
"version": "0.71.3",
"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": null,
"digests": {
"blake2b_256": "072c6fb8ac6eba202577b441be23fad37d32b548296457e31a429827e1a527d5",
"md5": "7057d6af5d2800837c176af18c227c7f",
"sha256": "c22e1fe710bb66fe2c2b705f785b743ff08d10a7b9ee005fe0168f12a8f48cb6"
},
"downloads": -1,
"filename": "austrakka-0.71.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7057d6af5d2800837c176af18c227c7f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.9",
"size": 108756,
"upload_time": "2025-07-22T00:22:34",
"upload_time_iso_8601": "2025-07-22T00:22:34.119960Z",
"url": "https://files.pythonhosted.org/packages/07/2c/6fb8ac6eba202577b441be23fad37d32b548296457e31a429827e1a527d5/austrakka-0.71.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-22 00:22:34",
"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
