austrakka


Nameaustrakka JSON
Version 0.65.0 PyPI version JSON
download
home_pagehttps://github.com/AusTrakka/austrakka2-cli
SummaryA CLI to interact with AusTrakka
upload_time2024-10-24 11:33:01
maintainerNone
docs_urlNone
authorAusTrakka Dev Team
requires_python<4,>=3.9
licenseNone
keywords sample setuptools development
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # 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_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": "AusTrakka Dev Team",
    "author_email": "dev@austrakka.net.au",
    "download_url": null,
    "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_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 AusTrakka",
    "version": "0.65.0",
    "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": "508eace478e6e46a2c015b1bd7b164b01363cd351281def4a665cdc998d118eb",
                "md5": "c17f6ddf42c392556e583288f513f660",
                "sha256": "1d186b5d07f3bc91982d0f5117fb0441099c0df494928ff093a886073dd39ac2"
            },
            "downloads": -1,
            "filename": "austrakka-0.65.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "c17f6ddf42c392556e583288f513f660",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<4,>=3.9",
            "size": 106715,
            "upload_time": "2024-10-24T11:33:01",
            "upload_time_iso_8601": "2024-10-24T11:33:01.510568Z",
            "url": "https://files.pythonhosted.org/packages/50/8e/ace478e6e46a2c015b1bd7b164b01363cd351281def4a665cdc998d118eb/austrakka-0.65.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-10-24 11:33:01",
    "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"
}
        
Elapsed time: 0.41363s