Here are some more advanced recipes that demonstrate how to combine multiple CLI commands or employ the CLI with other common utilities to achieve powerful results. For documentation on how to use individual commands, see instead the examples page.

Most of these examples rely on simple patterns, such as:

  • The --terse flag makes most CLI commands return raw IDs which can be fed into other CLI commands
  • Many commands take a single ID as input — to run a command on many inputs, first use the list command (maybe with some filters applied) and pipe the output to downstream steps via a program like xargs
  • CLI processes running in sub-shells can be used to make command inputs more flexible, for example by translating names to IDs on the fly

Code snippets are given for bash shells and should work on UNIXes including OS X. Dummy values are shown in angled brackets and should be filled in by the user before running (e.g. <id>).

I want to...

make an API call not yet supported by a CLI command

eval $(bs config load default) && 
    curl -sS --fail $BASESPACE_API_SERVER/v2/<unsupportedApiPath> -H x-access-token:$BASESPACE_ACCESS_TOKEN

stream a file from BSSH

curl -s $(bs link file -i <fileId>) | head

upload a biosample manifest

# generate demo manifest CSV file
cat  <<EOF > manifest.csv
[Header]
FileVersion,1
[Data]
Biosample Name,Analysis Workflow,Default Project
my_biosample_1,my_workflow,my_project
my_biosample_2,my_workflow,my_project
my_biosample_3,my_workflow,my_project
EOF

# note expected column order
while IFS=, read -r biosample workflow project; do
    bs create biosample -n ${biosample} --analysis-workflow ${workflow} -p ${project}
done < <(tail -n+5 manifest.csv)

download all datasets an appsession has created

bs await appsession <id> --terse | xargs -I@ bs download dataset -i @ -o @

retrieve a run's Indexing QC table as shown via the web UI

RUNID=123456; eval $(bs config load default) &&
    curl --fail -Ss $BASESPACE_API_SERVER/v2/runs/$RUNID/laneindexsummaries?Limit=1000 -H x-access-token:$BASESPACE_ACCESS_TOKEN | 
    jq -r ".Items[] | .IndexingCounts[] | [ .Id, .BioSample.BioSampleName, .Library.Name, .Index1,  .Index2, .FractionMapped ] | @tsv"
# produces:
# 1       BiosampleName1    LibraryName    CCGCGGTT        CTAGCGCT        4.9185
# 2       BiosampleName2    LibraryName    AGTTCAGG        TCTGTTGG        3.6086
# 3       BiosampleName3    LibraryName    TAATACAG        GTGAATAT        3.7074
# ...

use the CLI behind a proxy

HTTP_PROXY=http://user:password@host:port/ bs whoami

delete old datasets en masse

bs list datasets --older-than 1y --terse | xargs -n1 bs delete dataset --preserve-metadata -i

delete all my empty projects

bs list projects --filter-field TotalSize --filter-term '^0' --terse | xargs -n1 bs delete project -i

run CLI commands across multiple accounts

bs config list --template '{{.Name}}' | xargs -n1 bs whoami -c

download appsession log files with a given name

logFileID=$(eval $(bs config load default) &&
  curl -sS --fail -H x-access-token:$BASESPACE_ACCESS_TOKEN \
    $BASESPACE_API_SERVER/v2/appsessions/<appSessionId>/logfiles?Limit=500 |
  jq '.Items[] | select(.Path == "Reports.zip") | .Id')

bs download file -i $logFileID -o output

use names instead of IDs in a command

bs launch application -n "DRAGEN Germline" --app-version 3.3.7 \
  -o project-id:$(bs get project -n "my-project" --terse) \
  -o input_list.sample-id:$(bs get biosample -n "my-biosample" --terse)

generate an appsession iCredit summary for a given account

eval $(bs load config default) && bs list appsessions --exec-status Complete --terse | 
  xargs -I@ curl -Ss --fail $BASESPACE_API_SERVER/v2/appsessions/@ -H x-access-token:$BASESPACE_ACCESS_TOKEN | 
  jq -r '[ .Id, .Application.Name, .DateCreated, .DateCompleted, .RunningDuration, .ComputeStatistics.Amount // 0 ] | @csv'
# "160166245","Dragen Joint Genotyping Pipeline","2019-02-11T15:09:14.0000000Z","2019-02-11T15:23:35.0000000Z",661,1
# "159005555","Dragen Joint Genotyping Pipeline","2019-02-08T14:52:40.0000000Z","2019-02-08T15:07:33.0000000Z",610,1
# "173213225","DRAGEN Germline Pipeline","2019-04-09T10:59:57.0000000Z","2019-04-09T12:21:53.0000000Z",4586,7
# "159006521","DRAGEN Germline Pipeline","2019-02-08T10:39:23.0000000Z","2019-02-08T14:07:09.0000000Z",11989,34
# ...

launch an app with every available option for a given setting (e.g. every reference)

APP_NAME="DRAGEN Germline"
VERSION=3.3.7

# get available options for reference setting
references=$(bs launch application -n "${APP_NAME}" --app-version "${VERSION}" --list -f json |
    jq -r 'map(select(.Option | contains("ht-ref")))[0].Choices[:-1][]')

# iterate over options, launch an appsession for each
for reference in $references; do
    bs launch application -n "${APP_NAME}" --app-version "${VERSION}" \
       -o sample-id:123456 -o project-id:1234567 -o reference:"${reference}"
done

sound a terminal bell when an appsession finishes

bs await appsession <appsessionID>; echo -ne "\a"