acela-cli

Command-line client for the Acela BAM mirror API. No curl, no manual token handling — look up BAM files by patient/sample ID and get results as tab-delimited text ready for pandas, read.delim(), or awk.

Install

pip install git+ssh://git@github.com/mskcc/acela-cli.git

First-time setup

acela login

Prompts for your MSKCC username/password once and caches a session token in ~/.acela/credentials.json (file permissions 600). The token is valid for ~90 days; every other command uses it automatically, and you'll only be prompted again once it actually expires.

For scripts/pipelines that can't prompt interactively, set ACELA_USER and ACELA_PASSWORD (or ACELA_TOKEN directly) as environment variables instead.

Usage

# Single lookup, TSV to stdout
acela bam by-cmo-id C-ABCDEF

# Batch lookup from a file (one ID per line)
acela bam by-cmo-id --file cmo_ids.txt > results.tsv

# By DMP patient ID or DMP sample ID
acela bam by-dmp-id P-0001234
acela bam by-sample-id P-0001234-T01-IM6

# Search by DMP ID, optionally narrowed by CMO ID
acela bam find-path P-0001234 --cmo-id C-ABCDEF

# Just file paths, no metadata columns
acela bam by-cmo-id C-ABCDEF --no-metadata

# Raw JSON instead of TSV
acela bam by-cmo-id C-ABCDEF --json

# Write to a file instead of stdout
acela bam by-cmo-id C-ABCDEF -o results.tsv

Configuration

Env var	Purpose
ACELA_ENDPOINT	Override the API base URL (defaults to the prod Voyager host).
ACELA_USER / ACELA_PASSWORD	Non-interactive login for scripts/pipelines.
ACELA_TOKEN	Bypass the credential cache entirely with a pre-issued token.
ACELA_CONFIG_DIR	Override where the cached session is stored (defaults to ~/.acela).

Development

python -m venv .venv && source .venv/bin/activate
pip install -e .
acela --help