In July, we released an early-access version of BaseMount, a command-line tool to allow you to navigate your BaseSpace account and work with your files on-demand.
To complement this browsing capability, we are adding to the suite of BaseSpace Command Line Tools by releasing the BaseSpaceCLI (Command Line Interface). BaseSpaceCLI provides two new areas of functionality, uploading samples and launching apps, but also comes with a host of other commands to help you work with your BaseSpace data and apps.
To install the BaseSpaceCLI run this command:
$ sudo bash -c "$(curl -L https://bintray.com/artifact/download/basespace/helper/install.sh)"
The BaseSpaceCLI functionality is wrapped by a single
bs command, rather like git or docker. Just as you have
git pull there is
bs sample upload,
bs launch app and
bs list projects.
You can see a help message including what commands are available by typing bs without arguments:
$ bs ...
One way to get started is to watch the BaseSpaceCLI tutorial videos.
In the remainder of this blog post we will provide a brief introduction to some of the BaseSpaceCLI functionality.
The first step of using BaseSpaceCLI is to authenticate your account.
$ bs authenticate
This command redirects you to a URL. You can paste this URL into any web browser and type your BaseSpace credentials. An access token is then downloaded that will allow you to use BaseSpaceCLI. You only have to do this once to set up your account.
This mechanism is the same as BaseMount and the tokens can also be shared between the two tools – if you authenticate with BaseMount it can be used by BaseSpaceCLI and vice versa. For more information on access token sharing between BaseMount and BaseSpaceCLI, see the documentation.
See this video demo for more detail about Getting Started.
An example sample upload command is:
$ bs upload sample -p "my project name" *.fastq.gz
This will upload a set of fastq.gz files for a specific sample. We also provide recipes in the documentation to help you use command-line loops to upload batches of samples. BaseSpaceCLI puts no restrictions on what fastq file sizes you can upload into BaseSpace.
See this video demo for more detail about Sample Upload.
To launch the BWA app, we can first look at what parameters we need to pass to the app:
$ bs list apps -n "BWA"
Then use the
bs launch app command and provide the necessary BaseSpace entities on the command line, either as IDs:
# project ID and then sample ID $ bs launch app -n "BWA" 125125 5135135
Or as BaseMount paths:
# assume you have mounted your BaseSpace account as $BASEMOUNT $ bs launch app -n "BWA" $BASEMOUNT/Projects/MyProject $BASEMOUNT/Samples/MySample
App configuration information is stored by BaseSpaceCLI, including the app versions and how they are launched. BaseSpaceCLI ships with support for four of the most commonly used apps (BWA WGS, Isaac WGS, TopHat and Cufflinks) and the ability to import new apps based on existing app runs.
See this video demo for more detail about Launching Apps.
To help you find entities in your BaseSpace account to use for app launches and other purposes, there are commands to list projects, samples and appresults. For example, to list projects:
$ bs list projects
These commands also have formatting options to facilitate scripting. In this example, we list samples in csv form, omitting quotes:
$ bs list samples -f csv --quote none
See this video demo for more detail about Listing Entities.
Working With Running Apps
Once an app has been launched (either from basespace.com or from BaseSpaceCLI), you can monitor its progress with the
bs list appsessions command:
# by default list appsessions with the Running and PendingAnalysis status $ bs list appsessions
You can also kill these apps with the
bs kill appsession command:
$ bs kill appsessions 51351
As well as BaseSpaceCLI, we are also releasing an update to BaseMount. The main feature in this new release is proxy support as well as some other internal changes to make BaseMount more efficient.
Please note that this is an early access version of the BaseSpaceCLI. We encourage you to test it out and provide any feedback on our developer google group.