How to list BaseSpace entities using BaseSpace CLI

One of the key features of the BaseSpace CLI tool is the ability to list the various entities, such as Runs, Projects and Biosamples accessible by the current BaseSpace account. This includes entities owned by as well as those shared with the current user. The list command is a quick way to get Ids and Names of entities, which can then be used as input into downstream BaseSpace CLI commands. In its simplest form the list command is structured as below:

bs list <entity>  

Available BaseSpace entities: appresult, appsession, biosample, dataset, project, run, trash

The example below is a truncated output listing all Runs accessible under the current BaseSpace account. The default output is a table format that is easy for humans to read:

bs list run+------------------------------------------------------------------+-----------+-------------------------------------------------------------------+------------------+| Name | Id | ExperimentName | Status |+------------------------------------------------------------------+-----------+-------------------------------------------------------------------+------------------+| 150109\_NS500101\_0203\_ANextSeq\_500\_V2\_RNA-Seq\_(8plex)\_-\_H3GYJBGXX | 10149162 | NextSeq 500 V2: RNA-Seq (8plex) - H3GYJBGXX | Complete || 150123\_P3018\_0319\_ANextSeq\_500\_V2\_Nano350\_(PhiX)\_H3GNKBGXX | 10383420 | NextSeq 500 V2: Nano350 (PhiX)\_H3GNKBGXX | Complete || 160907\_NB500983\_0241\_AH2LWNBGXY | 20865846 | TruSight\_Tumor\_170\_Example\_Dataset | Complete || 170220\_A00103\_0014\_AHMWVDMCVY | 23564552 | NovaSeq: TruSeq Nano 550 (Replicates of NA12878) | Failed |...  

Fields In the table output, above the column titles (headers) are the default "fields" printed with the simple list run command. These fields can be specified using the -F flag combination in the command to provide more or less information about each result, and tailor the output to the user's desires:

bs list run -F ExperimentName -F Id -F UserOwnedBy.Name+-------------------------------------------------------------------+-----------+-----------------------------------+| ExperimentName | Id | UserOwnedBy.Name |+-------------------------------------------------------------------+-----------+-----------------------------------+| NextSeq 500 V2: RNA-Seq (8plex) - H3GYJBGXX | 10149162 | Illumina Inc || NextSeq 500 V2: Nano350 (PhiX)\_H3GNKBGXX | 10383420 | Illumina Public Data || TruSight\_Tumor\_170\_Example\_Dataset | 20865846 | Illumina Public Data || NovaSeq: TruSeq Nano 550 (Replicates of NA12878) | 23564552 | Illumina Public Data |...  

The various fields can be used to filter results to avoid needing to print and search through the entire list of entities. One can specify the CLI only return results where the field designated with the --filter-field flag contains the string designated with the --filter-term flag:

bs list run --filter-field ExperimentName --filter-term NovaSeq+----------------------------------------------------+-----------+----------------------------------------------------+----------+| Name | Id | ExperimentName | Status |+----------------------------------------------------+-----------+----------------------------------------------------+----------+| 170220\_A00103\_0014\_AHMWVDMCVY | 23564552 | NovaSeq: TruSeq Nano 550 (Replicates of NA12878) | Failed |+----------------------------------------------------+-----------+----------------------------------------------------+----------+  

Filtering In the example above, the results are limited to only those runs where the case-sensitive string "NovaSeq" is found in the field ExperimentName. The string listed in filter-term can comprise all, or part, of the field listed in --filter-field. For example, simply using the string "Seq" will return more matches:

bs list run --filter-field ExperimentName --filter-term Seq+------------------------------------------------------------------+-----------+----------------------------------------------------+----------+| Name | Id | ExperimentName | Status |+------------------------------------------------------------------+-----------+----------------------------------------------------+----------+| 150109\_NS500101\_0203\_ANextSeq\_500\_V2\_RNA-Seq\_(8plex)\_-\_H3GYJBGXX | 10149162 | NextSeq 500 V2: RNA-Seq (8plex) - H3GYJBGXX | Complete || 150123\_P3018\_0319\_ANextSeq\_500\_V2\_Nano350\_(PhiX)\_H3GNKBGXX | 10383420 | NextSeq 500 V2: Nano350 (PhiX)\_H3GNKBGXX | Complete || 170220\_A00103\_0014\_AHMWVDMCVY | 23564552 | NovaSeq: TruSeq Nano 550 (Replicates of NA12878) | Failed || 180117\_SN901\_0713\_ACBTVAANXX | 59519461 | HiSeq 2500: TruSight Oncology UMI Reagents | Failed || 180718\_M04499\_0151\_000000000-BWFHW | 105217112 | Myeloid\_DNA\_Public\_Data\_MiSeq\_11pM | Complete |...  

It is also possible to filter based on the --date-field of an entity using the --newer-than and --older-than flags. The default --date-field is the entity creation date (DateCreated). The example below lists all runs that were created in the past 5 weeks:

bs list run --newer-than 5w+------------------------------------+-----------+------------------------------------+----------+| Name | Id | ExperimentName | Status |+------------------------------------+-----------+------------------------------------+----------+| 180710\_NS500507\_0380\_AH3FWGBGX5 | 103242144 | PhiX-Run | Complete || 180718\_M04499\_0151\_000000000-BWFHW | 105217112 | Myeloid\_DNA\_Public\_Data\_MiSeq\_11pM | Complete |+------------------------------------+-----------+------------------------------------+----------+  

Available time suffixes: s (seconds), m (minutes), h (hours), d (days), w (weeks), y (years)

Formatting There are other options for formatting outputs that may be more useful as input into downstream commands or programs, such as comma-separated value (CSV) lists:

bs list runs --filter-field ExperimentName --filter-term NovaSeq -f csvName,Id,ExperimentName,Status170220\_A00103\_0014\_AHMWVDMCVY,23564552,NovaSeq: TruSeq Nano 550 (Replicates of NA12878),Failed  

Available output formats: yaml,json,xml,csv,table (default)

bs list runs -c bifx --filter-field ExperimentName --filter-term NovaSeq -f json [ { "HrefBaseSpaceUI": "https://basespace.illumina.com/run/23564552/NovaSeq-TruSeq-Nano-550-Replicates-of-NA12878", "Name": "170220\_A00103\_0014\_AHMWVDMCVY", "Id": "23564552",... }]  

The option to output in JSON format is also available, and can provide much more information in a format easily accessible by many downstream programs. Above is the raw output and has been truncated, while below output.json for the full output text:

[ { "HrefBaseSpaceUI": "https://basespace.illumina.com/run/23564552/NovaSeq-TruSeq-Nano-550-Replicates-of-NA12878", "Name": "170220\_A00103\_0014\_AHMWVDMCVY", "Id": "23564552", "DateCreated": "2017-03-21T20:38:16Z", "DateModified": "2019-09-19T16:58:48Z", "DateUploadStarted": null, "DateUploadCompleted": null, "DateInstrumentStarted": "2017-03-21T20:38:14Z", "DateInstrumentCompleted": "2017-03-24T12:16:07Z", "Number": 0, "UserOwnedBy": { "Id": "9319322", "Name": "Illumina Public Data", "GravatarUrl": "https://secure.gravatar.com/avatar/c028aa9f7bb49e5c99efd2c6a329d8d6.jpg?s=20&d=mm&r=PG", "DateLastActive": "", "DateCreated": "0001-01-01T00:00:00.0000000Z" }, "ExperimentName": "NovaSeq: TruSeq Nano 550 (Replicates of NA12878)", "Status": "Failed", "ReagentBarcode": "", "FlowcellBarcode": "", "Instrument": { "InstrumentId": 6970965, "Name": "DA-Test", "SerialNumber": "DA-Test" }, "InstrumentName": "DA-Test", "InstrumentType": "NovaSeq6000", "PlatformName": "NovaSeq", "Workflow": "Generate FASTQ", "NumCyclesRead1": 0, "NumCyclesRead2": 0, "NumCyclesIndex1": 0, "NumCyclesIndex2": 0, "SequencingStats": { "Chemistry": "", "ErrorRate": 0.381995, "ErrorRateR1": 0.311466, "ErrorRateR2": 0.452525, "IntensityCycle1": 823.545, "IsIndexed": true, "MaxCycleCalled": 318, "MaxCycleExtracted": 318, "MaxCycleScored": 318, "MinCycleCalled": 318, "MinCycleExtracted": 318, "MinCycleScored": 318, "NonIndexedErrorRate": 0.381995, "NonIndexedIntensityCycle1": 779.075, "NonIndexedPercentAligned": 1.26232, "NonIndexedPercentGtQ30": 92.4524, "NonIndexedProjectedTotalYield": 1333.43, "NonIndexedYieldTotal": 1333.43, "NumCyclesIndex1": 8, "NumCyclesIndex2": 8, "NumCyclesRead1": 151, "NumCyclesRead2": 151, "NumLanes": 2, "NumReads": 4, "NumSurfaces": 2, "NumSwathsPerLane": 1, "NumTilesPerSwath": 88, "PercentAligned": 1.26232, "PercentGtQ30": 92.6168, "PercentGtQ30R1": 95.6105, "PercentGtQ30R2": 89.2943, "PercentPf": 0.771596, "PercentResynthesis": 69.8303, "PhasingR1": 0.0937093, "PhasingR2": 0.0713997, "PrePhasingR1": 0.0738698, "PrePhasingR2": 0.04491, "ProjectedTotalYield": 1395.65, "ReadsPfTotal": 17781898240, "ReadsTotal": 23045603328, "YieldTotal": 1395.65 }, "LaneAndQcStatus": "QcPassed", "LimsStatus": "NoLims", "TotalSize": 438164818891, "IsFileDataDeleted": false, "IsArchived": false }]  

For any feedback or questions regarding this article (Illumina Knowledge Article #3682), contact Illumina Technical Support [email protected].