diff --git a/mars-cli/README.md b/mars-cli/README.md index 8163409..e8c55ff 100644 --- a/mars-cli/README.md +++ b/mars-cli/README.md @@ -1,9 +1,11 @@ # Installing the mars-cli +This installation procedure describes a typical Linux installation. This application can perfectly work on Windows and MacOS but some of the steps might be different. + Installing the mars-cli from source: ```sh -cd mars-cli # Assuming you are in the root folder +cd mars-cli # Assuming you are in the root folder of this project pip install . ``` @@ -18,6 +20,20 @@ If you want to overwrite the `settings.ini` file when reinstalling, you need to ```sh OVERWRITE_SETTINGS=True pip install .[test] ``` +Installing the MARS-cli, will by default create a `.mars` directory in the home directory to store settings and log files. +If you wish to create the `.mars` directory in another place, you must specify the `MARS_SETTINGS_DIR` variable and set it to the desired path: + +```sh +export MARS_SETTINGS_DIR= +``` + +If you want to make it permanent, you can run to following commands in the terminal. +Note: replace `.bashrc` by the config file of your shell. + +```sh +echo '# Add MARS setting directory to PATH' >> $HOME/.bashrc +echo 'export MARS_SETTINGS_DIR=' >> $HOME/.bashrc +``` Once installed, the CLI application will be available from the terminal. @@ -51,6 +67,144 @@ __log_max_size__: The maximum size in kB for the log file. By default the maximu __log_max_files__: The maximum number of old log files to keep. By default, this is set to 5 +## Target respoistory settings + +Each of the target repositories have a set of settings: + +- development-url: URL to the development server when performing a health-check +- development-submission-url: URL to the development server when performing a submission +- production-url: URL to the production server when performing a health-check +- production-submission-url: URL to the production server when performing a submissionW + +# Using the MARS-CLI + +If you wish to use a different location for the `.mars' folder: + +```sh +export MARS_SETTINGS_DIR= +mars-cli [options] ARGUMENT +``` + +## Help + +The mars-cli's help text can be found from the command line as such: + +```sh +mars-cli --help +``` + +Output: + +``` +➜ mars-cli --help +Usage: mars-cli [OPTIONS] COMMAND [ARGS]... + +Options: + -d, --development Boolean indicating the usage of the development + environment of the target repositories. If not present, + the production instances will be used. + --help Show this message and exit. + +Commands: + health-check Check the health of the target repositories. + submit Start a submission to the target repositories. + validate-isa-json Validate the ISA JSON file. +``` + +or for a specific command: + +```sh +mars-cli submit --help +``` + +Output: + +``` +➜ mars-cli submit --help +############# Welcome to the MARS CLI. ############# +Running in Production environment +Usage: mars-cli submit [OPTIONS] CREDENTIALS_FILE ISA_JSON_FILE + + Start a submission to the target repositories. + +Options: + --submit-to-ena BOOLEAN Submit to ENA. + --submit-to-metabolights BOOLEAN + Submit to Metabolights. + --investigation-is-root BOOLEAN + Boolean indicating if the investigation is + the root of the ISA JSON. Set this to True + if the ISA-JSON does not contain a + 'investigation' field. + --help Show this message and exit. +``` + +## Development + +By default the mars-CLI will try to submit the ISA-JSON's metadata towards the repositories' production servers. Passing the development flag will run it in development mode and substitute the production servers with the development servers. + +## Health check repository services + +You can check whether the supported repositories are healthy, prior to submission, by doing a health-check. + +```sh +mars-cli health-check +``` + +Output: + +``` +➜ mars-cli health-check +############# Welcome to the MARS CLI. ############# +Running in Production environment +Checking the health of the target repositories. +Checking production instances. +Webin (https://www.ebi.ac.uk/ena/submit/webin/auth) is healthy. +ENA (https://www.ebi.ac.uk/ena/submit/webin-v2/) is healthy. +Biosamples (https://www.ebi.ac.uk/biosamples/samples/) is healthy. +``` + +## Submitting to repository services + +TODO + +### Options + +- `--submit-to-ena`: By default set to `True`. Will try submit ISA-JSON metadata towards ENA. Setting it to `False` will skip sending the ISA-JSON's metadata to ENA. + +```sh +mars-cli submit --submit-to-ena False my-credentials my-isa-json.json +``` + +- `--submit-to-metabolights`: By default set to `True`. Will try submit ISA-JSON metadata towards Metabolights. Setting it to `False` will skip sending the ISA-JSON's metadata to Metabolights. + +```sh +mars-cli submit --submit-to-metabolights False my-credentials my-isa-json.json +``` + +`--investigation-is-root`: By default this flag is set to false, maening the ISA-JSON should have the `investigation` key at the root level. In case the root level __IS__ the investigation (`investigation` level is omitted), you need set the flag `--investigation-is-root` to `True` in order to validate the ISA-JSON. + +```sh +mars-cli submit --investigation-is-root True my-credentials my-isa-json.json +``` + +## Validation of the ISA JSON + +You can perform a syntactic validation of the ISA-JSON, without submitting to the target repositories. + +__Note:__ This does not take validation into account from the repository's side. This does not guarantee successful submission. + +```sh +mars-cli validate-isa-json --investigation-is-root True ../test-data/biosamples-input-isa.json +``` + +### Options + +`--investigation-is-root`: By default this flag is set to false, maening the ISA-JSON should have the `investigation` key at the root level. In case the root level __IS__ the investigation (`investigation` level is omitted), you need set the flag `--investigation-is-root` to `True` in order to validate the ISA-JSON. + +```sh +mars-cli validate-isa-json my-isa-investigation.json +``` # Extending BioSamples' records The Python script ``biosamples-externalReferences.py`` defines a class BiosamplesRecord for managing biosample records. This class is designed to interact with the BioSamples database, allowing operations like fetching, updating, and extending biosample records.