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.
Sep 07, 2020 Useful Windows command-line tools. You can perform and script most Windows system administration tasks from the command line by learning and using wmic. Native command-line Windows networking tools you may find useful include ping, ipconfig, tracert, and netstat. You can perform many useful Windows tasks by invoking the Rundll32 command.
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.
- NVIDIA Developer Tools are a collection of applications, spanning desktop and mobile targets, which enable developers to build, debug, profile, and develop class-leading and cutting-edge software that utilizes the latest visual computing hardware from NVIDIA. Developer Tools Downloads Figure 1. Flowchart describing working with new NVIDIA Nsight tools for performance optimization NVIDIA.
- Just like that, your Mac is a powerful server. MacOS Server brings even more power to your business, home office, or school. Designed to work with macOS and iOS, macOS Server makes it easy to configure Mac and iOS devices.
- EDITED FOR PEOPLE JUST GETTING HERE See #569 (comment) and #569 (comment), the warning can just be ignored. Command Line Tools works fine, you do not need the full Xcode.
For information on the most recent version of BaseSpace Sequence Hub CLI see Release Notes.
Install:
You can install from your web browser directly: or install from the command line, as described below.
These install instructions assume installation into the $HOME/bin
directory. You can create this directory with mkdir $HOME/bin
.
You can change the installation location (for example, to preserve a previous installation) by changing the option after -O
, e.g.
Note that your operating system might require that you change the file permissions to make the downloaded binary executable:
If you are using a Mac, you can also install and update BaseSpace Sequence Hub CLI using Homebrew:
Binaries for other platforms are also available, see complete file listings via bintray.
Installing bscp
BaseSpace Copy (bscp) is an optional plugin to the Sequence Hub CLI, however it is no longer maintained as bscp upload and download functionality has now been integrated into native CLI upload
and download
commands.If you still need to install this tool, download the binary into a location in your $PATH with a bs-
prefix to make it available via the bs cp
command:
Authenticate
Note this command will authenticate to a default server located in AWS Virginia (https://api.basespace.illumina.com/
)for localised authentication, please see Authenticate section.
Command Structure
The BaseSpace Sequence Hub CLI is based on a patternof 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
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 examplecreate project
is equivalent toproject create
. See Entity Reference.Actions on sub-entities—Actions on sub-entities, e.g.
export workflow threshold
orsetproject 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:
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 bybs 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 usingbs config load
. This is useful for injecting access credentials into Docker containers.
For example:
API Servers:
- USA: https://api.basespace.illumina.com (default if no api-server is specified)
- Germany: https://api.euc1.sh.basespace.illumina.com
- Australia: https://api.aps2.sh.basespace.illumina.com
- China: https://api.cnn1.sh.basespace.illumina.com.cn
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:
You can type the action by itself to see the entities to which that action can be applied:
Similarly, you can specify an entity and see which actions are available:
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:
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 someexamples.
- 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
andruns
which supportproperties
on those entities. - The
workflow
entity hasthresholds
anddependencies
with their own operations. - The
biosample
entity hasrequeue
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.
You can also use this pattern to help explore the available commands, e.g.
For more information on using sub-entities, refer to the worked examples:
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:
Additional options:
--scopes
, to specify the scopes you obtain for your token.--timeout
, the amount of time to wait before giving up
Scopes
Osx Command Line Developer Tools Download
The following scopes are commonly used:
Actions | Scopes |
---|---|
Accessing data | |
Creating data | |
Deleting data | |
Working with apps | |
Uploading sequencing run folders |
More information about scopes is available in the API documentation
For example:
Whoami
Returns information about the current user and token.
Example:
Entity Reference
Entity | Description | Available Actions | Sub-entities | Other notes | Example |
---|---|---|---|---|---|
Application | BaseSpace app | Get Header List Rename | A token with MANAGE APPLICATIONS scope is needed for some operations | ||
AppResult | Output from app | Content Delete Get Header List Translate | Property | ||
AppSession | Representing an app during or after it has executed | Await Delete Get Header Kill List Rename | Property | ||
Biosample | Data and metadata for a biological sample | Get Header Import List Rename | Property | See Worked Examples | |
Config | Configuration files stored in $HOME/.basespace | ListLoad | Not a BSSH entity, but used purely by BSSHCLI | ||
Dataset | Output from app that captures typed output | Delete Get Header Import List Translate | Property | ||
Project | Collection of other BSSH entities | Create Delete Get Header List Rename | Property | ||
Run | Sequencing run, sometimes called a flow cell | Content Delete Get Header List | Property | ||
Workflow | A type of BSSH app that can be configured with auto-launch dependencies and QC thresholds | Create Threshold Dependency | See Worked Examples for more details |
Sub-Entity Reference
Entity | Description | Owning Entity | Example |
---|---|---|---|
Dependency | Workflow | See Worked Examples for more details. | |
Lab Requeues | The lab requeues that have been requested for a biosample | Biosample | |
Property | Key/value properties on entities | AppResultAppSessionBiosampleDatasetProject | |
Threshold | Workflow |
Action Reference
Osx Command Line Developer Tools Tutorial
Action | Description | Available Entities | Notes | Example |
---|---|---|---|---|
All | Get all properties for an entity | Property | ||
Await | Await the completion of appsessions | Appsession | ||
Clear | Used to remove workflow settings | Workflow dependency Workflow threshold | ||
Content | Show the contents of a BSSH entity | AppResult Dataset Run | ||
Delete | Move an entity to trash | AppResult AppSession Dataset Project Run | Items are not deleted until the trash is emptied | |
Download | Download BSSH data | AppResult Biosample Dataset File Project Run | ||
Get | Application AppResult Biosample Dataset Project Property Run | |||
Headers | Show available headers for an entity | Application AppResult Biosample Dataset Project Run | Useful to choose outputs for `bs list` | |
Kill | Kill a running appsession | Appsession | ||
List | List all entities | Application AppResult Biosample Dataset Project Property Run | Has options to customize output: | |
Load | Allow config variables to be loaded into environment | Config | ||
Rename | Rename an entity | Application Appsession Biosample Project | ||
Set | Set a property or other setting | Property | ||
Translate | Translate between V1 and V2 entity IDs | AppResult Dataset |
What's New
The V2 CLI features has been designed to be fast, portable, and reflect as much of the API as possible. We have included commands to support features released in BaseSpace 5.0. These features include:
Workflows—BaseSpace Sequence Hub includes support for apps that can belaunched automatically and have an automated QC step, calledanalysis workflows. The new CLI includes commands to create, list andmodify these workflows.
Datasets—BaseSpace Sequence Hub apps have the ability to create datasets, an entity that stores data and metadata separately. The new CLI includes features to listand filter datasets.
Biosamples—The biosample is an entity that groupstogether metadata and FASTQ data for a biological sample, includingattaching analysis workflows to a biosample. The V2 CLI allows thelisting and creation of biosamples and their metadata, including thecreation of analysis workflows and inspecting lab requeues.
The V2 CLI includes the following enhancements on the previous V1 CLI:
Rich options for listing entities and customising output
Additional
get
command to provide more details on a specific entitySupport for deleting appresults, appsessions, datasets, projectsand runs.
Ability to inspect files within BaseSpace Sequence Hub entities using the
contents
commandSupport for downloading data using the
download
commandMore flexible install process. The CLI can be installed by downloading a single binary, which enables you to install the CLI in an environment where you do not have sudo privileges. Using a single binary file also allows simpler distribution of updated versions.
Support for all Linux platforms in addition to Mac and Windows.
How Can I Get Support for CLI?
Command Line Windows 10
The BaseSpace CLI v1.0 and higher is supported by the illumina support team: support@illumina.com. The BaseSpace Sequence Hub Google Group is a public forum for any BaseSpace developer information.
macOS Server brings even more power to your business, home office, or school. Designed to work with macOS and iOS, macOS Server makes it easy to configure Mac and iOS devices. It’s also remarkably simple to install, set up, and manage. Add macOS Server to your Mac from the Mac App Store for just $19.99.
Osx Command Line Developer Tools Tutorial
Your command center.
Command-line Sxstrace.exe
macOS Server lets you set up and manage multiple Mac computers and iOS devices, right from your Mac. And it’s so simple to use, you don’t need an IT department.
macOS Server resources.
Everything you want to know about macOS Server, including training, services, and documentation.