Updated for version: 1.3.59

Command line (CLI) bindings for Basepair's API. The CLI bindings are just a wrapper around the Python bindings, which are more fully featured. So if there is something you cannot do via the command line, then check out the Python API. An outline of the contents on this page:

  • Setup
    • Installation
    • Setup your configuation
  • Examples
    • Listing available data
    • Creating or deleting a sample
    • Create an analysis
    • Download results


1.0 Requirements

Requires Python version 3. We no longer support Python 2.

1.1 Installation:

You need to first install the basepair Python package. If you don't have pip, you can get it here.

pip install basepair

Once you have it installed you should have available to you at the command line the "basepair" tool. Try running the following in your terminal:

basepair -h

1.2 Configuration:

Step 1

You need to obtain your configuration file to connect to Basepair's API. To obtain the file:

  1. Go to your Basepair dashboard: https://app.basepairtech.com
  2. Click on your profile name in the top right corner.
  3. Click on "Profile".
  4. Click on "Download API config file" in the upper right corner.

When you do get your configuration file it should look like the following:

  "api": {
    "host": "https://app.basepairtech.com/",
    "prefix": "api/v1/",
    "username": "user@basepairtech.com",
    "api_key": ""
  "aws": {
    "s3": {
      "bucket": "basepair"
    "aws_id": "",
    "aws_secret": ""

The "api_key", "aws_id", and "aws_secret" are codes unique to your account and allow you to access Basepair and your data.

Step 2

Then to make this file available to your API calls you can do one of the following:

Option 1: Define an environment variable

export BP_CONFIG_FILE=/path/to/basepair.config.json

Option 2: Give it as a parameter when calling basepair:

basepair --config /path/to/basepair.config.json


1. Listing available data

You can list various types of data available to you. By default the "basepair list" command prints data in a human-readable table format, which does not all data associated with each item, only the critical data. If you want to see all data associated with each item then include the "--json" flag.

1.1 List genomes

The following will print the genomes available:

basepair list genomes -c basepair.config.json

Which will output the following:

  id  name                     date_created
----  -----------------------  --------------------------
   1  hg19                     2018-04-18T14:58:15.865993
   2  mm10                     2018-04-18T15:05:39.770488
   3  mm9                      2018-04-18T15:10:33.438603
   4  danRer10                 2018-04-18T15:15:11.281866
   5  tair10                   2018-04-18T15:17:19.582104
   6  dm6                      2018-04-18T15:23:27.298556
   7  danRer7                  2018-04-18T15:28:12.977544
   8  sacCer3                  2018-04-18T15:30:50.993198
   9  SL2.40                   2018-04-18T15:31:50.603006
  10  Xla.v91                  2018-04-18T15:36:55.491452
  11  xenTro7                  2018-04-18T15:43:42.386466
  12  taeGut2                  2018-04-18T15:44:56.550366
  13  Streptococcus_sanguinis  2018-04-18T15:45:06.695995
  14  CENPK113-7D-RP           2018-04-18T15:45:26.305311
  15  rn6                      2018-04-18T15:46:13.155202
  16  susScr11                 2018-04-18T15:48:53.443899
  17  ce11                     2018-04-18T15:49:32.644737
  18  Manis_javanica           2018-04-18T16:09:05.805615
  19  Ictalurus_punctatus      2018-04-18T16:16:12.306990
  20  mouse_GRCm38_M18         2018-10-04T15:40:16.284047
  21  Citrus_clementina.v1     2018-10-04T15:46:23.320161
  22  Nematostella_vectensis   2018-10-26T18:06:36.340901
  23  Gallus_gallus            2018-10-30T14:02:58.811138

1.2 List your analyses

You can list out all the analyses that you have done. This can be useful for getting the analysis' ids (for download), total file size, and more.

basepair list analyses \
    -c basepair.config.json 

1.3 List files for an analysis

To see what files are in a specific analysis you can run the code below. This can be useful for when you want to download an analysis but you only want certain files, which you can do by providing specific tags to filter the files by.

basepair list analysis \
    -c config.json \
    -u 16146

Which will output something like this:

id: 16146
name: DNA-Seq QC, Alignment (BWA) on Modified Genome 1
date_created: 2017-11-30T15:59:35.436706
completed_on: 2017-12-01T04:01:16.461192
sample ids: 12318

    id    filesize (Gigabytes)  source             name                                               tags
------  ----------------------  -----------------  -------------------------------------------------  -------------------------------------------
218373                  0.0000  FastQC             Modified_Genome_1.pe.per-base-quality.png          ['fastqc', 'per_base', 'figure', 'pe']
218369                  0.0000  FastQC             Modified_Genome_1.overrepresented.json             ['fastqc', 'overrepresented', 'json']
218549                  0.0000  Coverage           Modified_Genome_1.hg19.dedup.coverage-plot.png     ['coverage', 'plot']
218548                  0.0001  Coverage           Modified_Genome_1.hg19.dedup.coverage-summary.xls  ['coverage', 'report']
218547                  0.0082  Remove duplicates  Modified_Genome_1.hg19.dedup.bam.bai               ['bai', 'dedup']
218546                 43.6390  Remove duplicates  Modified_Genome_1.hg19.dedup.bam                   ['bam', 'dedup']
218545                  0.0000  Summary            Modified_Genome_1.hg19.alignment-summary.png       ['alignment_summary', 'figure']
218527                  0.0000  BWA                Modified_Genome_1.hg19.alignment-summary.json      ['alignment_summary', 'json']
218529                  0.0000  BWA                Modified_Genome_1.hg19.alignment-summary.txt       ['alignment_summary', 'text']
218530                  0.0082  BWA                Modified_Genome_1.hg19.bam.bai                     ['bai']
218528                 56.5115  BWA                Modified_Genome_1.hg19.bam                         ['bam']
218371                  0.0000  FastQC             Modified_Genome_1.pe.overrepresented.json          ['fastqc', 'overrepresented', 'json', 'pe']
218372                  0.0001  FastQC             Modified_Genome_1_fastqc.zip                       ['fastqc', 'zip']
218370                  0.0001  FastQC             Modified_Genome_1.pe_fastqc.zip                    ['fastqc', 'zip', 'pe']
218368                  0.0000  FastQC             Modified_Genome_1.per-base-quality.png             ['fastqc', 'per_base', 'figure']

1.4 Other things to list

A few other things you can do include printing out workflows available and your samples:

basepair list workflow -c basepair.config.json
basepair list samples -c basepair.config.json

2. Creating or deleting a sample

The following creates a sample named "test" that consists of a paired-end RNA-seq dataset from human (hg19).

basepair create sample \
    -c basepair.config.json \
    --name Sample1 \
    --genome hg19 \
    --datatype rna-seq \
    --file1 reads_1.fq \
    --file2 reads_2.fq

Running the above command will upload your samples and will print out ids for your sample and files. Here is the output from the above command:

created: sample with id 19377
  created: upload with id 33355
  created: upload with id 33356

You can also delete a sample:

basepair delete \
    -c basepair.config.json \
    -t sample \
    -s 19377

3. Create an analysis

**WARNING: This section and code to do this are still under construction.***

You can also create and submit an analysis. At a minimum you need to specify the workflow id and sample id(s). The example below creates read mapping and expression quantification (STAR) for the sample we just submitted:

basepair create analysis \
    -c basepair.config.json \
    --w 4 \
    --sample {{sample_id}}

Which will output something like this:

created: analysis 3213 with sample 19377

You can run an analysis with custom parameters like this:

basepair create analysis 
        --w 5
        --sample {{sample_id}}
        --params annotate:upstream:5000 annotate:downstream:5000

In the above command, each parameter is of the format <module>:<variable>:<value>

4. Download results

4.1 Download all analysis files

If you want to download all files for the analysis with id 28683 you can run the following:

basepair download analysis \
    -c basepair.config.json \
    -u {{analysis_id}} \
    -o ./output

4.2 Download certain analysis files

You can also filter the files you want to download using the --tags and --tagkind options. To see what tags are associated with each file, run the "bp list -t analysis -u (analysis_id) " command (an example is at the beginning of this page).

For example, if you want to exclude bam files:

basepair download analysis \
    -c basepair.config.json \
    --tags bam \
    --tagkind diff \
    -u {{analysis_id}} \
    -o ./output

If you want only files that exactly match two tags:

basepair download analysis \
    -c basepair.config.json \
    --tags tag1 tag2 \
    --tagkind exact \
    -u {{analysis_id}} \
    -o ./output

If you want any files that have a particular tag:

basepair download analysis \
    -c basepair.config.json \
    --tags tag1 \
    --tagkind subset \
    -u {{analysis_id}} \
    -o ./output

If you want only files that exactly match one of two sets of tags:

basepair download analysis \
    -c basepair.config.json \
    --tags tag1 tag2 \
    --tags tag3 tag4 \
    --tagkind exact \
    -u {{analysis_id}} \
    -o ./output


4.2 Download a sample's raw files

If you want to download the FASTQ files for your sample:

basepair download sample \
    -c basepair.config.json \
    -u {{sample_id}}