This Overview
opencga.sh is the officially recommended command line tool for normal users and are encouraged to use this. It implements all most of the functionality in more than 100 commandwith many different commands and subcommands. As per OpenCGA design, these These commands are a one-to-one mapping of Resources from REST web services and subcommands are mapping to end-points. These commands underneath makes REST calls to carry out operations, thus any user who has All the operations that can be performed using the command line internally creates one or several REST calls, so access to REST machine/cluster can execute these commands.
CommandLine Session Management
As a first step to execute any command with opencga.sh, user must login. After successfull login, the corresponding JWT sesssion token will be stored on machine under
Code Block |
---|
theme | RDark |
---|
title | session.json |
---|
|
~/.opencga/session.json |
This makes easier for users to login only once and execute any number of commands till the session token is expired. Please note down, session expiration is set by OpenCGA server independently from client. Once token is expired, user have to login again and can perform desired operations as normal.
Code Block |
---|
theme | RDark |
---|
title | Contents of session.json |
---|
|
{
"userId" : "rjbik",
"sessionId" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJyamJpayIsImF1ZCI6Ik9wZW5DR0EgdXNlcnMiLCJpYXQiOjE1MDkwMTU0ODgsImV4cCI6MTUwOTAxNzQ4OH0.n2vyq07UL_v7HHl0N-enyBEuy3Wy97b3ZKnA8ksLRIg",
"login" : "2017-10-26T11:58:09.146",
"logout" : "2017-11-22T14:58:10.097",
"timestamp" : 1511362690608,
"projectsAndStudies" : null
} |
Mapping From REST To CommandLineis required.
Correlation Between REST and CLI
In the following URL, "samples:" is the resource and "search" is the endpoint:
http://bioinfointbioinfo.hpc.cam.ac.uk/opencga-1.3.0-devdemo/webservices/rest/v1/samples/search
the corresponding command in commandLine the command line is :
Code Block |
---|
|
./opencga.sh samples |
and the corresponding subCommand subcommand is :
Code Block |
---|
theme | RDark | title | SubCommand |
---|
|
./opencga.sh samples search |
Executing ./opencga.sh will return the list of all available commands with a description for each of each them as shown below:
Code Block |
---|
language | text |
---|
theme | RDark |
---|
firstline | 1 |
---|
title | Executing 'opencga.sh' |
---|
|
Program: OpenCGA (OpenCB)
Version: 2.0.0-rc1
Git commit: 01cbe42598defa2ef5a192bad1f456166487aee4
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 FilesFile commands
jobs Jobs commands
individuals IndividualsIndividual commands
samplesfamilies SamplesFamily commands
variables Variable setpanels commands
cohorts Cohorts Panel commands
samples toolsSamples Tools commands
cohorts panels PanelsCohorts commands
Analysis commands:
alignments Implement several tools for the genomic alignment analysis
variant Variant commands
clinical Clinical analysis commands
Operation commands:
operations Operations commands
|
List The list of subCommand sample subcommands can be retrieved by simply executing a the "samples" command without any other argument as show below:
Code Block |
---|
language | text |
---|
theme | RDark |
---|
title | Executing 'opencga.sh samples' |
---|
|
./opencga.sh samples
Usage: opencga.sh samples <subcommand> [options]
Subcommands:
create Create a sample
load Load samples from a pedigree file
info Get samples information
search Search samples
update Update sample
delete Delete a sample
the selected sample group-by Group samples stats individuals Sample stats
Get the individuals of a list of samples. acl Return the acl of the resource
acl-update Update the permissions set for a member
annotation-sets-update Update the value of some annotations
|
CLI Session Management
Generally, unless we are pointing to a public OpenCGA installation, users will first need to log in using the "users login" command line. Once the user has successfully logged in, a session file will be generated in their home folder:
Code Block |
---|
|
~/.opencga/session.json |
This session file contains the following information:
This makes easier for users to login only once and execute any number of commands till the session token is expired. Please note down, session expiration is set by OpenCGA server independently from client. Once token is expired, user have to login again and can perform desired operations as normal.
Code Block |
---|
theme | RDark |
---|
linenumbers | true |
---|
|
{
"host" : "http://localhost:8080/opencga",
"version" : "v2",
"user" : "user1",
"token" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMSIsImF1ZCI6Ik9wZW5DR0EgdXNlcnMiLCJpYXQiOjE1NzQxNTcyODIsImV4cCI6MTU3NDE2MDg4Mn0.aMvD28oR_W5ZjWXuVpBXBGVHOEby-lAl7pb8oxOSXxE",
"refreshToken" : "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyMSIsImF1ZCI6Ik9wZW5DR0EgdXNlcnMiLCJpYXQiOjE1NzQxNTcyODIsImV4cCI6MTU3NDE2MDg4Mn0.aMvD28oR_W5ZjWXuVpBXBGVHOEby-lAl7pb8oxOSXxE",
"login" : "20191119095437",
"expirationTime" : "20191119105436",
"studies" : [ "user1@default:study1", "user1@default:study2" ]
} |
where:
- Line 2: OpenCGA host against which the user has been authenticated.
- Line 3: API version of the OpenCGA host
- Line 4: Authenticated user.
- Line 5: Token generated when the user last logged in.
- Line 6: Token generated when the user last logged in to refresh token without the need to provide user credentials again.
- Line 7: Date when the user last logged in.
- Line 8: Date when the token will expire.
- Line 9: Studies that are accessible by the user
Authenticating is only necessary the first time. Users will have time to execute any other command line without the need to provide any more credentials until the stored token expires. Please note down that the token expiration time is set by the main OpenCGA installation. Once this token has expired, users will need to log back in again to keep working with the command line.