How to launch any app in BaseSpace using BaseSpace Command Line Interface (CLI)
Last updated
Last updated
© 2023 Illumina, Inc. All rights reserved. All trademarks are the property of Illumina, Inc. or their respective owners. Trademark information: illumina.com/company/legal.html. Privacy policy: illumina.com/company/legal/privacy.html
The following details how to launch any app (application) in BaseSpace with the Command Line Interface (CLI). Steps include how to obtain the list of apps in BaseSpace, how to view list of available options for an app, how to find a project ID, how to find Biosample IDs, and how to accept the license agreement.
Follow the guidance on the BaseSpace Sequence Hub CLI Overview page to download and authenticate the BaseSpace CLI (this is only required when using BaseSpace CLI for the first time).
For a video format, see How to get started with BaseSpace Command Line Interface (CLI) Video.
Next, consider which BaseSpace application to use, along with which version of the application to use.
Enter the CLI command bs list application to list all of the available applications in BaseSpace instance and the latest version number for each app.
Alternatively, browse to the BaseSpace Apps page for more information on available applications, versions, and to explore demo data sets for each application.
After deciding the application and version to launch, obtain a list of all of the command-line options for that given application. To do so, run the command:
bs launch application -n "" --app-version <app.version.number> --list -f csv
This will generate a list (in CSV format) of the different available options for the application (required and optional)along with the default values for each. See example output below for 16S Metagenomics app, version 1.1.1.
Running bs launch application -n "16S Metagenomics" --app-version 1.1.1 --list -f csv
Gives:
For a more comprehendible visualization, copy and paste this CSV list into Excel or other spreadsheet tool get an easier view.
In order to launch the an application via CLI, make sure that the launch command contains all of the required options that do not have a default value.
In this example, with the 16S Metagenomics app, the required options without default values are: the project-id (to save the results to) and the input biosample-ids.
Reviewing the different options one-by-one:
App-session-name: the app session name will default to the app name, followed by the time the app was launched.
Project-id: this is the project ID to which to export the results. - To query the project ID by name, run the CLI command: * bs list project * This will list the different projects in the BaseSpace account, the project ID number for each, and the size.
Sample-id: as an example, this guide will use the biosamples that are provided in the demo project for the 16S Metagenomics app, which is project ID: 87118098. - List the biosamples from this project with the following command: * bs biosample list --project-id 87118098 --terse * which provides the following output:
Database: This is the taxonomic database file that is used by the 16S Metagenomics application to classify the reads. If no file is specified, it will use the default database file, RefSeq-RDP16S_v3_May2018_DADA2_32bp.dat
Custom-database: If using a different database file instead of using the default databases included with the 16S Metagenomics application, use this field. First, the database file must already be uploaded to a BaseSpace project, then, supply the File ID here.
To obtain the file ID, use following command: - bs contents project -i
5.Complete the CLI command as follows (in this example).
bs launch application -n “16S Metagenomics” --app-version 1.1.1 -o basespace-labs-disclaimer:Accepted -o app-session-name:”16S Metagenomics test” -o project-id:382517140 -o sample-id:106782723,106782724,106782725,106782726,106782727,106782728,106782729,106782730,106782731,106782732,106782733,106782734,106782735,106782736,106782737,106782738,106782739,106782740,106782741,106782742,106782743,106782744,106782745,106782746
6. If the end user license agreement (EULA) for the application has not already been accepted, there will be an error message similar to the one above. Navigate to the BaseSpace webpage to accept the agreement.
Use the URL provided to go to the application page, then scroll down to the EULA. Select it, then accept the license agreement prompt.
For any feedback or questions regarding this article (Illumina Knowledge Article #7759), contact Illumina Technical Support techsupport@illumina.com.
Note: Accepting the license agreement is required once per app, so future uses of the same app will not require this step.
