biobank-client

Docker image packaging the Indiana Biobank CLI client for programmatic access to the Indiana Biobank Clinical Genomic Research Portal API.

The core CLI tool (biobank-client) is auto-generated from the portal's OpenAPI specification and wraps the REST API as shell commands. This repository provides the Dockerfile and supporting scripts to ship that tool as a self-contained container, suitable for use in automated pipelines and batch workflows.

For end-user documentation on using the container or the CLI interactively within the Trusted Research Environment, see the platform docs.

Contents

File	Description
Dockerfile	Builds the container image (Debian 12, zsh, oh-my-zsh, jq)
biobank-client	Auto-generated CLI tool (OpenAPI Generator v7)
biobank-client.bash-completion	Bash tab-completion for the CLI
_biobank-client	Zsh tab-completion for the CLI
entrypoint.sh	Default entrypoint: lists all cohort files to /data/out/available_files.txt

Build

docker build . --platform=linux/amd64 \
  -t biobank-api-client \
  -t harbor.sca.iu.edu/biobank/biobank-api-client:latest

Push to Harbor

docker push harbor.sca.iu.edu/biobank/biobank-api-client:latest

Usage

Configuration

The container requires environment variables for authentication. The recommended approach is a .env file (keep it out of version control):

API_BASE_URL=https://api.biobank.sca.iu.edu
API_CREDENTIALS=apiKey:apiSecret

API keys can be generated from your profile page in the research portal.

Interactive shell

Start an interactive zsh session with the CLI on the PATH:

docker run -it --rm --env-file .env \
  harbor.sca.iu.edu/biobank/biobank-api-client:latest

Inside the container, API_BASE_URL and API_CREDENTIALS are already set, so you can run commands directly:

biobank-client getCohortFiles id=<cohort-id>
biobank-client downloadCohortFile file_id=<file-id>
biobank-client searchCohorts search_term=my-cohort

Run biobank-client -h for the full operation list.

Default entrypoint: list cohort files

The default entrypoint paginates through all files for a cohort and writes a JSON array to /data/out/available_files.txt, then exits. Useful for verifying connectivity or enumerating files before a full workflow run.

Requires COHORT_ID in addition to the two auth variables:

docker run --rm \
  --env-file .env \
  -e COHORT_ID=<your-cohort-id> \
  -v /local/path/to/output:/data/out \
  harbor.sca.iu.edu/biobank/biobank-api-client:latest

The output file contains a JSON array of file objects. To find a cohort ID, use searchCohorts in the interactive container (see above) or contact the Biobank team.