Welcome to Gencove's CLI documentation!

Indices and tables

Python library which enables you to use Gencoves' research backend.

Supported Python versions are 3.6 and above.

Quickstart

Installation

To check your default Python version, open an interactive shell and run:

python --version

To check if you have Python 3, open an interactive shell and run:

python3 --version

To install Gencove CLI Tool, open an interactive shell and run:

python<version> -m pip install gencove

If you want Gencove CLI Tool to be installed for your default Python installation, you can instead use:

python -m pip install gencove

Using Gencove CLI Tool

To start using Gencove CLI Tool, open an interactive shell and run:

gencove --help

This will output all available commands.

gencove

Gencove's command line interface.

gencove [OPTIONS] COMMAND [ARGS]...

Options

--version

Show the version and exit.

upload

Upload FASTQ files to Gencove's system.

SOURCE: folder that contains fastq files to be uploaded (acceptable file extensions are .fastq.gz, .fastq.bgz, .fq.gz, .fq.bgz), or .fastq-map.csv file with the mapping of R1/R2 files to related sample by client_id

DESTINATION (optional): gncv://[folder], where the folder is the location on Gencove systems

Examples:

Upload directory contents:

gencove upload test_dataset gncv://test
gencove upload [OPTIONS] SOURCE [DESTINATION]

Options

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

--run-project-id <run_project_id>

Immediately assign all uploaded files to this project and run them

--output <output>

A destination where to store the resulting assignments.

--no-progress

If specified, no progress bar is shown.

--metadata <metadata>

Assign metadata to all samples created from uploads. Only compatible with --run-project-id.

Arguments

SOURCE

Required argument

DESTINATION

Optional argument

download

Download deliverables of a project.

Must specify either project id or sample ids.

Examples:

Download all samples results:

gencove download ./results --project-id d9eaa54b-aaac-4b85-92b0-0b564be6d7db

Download some samples:

gencove download ./results --sample-ids 59f5c1fd-cce0-4c4c-90e2-0b6c6c525d71,7edee497-12b5-4a1d-951f-34dc8dce1c1d

Download specific deliverables:

gencove download ./results --project-id d9eaa54b-aaac-4b85-92b0-0b564be6d7db --file-types alignment-bam,impute-vcf,fastq-r1,fastq-r2

Skip download entirely and print out the deliverables as a JSON:

gencove download - --project-id d9eaa54b-aaac-4b85-92b0-0b564be6d7db --download-urls
gencove download [OPTIONS] DESTINATION

Options

--project-id <project_id>

Gencove project ID

--sample-ids <sample_ids>

A comma separated list of sample ids for which to download the deliverables

--file-types <file_types>

A comma separated list of deliverable file types to download.

--skip-existing, --no-skip-existing

Skip downloading files that already exist in DESTINATION

--download-urls

Output a list of urls in a JSON format.

--download-template <download_template>

Change downloads structure. Defaults to: {client_id}/{gencove_id}/{default_filename}. Available tokens: {client_id} {gencove_id} {file_type} {file_extension} {default_filename}

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

--no-progress

If specified, no progress bar is shown.

Arguments

DESTINATION

Required argument

projects

Project managements commands.

gencove projects [OPTIONS] COMMAND [ARGS]...
create-batch

Create a batch in a project.

gencove projects create-batch [OPTIONS] PROJECT_ID

Options

--batch-type <batch_type>

One of available project's batch types. Use gencove projects list-batch-types command to find out which batch types are available.

--batch-name <batch_name>

User defined batch name.

--sample-ids <sample_ids>

A comma separated list of sample ids for which to create a batch; if not specified use all samples in project

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

Arguments

PROJECT_ID

Required argument

create-merged-vcf

Merge VCF files in a project.

gencove projects create-merged-vcf [OPTIONS] PROJECT_ID

Options

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

Arguments

PROJECT_ID

Required argument

get-batch

Get batch that is available for a project.

gencove projects get-batch [OPTIONS] BATCH_ID

Options

--output-filename <output_filename>

Output filename for batch deliverable.

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

--no-progress

If specified, no progress bar is shown.

Arguments

BATCH_ID

Required argument

get-merged-vcf

Download merged VCF file in a project.

gencove projects get-merged-vcf [OPTIONS] PROJECT_ID

Options

--output-filename <output_filename>

Output filename for merged VCF file.

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

--no-progress

If specified, no progress bar is shown.

Arguments

PROJECT_ID

Required argument

list

List your projects.

gencove projects list [OPTIONS]

Options

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

list-batch-types

List batch types that are available for a project.

gencove projects list-batch-types [OPTIONS] PROJECT_ID

Options

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

Arguments

PROJECT_ID

Required argument

list-batches

List batches that are available for a project.

gencove projects list-batches [OPTIONS] PROJECT_ID

Options

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

Arguments

PROJECT_ID

Required argument

list-samples

List samples in a project.

gencove projects list-samples [OPTIONS] PROJECT_ID

Options

Gencove sample ID, client ID or metadata substring

--status <status>

Get samples with specific status

Options:completed|succeeded|failed|running|all
--archive-status <archive_status>

Get samples with specific archive status

Options:available|archived|restore_requested|all
--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

Arguments

PROJECT_ID

Required argument

restore-samples

Restore samples in a project.

gencove projects restore-samples [OPTIONS] PROJECT_ID

Options

--sample-ids <sample_ids>

A comma separated list of sample ids which will be restored. If omitted, restores all archived samples in project.

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

Arguments

PROJECT_ID

Required argument

run-prefix

Assign all uploads from Gencove prefix to a project. Optionally add metadata to the samples. Uploads can also be filtered through status.

Examples:

Assign uploads to a project:

gencove projects run-prefix 06a5d04b-526a-4471-83ba-fb54e0941758 gncv://my-project/path

Assign uploads to a project with metadata:

gencove projects run-prefix 06a5d04b-526a-4471-83ba-fb54e0941758 gncv://my-project/path --metadata-json='{"batch": "batch1"}'

Assign uploads filtered by status to a project:

gencove projects run-prefix 06a5d04b-526a-4471-83ba-fb54e0941758 gncv://my-project/path --status assigned
gencove projects run-prefix [OPTIONS] PROJECT_ID PREFIX

Options

--metadata-json <metadata_json>

Add metadata to all uploads that are to be assigned to a project.

--status <status>

Filter uploads by status of assignment

Options:all|unassigned|assigned
--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

Arguments

PROJECT_ID

Required argument

PREFIX

Required argument

status-merged-vcf

Get status of merge VCF files job in a project.

gencove projects status-merged-vcf [OPTIONS] PROJECT_ID

Options

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

Arguments

PROJECT_ID

Required argument

uploads

Uploads management commands.

gencove uploads [OPTIONS] COMMAND [ARGS]...
list

List user uploads.

gencove uploads list [OPTIONS]

Options

Filter uploads by gncv path

--status <status>

Filter uploads by status of assignment

Options:all|unassigned|assigned
--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

samples

Sample managements commands.

gencove samples [OPTIONS] COMMAND [ARGS]...
download-file

Download sample file metadata.

SAMPLE_ID specific sample for which to download the results

FILE_TYPE specific deliverable to download results for

DESTINATION path/to/file

Examples:

Download sample:

gencove samples download-file e6b45af7-07c5-4a6d-9f97-6e1efbf3e215 ancestry-json ancestry.json

Download and print to stdout then compress using gzip:

gencove samples download-file e6b45af7-07c5-4a6d-9f97-6e1efbf3e215 ancestry-json - | gzip > ancestry.json.gz
gencove samples download-file [OPTIONS] SAMPLE_ID FILE_TYPE DESTINATION

Options

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

--no-progress

If specified, no progress bar is shown.

Arguments

SAMPLE_ID

Required argument

FILE_TYPE

Required argument

DESTINATION

Required argument

get-metadata

Get sample metadata.

gencove samples get-metadata [OPTIONS] SAMPLE_ID

Options

--output-filename <output_filename>

Output filename for the metadata.

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

Arguments

SAMPLE_ID

Required argument

set-metadata

Set sample metadata.

gencove samples set-metadata [OPTIONS] SAMPLE_ID

Options

--json <json>

JSON string of the metadata to be assigned to a sample. [required]

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

Arguments

SAMPLE_ID

Required argument

s3

S3 imports managements commands.

gencove s3 [OPTIONS] COMMAND [ARGS]...
import

Import all samples from a S3 URI to a project. Optionally add metadata to the samples.

Examples:

Import samples to a project:

gencove s3 import s3://bucket/path/ 06a5d04b-526a-4471-83ba-fb54e0941758

Import samples to a project:

gencove s3 import s3://bucket/path/ 06a5d04b-526a-4471-83ba-fb54e0941758 --metadata-json='{"batch": "batch1"}'
gencove s3 import [OPTIONS] S3_URI PROJECT_ID

Options

--metadata-json <metadata_json>

Add metadata to all samples that are to be imported from S3 to a project.

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

Arguments

S3_URI

Required argument

PROJECT_ID

Required argument

webhooks

Webhook managements commands.

gencove webhooks [OPTIONS] COMMAND [ARGS]...
verify

Verify webhook signature.

SECRET key to be used as a secret for hmac algorithm.

HEADER Gencove-Signature header content.

PAYLOAD JSON payload (i.e., the request’s body).

gencove webhooks verify [OPTIONS] SECRET HEADER PAYLOAD

Arguments

SECRET

Required argument

HEADER

Required argument

PAYLOAD

Required argument

basespace

BaseSpace managements commands.

gencove basespace [OPTIONS] COMMAND [ARGS]...
biosamples

BaseSpace BioSamples management commands.

gencove basespace biosamples [OPTIONS] COMMAND [ARGS]...
list

List all BioSamples from BaseSpace project.

Examples:

List BioSamples of a BaseSpace project:

gencove basespace biosamples list 12345678

List BioSamples of a BaseSpace projects:

gencove basespace biosamples list 12345678,87654321
gencove basespace biosamples list [OPTIONS] BASESPACE_PROJECT_ID

Options

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

Arguments

BASESPACE_PROJECT_ID

Required argument

projects

BaseSpace projects management commands.

gencove basespace projects [OPTIONS] COMMAND [ARGS]...
import

Import all BioSamples from BaseSpace projects to a project. Optionally add metadata to the samples.

Examples:

Import BioSamples to a project:

gencove basespace projects import 12345678 06a5d04b-526a-4471-83ba-fb54e0941758

Import BioSamples from multiple BaseSpace projects to a project:

gencove basespace projects import 12345678,87654321 06a5d04b-526a-4471-83ba-fb54e0941758

Import BioSamples to a project with metadata:

gencove basespace projects import 12345678 06a5d04b-526a-4471-83ba-fb54e0941758 --metadata-json='{"batch": "batch1"}'
gencove basespace projects import [OPTIONS] BASESPACE_PROJECT_IDS PROJECT_ID

Options

--metadata-json <metadata_json>

Add metadata to all samples that are to be imported from BaseSpace to a project.

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable

Arguments

BASESPACE_PROJECT_IDS

Required argument

PROJECT_ID

Required argument

list

List all BaseSpace projects.

Examples:

Import BioSamples to a project:

gencove basespace projects list
gencove basespace projects list [OPTIONS]

Options

--host <host>

Optional Gencove API host, including http/s protocol. Can be passed as GENCOVE_HOST environment variable. Defaults to https://api.gencove.com

--email <email>

Gencove user email to be used in login. Can be passed as GENCOVE_EMAIL environment variable

--password <password>

Gencove user password to be used in login. Can be passed as GENCOVE_PASSWORD environment variable

--api-key <api_key>

Gencove api key. Can be passed as GENCOVE_API_KEY environment variable