CLI Overview - BaseSpace Developers

• Home
• Documentation
• CLI Overview

BaseSpace Sequence Hub CLI

You can work with your BaseSpace Sequence Hub data using the command line interface (CLI). The BaseSpace Sequence Hub CLI supports scripting and programmatic access to BaseSpace Sequence Hub for automation, bulk operations, and other routine functions. It can be used independently or in conjunction with BaseMount.

The BaseSpace Sequence Hub CLI has been updated to support automation features in the latest BaseSpace Sequence Hub.

To see the overall capabilities of the CLI and to help you get started post-installation, we recommend you use the Worked Examples.

Install BaseSpace Sequence Hub CLI

The BaseSpace Sequence Hub CLI is supported on Linux, Mac, and Windows (32 and 64 bit). It carries a small memory footprint, but for safety it should be installed on a machine with at least 1GB RAM.

For information on the most recent version of BaseSpace Sequence Hub CLI see Release Notes.

Install:

You can download the latest CLI release using your web browser, the latest release version is:

• Mac OS X
• Linux
• Windows

Alternatively you can install from the command-line. These install instructions assume installation into the $HOME/bin directory. You can create this directory with mkdir $HOME/bin.

# Linux $ wget "https://launch.basespace.illumina.com/CLI/latest/amd64-linux/bs" -O $HOME/bin/bs # Mac $ wget "https://launch.basespace.illumina.com/CLI/latest/amd64-osx/bs" -O $HOME/bin/bs # Windows $ wget "https://launch.basespace.illumina.com/CLI/latest/amd64-windows/bs.exe" -O bs.exe

You can change the installation location (for example, to preserve a previous installation) by changing the option after -O, e.g.

$ wget "https://launch.basespace.illumina.com/CLI/latest/amd64-linux/bs" -O $HOME/bin/bs

Note that your operating system might require that you change the file permissions to make the downloaded binary executable:

$ chmod u+x $HOME/bin/bs

If you are using a Mac, you can also install and update BaseSpace Sequence Hub CLI using Homebrew:

$ brew tap basespace/basespace && brew install bs-cli

Binaries for other platforms are also available, see complete file listings via launch.basespace.illumina.com.

Authenticate

$ bs auth

Note this command will authenticate to a default server located in AWS Virginia (https://api.basespace.illumina.com/) for localised authentication and tips for authenticating against Professional and Enterprise workgroups, please see the Authenticate section.

Command Structure

The BaseSpace Sequence Hub CLI is based on a pattern of a command prefix and a tree of subcommands. Just as in docker there is docker run, docker build, docker exec and in git there is git pull, git push,git commit, the the BaseSpace Sequence Hub CLI has bs list, bs create and bs authenticate. Some commands have subcommands, such as bs list appsession and bs create project.

Each subcommand has its own set of options which can be accessed with --help or -h, as in the following example

$ bs auth --help Usage: bs [OPTIONS] authenticate [authenticate-OPTIONS] Application Options: -V, --version Display version Help Options: -h, --help Show this help message [authenticate command options] -c, --config= Output to this BaseSpaceCLI configuration --force Overwrite existing configuration file, if it already exists --api-server= BaseSpace API hostname (default: https://api.basespace.illumina.com) [$BASESPACE_API_SERVER] --scopes= List of scopes to authenticate with (default: READ GLOBAL, CREATE GLOBAL) --timeout= Time in seconds before giving up (default: 120)

Command Summary

CLI commands can use the following patterns:

• Standalone commands—Single commands, e.g. auth. See Standalone Commands.

• Actions on entities—Actions on entities, e.g. list appsession, import dataset, get biosample. These can be used in reverse, for example create project is equivalent to project create. See Entity Reference.

• Actions on sub-entities—Actions on sub-entities, e.g. export workflow threshold or set project property. See Sub-Entity Reference.

The following table summarizes the CLI functions and commands. For detailed descriptions of commands, see Command Reference.

Function	Available Commands
List and explore entities	bs list, bs get, bs headers
List and download files within entities	bs contents, bs download
Kill running apps	bs kill appsession
Delete entities	bs delete
Create biosamples and upload fastq files for them	bs create biosample, bs upload dataset
Create analysis and configure analysis workflows from apps	bs create workflow, bs workflow threshold ..., bs workflow dependency ...

Some command combinations have specific options. Review the usage message for more information. For example:

$ bs list appsession --help ... [list command options] --exec-status= Filter by execution status --input-biosamples= Filter by Input BioSample ...

Command Discovery

The CLI has been designed to help you discover commands. By typing the main bs command with --help you can see all the entities that are supported and all the actions that can be performed:

$ bs --help ... Available actions: add Add lane or workflow settings authenticate Make an authentication request to BaseSpace (aliases: auth) clear Clear lane or workflow settings content Show all files in an entity (aliases: contents, dir) create Create an entity delete Move entities to your trash (aliases: rm, move-to-trash) download Download files from an entity export Export lane or workflow settings get Get detailed information about an entity (aliases: info, inspect) import Import lane or workflow settings kill Abort entities list List and filter entities (aliases: filter, list-all) set Set properties in an entity upload Upload files to an entity whoami Get information about selected user/configuration Available entities: application View and manage applications (aliases: applications) appresult View and manage appresults (aliases: appresults) appsession View and manage appsessions (aliases: appsessions) biosample View and manage biosamples (aliases: biosamples) config View and manage installed confgurations (aliases: configs, configuration) dataset View and manage datasets (aliases: datasets) lane View and manage automated lane QC thresholds (aliases: lanes) project View and manage projects (aliases: projects) run View and manage runs (aliases: runs) workflow View and manage workflow applications (aliases: workflows)

You can type the action by itself to see the entities to which that action can be applied:

$ bs list Please specify one command of: application, appresult, appsession, attribute, biosample, config, dataset, project, property or run $ bs import Please specify one command of: lane or workflow

Similarly, you can specify an entity and see which actions are available:

$ bs application Please specify one command of: get, header, launch or list $ bs workflow Please specify one command of: create, dependency or threshold

For each command combination, you can always run --help to see which sub-options are available and to get more details on the sub-commands:

$ bs appsession --help ... Available commands: delete Move an appsession to your trash (aliases: rm, move-to-trash) get Get detailed information about an appsession (aliases: info, inspect) header List all available fields for an appsession (aliases: headers) kill Abort an appsession list List and filter all appsessions (aliases: filter, list-all) property Manage properties on an appsession (aliases: properties) $ bs appsession kill --help ... [kill command arguments] ID: IDs of the appsession to kill (multiple positional arguments) bs set property --help Available commands: appresult set properties of an appresult (aliases: appresults) appsession set properties of an appsession (aliases: appsessions) biosample set properties of a biosample (aliases: biosamples) dataset set properties of a dataset (aliases: datasets) project set properties of a project (aliases: projects) run set properties of a run (aliases: runs) Command Reference

The following sections list the standalone commands and action commands grouped by entity, sub-entity, and action. For more information about how the commands work in practice, see the Worked Examples.

• The Entities table lists the actions that can be applied to the entity, with some examples.
• The Sub-Entities table lists the owning entity.
• The Actions table lists the entities and sub-entities the action applies to, with some examples.

Entities and sub-entities

Some entities have sub-entities that have separate operations you can perform. These include:

• Core Entities like projects, appsessions, datasets and runs which support properties on those entities.
• The workflow entity has thresholds and dependencies with their own operations.
• The biosample entity has requeue sub-entity used in communication with LIMS for high-throughput lab operations use-cases.

To use sub-entities, you need to provide switches to select the main entity (e.g. the project) as well as the sub-entity (e.g. the property name).

We recommend that you access sub-entities noun-first in this pattern bs <entity> <sub-entity> <verb> e.g.

# -n refers to the name of the project $ bs project property all -n "MyProject" # -n refers to the name of the project and --property-name refers to the name of the property within that project $ bs project property get -n "My Project" --property-name="MyProperty"

You can also use this pattern to help explore the available commands, e.g.

$ bs project property Please specify one command of: all, delete, get or set

For more information on using sub-entities, refer to the worked examples:

• Workflow configuration
• Working with properties

Standalone Commands

Authenticate

Authenticates against an instance of BaseSpace Sequence Hub, storing the API server used, and the derived access token, for use in future commands.

Example:

$ bs auth $ bs authenticate

Note: auth is an alias for authenticate. Either example below runs the same command):

This command will generate a URL which must be pasted into a browser where the user can log into their BaseSpace account and accept the authentication request.

$ bs auth Please go to this URL to authenticate: https://basespace.illumina.com/oauth/device?code=6Cesj

Enterprise Domains & Workgroups

If accessing a Professional or Enterprise workgroup, be sure to log into the desired domain and/or workgroup prior to running the authenticate command with BaseSpace CLI. Running the command below will set the default configuration and access token for whatever account and domain/workgroup the user is logged into. If needed, additional authentication configurations may be generated and stored using the -c <config-name> option. See below for more details.

Note: for Enterprise domains, the API URL used for authentication does not include the domain name. Only authentication with non-USE1 instances requires addition of the --api-server option (see below for details).

Specify API server and Access Token

Most BaseSpace Sequence Hub CLI commands require that you specify an API server to contact and an access token to authenticate against BaseSpace Sequence Hub. These can be specified in the following ways.

• Config—Use -c / --config to specify the config name to use e.g. bs -c virginia to use the virginia.cfg configuration file. Configuration files are generated by bs auth and stored in $HOME/.basespace. The file format used here is shared with other BSSH command line tools such as BaseMount, so if you have a BaseMount config file you do not need to derive another one.
• Command Line—Use --api-server / --access-token to specify the API server and access token on the command line. Warning: This method can store details in your command history and threaten the security of your token.
• Environment variables—Provide access credentials by specifying the environment variables $BASESPACE_ACCESS_TOKEN and $BASESPACE_API_SERVER. These can also be loaded from a config using bs config load. This is useful for injecting access credentials into Docker containers.

API Servers:

Region Name	Country	City/State	API URL
USE1 (default)	USA	Virgina, USA	https://api.basespace.illumina.com
APS2	Australia	Sydney, Australia	https://api.aps2.sh.basespace.illumina.com
CAC1	Canada	Montréal, Québec	https://api.cac1.sh.basespace.illumina.com
EUC1	Europe	Frankfurt, Germany	https://api.euc1.sh.basespace.illumina.com
APN1	Japan	Tokyo, Japan	https://api.apn1.sh.basespace.illumina.com
EUW2	UK	London, UK	https://api.euw2.sh.basespace.illumina.com

To authenticate on a BaseSpace instance for a region other than USE1 the --api-server option must be used in conjunction with the appropriate API URL:

$ bs auth --api-server https://api.euc1.sh.basespace.illumina.com # Authenticate on EUC1

Similar to the auth command above, this will generate an authentication URL with appropriate API URL:

$ bs auth --api-server https://api.euc1.sh.basespace.illumina.com Please go to this URL to authenticate: https://euc1.sh.basespace.illumina.com/oauth/device?code=ElVQx

Configs:

The command above will write the token to the default config file ($HOME/.basespace/default.cfg). If this is not desired, a new config file can be created using the -c / --config option:

$ bs auth -c eu --api-server https://api.euc1.sh.basespace.illumina.com # Authenticate on EUC1 and save to a config file called "eu"

Any number of uniquely names config files may be generated in order to interact with different accounts, regions, and workgroups. Use the command below to list all saved config file names:

$ bs list config

If saving the access token in a non-default config file, the -c <config-name> option must be used for every invocation of bs in order to send the proper access token. To avoid needing to use the -c <config-name> for every command, the eval command can be used in conjunction with the bs load config command to load the proper API URL and access tokens into the variables BASESPACE_API_SERVER and BASESPACE_ACCESS_TOKEN, respectively.

$ eval $(bs load config eu)

This command is specific to Linux and Mac OS and the setting will last for the duration of the terminal session, or until changed by the user. In order to set these variables in Windows, there is a two-step process and it depends on whether PowerShell or the CMD terminal is used:

First, print the API server URL and access token for the desired config file:

$ bs load config eu BASESPACE_API_SERVER=https://api.euc1.sh.basespace.illumina.com BASESPACE_ACCESS_TOKEN=<private-access-token>

Second, for each of the lines printed from the command above, copy the line, and run the $env command within Windows PowerShell:

$env:BASESPACE_API_SERVER="https://api.basespace.illumina.com" $env:BASESPACE_ACCESS_TOKEN="<private-access-token>"

Note: Both the URL and access token values must be enclosed in double quotes in order to successfully set the environment variables

If using Windows CMD rather than PowerShell, the set command can accomplish the same goal, but the quotation marks must be omitted:

$ set BASESPACE_API_SERVER=https://api.basespace.illumina.com $ set BASESPACE_ACCESS_TOKEN=<private-access-token>

To verify the settings, run bs whoami and verify the "Host" URL is now set to the desired instance/region API URL.

It is also possible to pass the API URL and access token values on the command line, but this is not recommended.

Example:

$ bs list projects --api-server=https://api.euc1.sh.basespace.illumina.com/ --access-token=XXXXX

Additional options for the auth command:

• --scopes, to specify the scopes you obtain for your token.

• --timeout, the amount of time to wait before giving up

Scopes

The following scopes are commonly used: