Skip to main content

Human Cell Atlas Data Storage System Command Line Interface

Project description


This repository has been deprecated. For information about accessing Human Cell Atlas data please refer to the Data Browser quick start guide.


This repository is a pip installable Command Line Interface (CLI) and Python library (API) for interacting with the Data Coordination Platform (DCP) of the Human Cell Atlas (HCA).

Currently the hca package supports interaction with the Upload Service and Data Storage Service (DSS) for services such as uploading, downloading, and querying data.

The HCA CLI is compatible with Python versions 3.5+ (we are no longer compatible with Python 2.7, and our last compatible Python 2.7 version was hca==6.4.0).


pip install hca.


Documentation on

Example CLI/API usage:

To see the list of commands you can use, type hca --help.

Configuration management

The HCA CLI supports ingesting configuration from a configurable array of sources. Each source is a JSON file. Configuration sources that follow the first source update the configuration using recursive dictionary merging. Sources are enumerated in the following order (i.e., in order of increasing priority):

  • Site-wide configuration source, /etc/hca/config.json

  • User configuration source, ~/.config/hca/config.json

  • Any sources listed in the colon-delimited variable HCA_CONFIG_FILE

  • Command line options

Array merge operators: When loading a chain of configuration sources, the HCA CLI uses recursive dictionary merging to combine the sources. Additionally, when the original config value is a list, the package supports array manipulation operators, which let you extend and modify arrays defined in underlying configurations. See for a list of these operators.

Service to Service Authorization

Google service credentials must be whitelisted before they will authenticate with the HCA CLI.

Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of your Google service credentials file to authenticate.

One can also use: hca dss login.

See Google service credentials for more information about service accounts. Use the Google Cloud IAM web console to manage service accounts.


To develop on the CLI, first run pip install -r requirements-dev.txt. You can install your locally modified copy of the hca package by running make install in the repository root directory.

To use the command line interface with a local or test DSS, first run hca (or scripts/hca if you want to use the package in-place from the repository root directory). This will create the file ~/.config/hca/config.json, which you can modify to update the value of DSSClient.swagger_url to point to the URL of the Swagger definition served by your DSS deployment. Lastly, the CLI enforces HTTPS connection to the DSS API. If you are connecting to a local DSS, make this change in dcp-cli/hca/util/ in the SwaggerClient object:

scheme = "http"

To use the Python interface with a local or test DSS, pass the URL of the Swagger definition to the DSSClient constructor via the swagger_url parameter:

client = DSSClient(swagger_url="")

You can also layer a minimal config file on top of the default config.json using the HCA_CONFIG_FILE environment variable, for example:

export SWAGGER_URL=""
jq -n .DSSClient.swagger_url=env.SWAGGER_URL > ~/.config/hca/config.staging.json
export HCA_CONFIG_FILE=~/.config/hca/config.staging.json


Before you run tests, first run hca dss login. This will open a browser where you can log in to authenticate with Google. Use an email address from one of the whitelisted domains (in DSS_SUBSCRIPTION_AUTHORIZED_DOMAINS_ARRAY from here).

Then make test.

Primary CI testing is through Travis CI; there is also additional testing with the Gitlab Allspark instance that runs tests for Windows. (Note that Allspark is not open to the public, members of the Human Cell Atlas project can access the Allspark cluster using the Github account associated with the Human Cell Atlas organization on Github.) If submitting PRs that have the potential of being platform-dependent, please ensure the status of “Windows Testing” is verified before merging.


Please report bugs, issues, feature requests, etc. in the HumanCellAtlas/dcp-cli repository on GitHub.

Security Policy

See our Security Policy.


Licensed under the terms of the MIT License.

Project details

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hca-8.0.0.tar.gz (86.5 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page