Introducing BaseSpaceCLI

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.

BaseSpace Command Line Tools

To install the BaseSpaceCLI run this command:

$ sudo bash -c "$(curl -L"

The BaseSpaceCLI functionality is wrapped by a single bs command, rather like git or docker. Just as you have git commitgit pushgit pull there is bs sample uploadbs launch app and bs list projects.

You can see a help message including what commands are available by typing bs without arguments:

$ bs

Tutorial Videos

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.

Getting Started

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.

Sample Upload

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.

Launching Apps

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.

Listing Entities

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 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

See videos for launching apps, launch apps #2, and importing new apps for more detail about Running Apps.

BaseMount Update

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.

More Information

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.

You’ll find more information on our help site both about BaseSpaceCLI and BaseMount.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.