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. You must be on the MSK VPN for this tool to work.

Install

1. Clone the repo

git clone https://github.com/mskcc/acela-cli.git
cd acela-cli

2. Create a virtual environment so acela-cli's dependencies don't clash with anything else on your machine. Pick whichever tool you already use — venv (ships with Python) or micromamba:

# venv
python -m venv .venv
source .venv/bin/activate

# micromamba
micromamba create -n acela-cli python=3.11
micromamba activate acela-cli

3. Install

pip install .

Confirm it worked:

acela --help

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

# CSV instead of the default tab-delimited output
acela bam by-cmo-id C-ABCDEF --sep csv

# Any custom delimiter also works
acela bam by-cmo-id C-ABCDEF --sep "|"

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