OpenCGA implements three different command lines for different purposes, these are opencga.sh, opencga-admin.sh and opencga-analysis.sh. All of them follow the same structure, design and share many usage features:
Here you can find a diagram of the three command lines a brief description below:
This is the main command line for normal users, in fact this is the only command line that everybody should use. It implements all the functionality in more than 100 command and subcommands, for example you can login, list files, search samples or query variants. The vast majority of the subcommands run over RESTful web services so this command line can run remotely (outside of the cluster) or locallly (inside the cluster) as long as you have access to the REST server, this command line uses client-configuration.yml file. You can find more detailed information at Command Lines > opencga.sh
This command line requires the admin password to be executed, it allows to install catalog database and indexes, create users, query the audit, ... This does not use RESTful web services and it needs direct access to the server, so it only runs in the OpenCGA cluster and it uses configuration.yml. You can find more detailed information at Command Lines > opencga-admin.sh.
This command line is used by OpenCGA system itself and nobody is expected to use it unless you are debugging and you really understand how it works. It runs in the cluster and uses configuration.yml. No more detailed information is provided at this moment.
In this section you will learn how to use the command lines, some examples are provided using opencga.sh command line.
OpenCGA follows the most standard conventions when implementing command lines, the most relevant ones are:
./opencga.sh [-h|--help] [--version] <command> [options]
You can execute any of the three command lines without any argument to get the usage help (you can also provide -h parameter)
imedina@ivory:~/appl/opencga/build/bin$ ./opencga.sh Program: OpenCGA (OpenCB) Version: 1.0.0-rc3 Git commit: f42850ff3ff1acb8d0a1bac710c9ec38e084fee5 Description: Big Data platform for processing and analysing NGS data Usage: opencga.sh [-h|--help] [--version] <command> [options] Catalog commands: users User commands projects Project commands studies Study commands files Files commands jobs Jobs commands individuals Individuals commands samples Samples commands variables Variable set commands cohorts Cohorts commands tools Tools commands panels Panels commands Analysis commands: alignments Implement several tools for the genomic alignment analysis variant Variant commands |
where:
When one command is executed without any other argument a specific help is shown, this specific help shows the different subcommands available with a brief description, as you can see in the following example
imedina@ivory:~/appl/opencga/build/bin$ ./opencga.sh users Usage: opencga.sh users <subcommand> [options] Subcommands: create Create a new user info Get complete information of the user together with owned and shared projects and studies update Update some user attributes using GET method change-password Update some user attributes using GET method delete Delete an user [NO TESTED] projects List all projects and studies belonging to the selected user login Login as a user logout End user session reset-password Reset password |
where:
When one subcommand is executed with -h or --help parameter then a specific usage help with all the options is printed for this subcommand, check next example
imedina@ivory:~/appl/opencga/build/bin[release-1.0.0-rc3]$ ./opencga.sh samples update -h Usage: opencga.sh samples update [options] Options: -C, --conf STRING Configuration folder that contains opencga.yml, catalog-configuration.yaml, storage-configuration.yml and client-configuration.yaml files. -d, --description STRING Description -h, --help Print this help [false] --individual STRING Individual id or name --log-file STRING Set the file to write the log -L, --log-level STRING One of the following: 'error', 'warn', 'info', 'debug', 'trace' [info] -M, --metadata Include metadata information [false] -n, --name STRING Cohort set name. --no-header Not include headers in the output (not applicable to json output-format) [false] --of, --output-format STRING Output format. one of {JSON, JSON_PRETTY, TEXT, YAML} [TEXT] * --sample STRING Sample id or name -S, --sid, --session-id STRING Token session id --source STRING Source -s, --study STRING Study [[user@]project:]study where study and project can be either the id or the alias. -v, --verbose Increase the verbosity of logs [false] |
where:
Some of these options are available for most of the commands and subcommands, these are:
-C, --conf: If not defined, the command line will assume that the configuration folder can be found in the parent folder where the executable is found (../conf). If that is not the case or if the user wants to use other configuration files available in a different path, the path should be provided.
-h, --help: Shows the help with the list of options. Generally this is not necessary because there is almost always a mandatory parameter to be provided, although it is needed in a few cases if user wants to see the options.
--log-file: By default, all the logs generated by the command lines are printed in the screen. However, the user might want to redirect the logs to another file. For those cases, the user will need to provide the file where the logs will be stored.
-L, --log-level: There are 5 different log levels: 'error', 'warn', 'info', 'debug', 'trace'
-M, --metadata: prints the result metadata
OpenCGA command lines come with a huge number of commands and options and its very tedious for any user to type these manually. We have created auto completion scripts for each of the following command lines to make everyone's life easier.
OpenCGA generates auto completetion scripts dynamically from source code to make sure we always support the latest commands and options available in our code. After installation, user will find these scripts under "build/completion" folder.
Please copy these scripts to the following directory and then source:
cp build/completion/opencga* /etc/bash_completion.d/ source /etc/bash_completion.d/opencga source /etc/bash_completion.d/opencga-admin source /etc/bash_completion.d/opencga-analysis |
Table of Contents: