CLI Restricted Endpoint Examples

The HCA CLI provides users of the Human Cell Atlas (HCA) to access and download data sets from the HCA. This page covers how to access the HCA using the HCA command line utility.

The CLI calls listed here are restricted to those with upload or ingest permissions. Data will be submitted through a single Ingestion Service API. Submitted data will go through basic quality assurance before it is deposited into the Data Storage System (DSS) component.

In the document that follows, privileged user refers to a user with proper credentials and permission to upload/ingest data into the DSS.

NOTE: The HCA CLI utility is compatible with Python 3.5+.

hca delete-bundle

Deletes an existing bundle given a UUID, version, and replica.

Example call to hca delete-bundle:

#!/usr/bin/env bash

hca dss delete-bundle --reason test --replica gcp --uuid 98f6c379-cb78-4a61-9310-f8cc0341c0ea --version 2019-08-02T202456.025543Z

hca put-bundle

Creates a bundle. A bundle can contain multiple files of arbitrary type.

Inputs:

• uuid - a unique, user-created UUID.
• creator-uid - a unique user ID (uid) for the bundle creator uid. This accepts integer values.
• version - a unique, user-created version number. Use the create_verson() API function to generate a DSS_VERSION.
• replica - which replica to use (corresponds to cloud providers; choices: aws or gcp)

• files - a valid list of file objects, separated by commas (e.g., [{<first_file>}, {<second_file>}, ...  ]). Each file object must include the following details:

  • Valid UUID of the file
  • Valid version number of the file
  • Name of the file
  • Boolean value - is this file indexed

Example call to put_bundle():

#!/usr/bin/env bash

hca dss put-bundle --creator-uid 0 --replica aws --uuid 98f6c379-cb78-4a61-9310-f8cc0341c0ea --version 2019-08-02T202456.025543Z --files '{"uuid": "2196a626-38da-4489-8b2f-645d342f6aab", "version": "2019-07-10T001103.121000Z" , "name": "process_1.json", "indexed":false}'

hca patch-bundle

Allows user to pass in an optional list of files to add or remove from an exisiting bundle.

add_files/remove_files follow this format:

[
  {
    "path": "string",
    "type": "string",
    "uuid": "string",
    "version": "string"
  }
]

Example call to hca patch-bundle:

 #!/usr/bin/env bash

hca dss patch-bundle --replica aws --uuid 98f6c379-cb78-4a61-9310-f8cc0341c0ea --version 2019-08-02T202456.025543Z

hca put-file

Creates a new version of a file, given an existing UUID, version, creator uid, and source URL.

Example call to hca put-file:

#!/usr/bin/env bash

hca dss put-file --uuid 38f6c379-cb78-4a61-9310-f8cc0341c0eb --version 2019-07-30T164352.961501Z --creator-uid 0 --source-url s3://org-humancellatlas-dss-cli-test/930a927d-0138-4a79-8c87-e45936fe4fc3/get_bundle.json

hca get-collection(s), hca put-collection, hca patch-collection, hca delete-collection

• hca get-collection - Given a collection UUID, get the collection.
• hca get-collections - Get a list of collections for a given user.
• hca delete-collection - Given a collection UUID and replica, delete the collection from the replica.
• hca put-collection - Create a collection.
• hca patch-collection - Add or remove a given list of files from an existing collection.

To add or remove files with the CLI actions above, specify each file in the following format:

[
  {
    "path": "string",
    "type": "string",
    "uuid": "string",
    "version": "string"
  }
]

Example CLI calls:

#!/usr/bin/env bash

info_instance=$(hca dss put-collection --uuid fff01947-bf94-43e9-86ca-f6ff6ae45d2c --description foo --details {} --version 2018-09-17T161441.564206Z --replica aws --name bar --contents '{"path": "https://dss.dev.data.humancellatlas.org/v1/bundles/ff818282-9735-45fa-a094-e9f2d3d0a954?version=2019-08-06T170839.843085Z&replica=aws", "version": "2019-08-06T170839.843085Z", "type": "bundle", "uuid": "ff818282-9735-45fa-a094-e9f2d3d0a954"}')

ID=`echo ${info_instance} | jq -r '.uuid'`
VERSION=`echo ${info_instance} | jq -r '.version'`

hca dss get-collections

hca dss patch-collection --replica aws --uuid $ID --verison $VERSION

hca dss get-collection --replica aws --uuid $ID

hca dss delete-collection --replica aws --uuid $ID

hca upload

Uploads a directory of files from the local filesystem and creates a bundle containing the uploaded files.

Example call to hca upload:

#!/usr/bin/env bash

hca dss upload --src-dir data/ --replica aws --staging-bucket upload-test-unittest

aws s3 rm s3://upload-test-unittest --recursive

Links: Index / Module Index / Search Page