<!--
# COPYRIGHT NOTICE
# This file is part of the "Universal Biomedical Skills" project.
# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
# All Rights Reserved.
#
# This code is proprietary and confidential.
# Unauthorized copying of this file, via any medium is strictly prohibited.
#
# Provenance: Authenticated by MD BABU MIA

-->

# Command Line Interface Reference

BioMCP provides a comprehensive command-line interface for biomedical data retrieval and analysis. This guide covers all available commands, options, and usage patterns.

## Installation

```bash
# Using uv (recommended)
uv tool install biomcp

# Using pip
pip install biomcp-python
```

## Global Options

These options work with all commands:

```bash
biomcp [OPTIONS] COMMAND [ARGS]...

Options:
  --version  Show the version and exit
  --help     Show help message and exit
```

## Commands Overview

| Domain           | Commands             | Purpose                                         |
| ---------------- | -------------------- | ----------------------------------------------- |
| **article**      | search, get          | Search and retrieve biomedical literature       |
| **trial**        | search, get          | Find and fetch clinical trial information       |
| **variant**      | search, get, predict | Analyze genetic variants and predict effects    |
| **gene**         | get                  | Retrieve gene information and annotations       |
| **drug**         | get                  | Look up drug/chemical information               |
| **disease**      | get                  | Get disease definitions and synonyms            |
| **organization** | search               | Search NCI organization database                |
| **intervention** | search               | Find interventions (drugs, devices, procedures) |
| **biomarker**    | search               | Search biomarkers used in trials                |
| **health**       | check                | Monitor API status and system health            |

## Article Commands

For practical examples and workflows, see [How to Find Articles and cBioPortal Data](../how-to-guides/01-find-articles-and-cbioportal-data.md).

### article search

Search PubMed/PubTator3 for biomedical literature with automatic cBioPortal integration.

```bash
biomcp article search [OPTIONS]
```

**Options:**

- `--gene, -g TEXT`: Gene symbol(s) to search for
- `--variant, -v TEXT`: Genetic variant(s) to search for
- `--disease, -d TEXT`: Disease/condition(s) to search for
- `--chemical, -c TEXT`: Chemical/drug name(s) to search for
- `--keyword, -k TEXT`: Keyword(s) to search for (supports OR with `|`)
- `--pmid TEXT`: Specific PubMed ID(s) to retrieve
- `--limit INTEGER`: Maximum results to return (default: 10)
- `--no-preprints`: Exclude preprints from results
- `--no-cbioportal`: Disable automatic cBioPortal integration
- `--format [json|markdown]`: Output format (default: markdown)

**Examples:**

```bash
# Basic gene search with automatic cBioPortal data
biomcp article search --gene BRAF --disease melanoma

# Multiple filters
biomcp article search --gene EGFR --disease "lung cancer" --chemical erlotinib

# OR logic in keywords (find different variant notations)
biomcp article search --gene PTEN --keyword "R173|Arg173|p.R173"

# Exclude preprints
biomcp article search --gene TP53 --no-preprints --limit 20

# JSON output for programmatic use
biomcp article search --gene KRAS --format json > results.json
```

### article get

Retrieve a specific article by PubMed ID or DOI.

```bash
biomcp article get IDENTIFIER
```

**Arguments:**

- `IDENTIFIER`: PubMed ID (e.g., "38768446") or DOI (e.g., "10.1101/2024.01.20.23288905")

**Examples:**

```bash
# Get article by PubMed ID
biomcp article get 38768446

# Get preprint by DOI
biomcp article get "10.1101/2024.01.20.23288905"
```

## Trial Commands

For practical examples and workflows, see [How to Find Trials with NCI and BioThings](../how-to-guides/02-find-trials-with-nci-and-biothings.md).

### trial search

Search ClinicalTrials.gov or NCI CTS API for clinical trials.

```bash
biomcp trial search [OPTIONS]
```

**Basic Options:**

- `--condition TEXT`: Disease/condition to search
- `--intervention TEXT`: Treatment/intervention to search
- `--term TEXT`: General search terms
- `--nct-id TEXT`: Specific NCT ID(s)
- `--limit INTEGER`: Maximum results (default: 10)
- `--source [ctgov|nci]`: Data source (default: ctgov)
- `--api-key TEXT`: API key for NCI source

**Study Characteristics:**

- `--status TEXT`: Trial status (RECRUITING, ACTIVE_NOT_RECRUITING, etc.)
- `--study-type TEXT`: Type of study (INTERVENTIONAL, OBSERVATIONAL)
- `--phase TEXT`: Trial phase (EARLY_PHASE1, PHASE1, PHASE2, PHASE3, PHASE4)
- `--study-purpose TEXT`: Primary purpose (TREATMENT, PREVENTION, etc.)
- `--age-group TEXT`: Target age group (CHILD, ADULT, OLDER_ADULT)

**Location Options:**

- `--country TEXT`: Country name
- `--state TEXT`: State/province
- `--city TEXT`: City name
- `--latitude FLOAT`: Geographic latitude
- `--longitude FLOAT`: Geographic longitude
- `--distance INTEGER`: Search radius in miles

**Advanced Filters:**

- `--start-date TEXT`: Trial start date (YYYY-MM-DD)
- `--end-date TEXT`: Trial end date (YYYY-MM-DD)
- `--intervention-type TEXT`: Type of intervention
- `--sponsor-type TEXT`: Type of sponsor
- `--is-fda-regulated`: FDA-regulated trials only
- `--expanded-access`: Trials offering expanded access

**Examples:**

```bash
# Find recruiting melanoma trials
biomcp trial search --condition melanoma --status RECRUITING

# Search by location (requires coordinates)
biomcp trial search --condition "lung cancer" \
  --latitude 41.4993 --longitude -81.6944 --distance 50

# Use NCI source with advanced filters
biomcp trial search --condition melanoma --source nci \
  --required-mutations "BRAF V600E" --allow-brain-mets true \
  --api-key YOUR_KEY

# Multiple filters
biomcp trial search --condition "breast cancer" \
  --intervention "CDK4/6 inhibitor" --phase PHASE3 \
  --status RECRUITING --country "United States"
```

### trial get

Retrieve detailed information about a specific clinical trial.

```bash
biomcp trial get NCT_ID [OPTIONS]
```

**Arguments:**

- `NCT_ID`: Clinical trial identifier (e.g., NCT03006926)

**Options:**

- `--include TEXT`: Specific sections to include (Protocol, Locations, References, Outcomes)
- `--source [ctgov|nci]`: Data source (default: ctgov)
- `--api-key TEXT`: API key for NCI source

**Examples:**

```bash
# Get basic trial information
biomcp trial get NCT03006926

# Get specific sections
biomcp trial get NCT03006926 --include Protocol --include Locations

# Use NCI source
biomcp trial get NCT04280705 --source nci --api-key YOUR_KEY
```

## Variant Commands

For practical examples and workflows, see:

- [Get Comprehensive Variant Annotations](../how-to-guides/03-get-comprehensive-variant-annotations.md)
- [Predict Variant Effects with AlphaGenome](../how-to-guides/04-predict-variant-effects-with-alphagenome.md)

### variant search

Search MyVariant.info for genetic variant annotations.

```bash
biomcp variant search [OPTIONS]
```

**Options:**

- `--gene TEXT`: Gene symbol
- `--hgvs TEXT`: HGVS notation
- `--rsid TEXT`: dbSNP rsID
- `--chromosome TEXT`: Chromosome
- `--start INTEGER`: Genomic start position
- `--end INTEGER`: Genomic end position
- `--assembly [hg19|hg38]`: Genome assembly (default: hg38)
- `--significance TEXT`: Clinical significance
- `--min-frequency FLOAT`: Minimum allele frequency
- `--max-frequency FLOAT`: Maximum allele frequency
- `--min-cadd FLOAT`: Minimum CADD score
- `--polyphen TEXT`: PolyPhen prediction
- `--sift TEXT`: SIFT prediction
- `--sources TEXT`: Data sources to include
- `--limit INTEGER`: Maximum results (default: 10)
- `--no-cbioportal`: Disable cBioPortal integration

**Note:** When searching by gene, OncoKB clinical actionability data is automatically included for BRAF, ROS1, and TP53 (or all genes if ONCOKB_TOKEN is set).

**Examples:**

```bash
# Search pathogenic BRCA1 variants
biomcp variant search --gene BRCA1 --significance pathogenic

# Search by HGVS notation
biomcp variant search --hgvs "NM_007294.4:c.5266dupC"

# Filter by frequency and prediction scores
biomcp variant search --gene TP53 --max-frequency 0.01 \
  --min-cadd 20 --polyphen possibly_damaging

# Search genomic region
biomcp variant search --chromosome 7 --start 140753336 --end 140753337

# OncoKB integration (uses free demo server for BRAF, ROS1, TP53 automatically)
biomcp variant search --gene BRAF
```

### variant get

Retrieve detailed information about a specific variant. The `--include-external` flag also retrieves clinical actionability data from OncoKB for variants in BRAF, ROS1, and TP53 (or all genes if ONCOKB_TOKEN is set).

```bash
biomcp variant get VARIANT_ID [OPTIONS]
```

**Arguments:**

- `VARIANT_ID`: Variant identifier (HGVS, rsID, or genomic)

**Options:**

- `--include-external / --no-external`: Include annotations from external sources (TCGA, 1000 Genomes, cBioPortal, OncoKB) (default: true)
- `--json, -j`: Output in JSON format
- `--assembly TEXT`: Genome assembly (hg19 or hg38, default: hg19)

**Examples:**

```bash
# Get variant by HGVS (defaults to hg19)
biomcp variant get "NM_007294.4:c.5266dupC"

# Get variant by rsID
biomcp variant get rs121913529

# Specify hg38 assembly
biomcp variant get rs113488022 --assembly hg38

# JSON output with hg38
biomcp variant get rs113488022 --json --assembly hg38

# Without external annotations
biomcp variant get rs113488022 --no-external

# Get variant by genomic coordinates
biomcp variant get "chr17:g.43082434G>A"
```

### variant predict

Predict variant effects using Google DeepMind's AlphaGenome (requires API key).

```bash
biomcp variant predict CHROMOSOME POSITION REFERENCE ALTERNATE [OPTIONS]
```

**Arguments:**

- `CHROMOSOME`: Chromosome (e.g., chr7)
- `POSITION`: Genomic position
- `REFERENCE`: Reference allele
- `ALTERNATE`: Alternate allele

**Options:**

- `--tissue TEXT`: Tissue type(s) using UBERON ontology
- `--interval INTEGER`: Analysis window size (default: 20000)
- `--api-key TEXT`: AlphaGenome API key

**Examples:**

```bash
# Basic prediction (requires ALPHAGENOME_API_KEY env var)
biomcp variant predict chr7 140753336 A T

# Tissue-specific prediction
biomcp variant predict chr7 140753336 A T \
  --tissue UBERON:0002367  # breast tissue

# With per-request API key
biomcp variant predict chr7 140753336 A T --api-key YOUR_KEY
```

## Gene/Drug/Disease Commands

For practical examples using BioThings integration, see [How to Find Trials with NCI and BioThings](../how-to-guides/02-find-trials-with-nci-and-biothings.md#biothings-integration-for-enhanced-search).

### gene get

Retrieve gene information from MyGene.info.

```bash
biomcp gene get GENE_NAME
```

**Examples:**

```bash
# Get gene information
biomcp gene get TP53
biomcp gene get BRAF
```

### drug get

Retrieve drug/chemical information from MyChem.info.

```bash
biomcp drug get DRUG_NAME
```

**Examples:**

```bash
# Get drug information
biomcp drug get imatinib
biomcp drug get pembrolizumab
```

### disease get

Retrieve disease information from MyDisease.info.

```bash
biomcp disease get DISEASE_NAME
```

**Examples:**

```bash
# Get disease information
biomcp disease get melanoma
biomcp disease get "non-small cell lung cancer"
```

## NCI-Specific Commands

These commands require an NCI API key. For setup instructions and usage examples, see:

- [Authentication and API Keys](../getting-started/03-authentication-and-api-keys.md#nci-clinical-trials-api)
- [How to Find Trials with NCI and BioThings](../how-to-guides/02-find-trials-with-nci-and-biothings.md#using-nci-api-advanced-features)

### organization search

Search NCI's organization database.

```bash
biomcp organization search [OPTIONS]
```

**Options:**

- `--name TEXT`: Organization name
- `--city TEXT`: City location
- `--state TEXT`: State/province
- `--country TEXT`: Country
- `--org-type TEXT`: Organization type
- `--api-key TEXT`: NCI API key

**Example:**

```bash
biomcp organization search --name "MD Anderson" \
  --city Houston --state TX --api-key YOUR_KEY
```

### intervention search

Search NCI's intervention database.

```bash
biomcp intervention search [OPTIONS]
```

**Options:**

- `--name TEXT`: Intervention name
- `--intervention-type TEXT`: Type (Drug, Device, Procedure, etc.)
- `--api-key TEXT`: NCI API key

**Example:**

```bash
biomcp intervention search --name pembrolizumab \
  --intervention-type Drug --api-key YOUR_KEY
```

### biomarker search

Search biomarkers used in clinical trials.

```bash
biomcp biomarker search [OPTIONS]
```

**Options:**

- `--gene TEXT`: Gene symbol
- `--biomarker-type TEXT`: Type of biomarker
- `--api-key TEXT`: NCI API key

**Example:**

```bash
biomcp biomarker search --gene EGFR \
  --biomarker-type mutation --api-key YOUR_KEY
```

## Health Command

For monitoring API status before bulk operations, see the [Performance Optimizations Guide](../developer-guides/07-performance-optimizations.md).

### health check

Monitor API endpoints and system health.

```bash
biomcp health check [OPTIONS]
```

**Options:**

- `--apis-only`: Check only API endpoints
- `--system-only`: Check only system resources
- `--verbose, -v`: Show detailed information

**Examples:**

```bash
# Full health check
biomcp health check

# Check APIs only
biomcp health check --apis-only

# Detailed system check
biomcp health check --system-only --verbose
```

## Output Formats

Most commands support both human-readable markdown and machine-readable JSON output:

```bash
# Default markdown output
biomcp article search --gene BRAF

# JSON for programmatic use
biomcp article search --gene BRAF --format json

# Save to file
biomcp trial search --condition melanoma --format json > trials.json
```

## Environment Variables

Configure default behavior with environment variables:

```bash
# API Keys
export NCI_API_KEY="your-nci-key"
export ALPHAGENOME_API_KEY="your-alphagenome-key"
export CBIO_TOKEN="your-cbioportal-token"
export ONCOKB_TOKEN="your-oncokb-token"

# Logging
export BIOMCP_LOG_LEVEL="DEBUG"
export BIOMCP_CACHE_DIR="/path/to/cache"
```

## Getting Help

Every command has a built-in help flag:

```bash
# General help
biomcp --help

# Command-specific help
biomcp article search --help
biomcp trial get --help
biomcp variant predict --help
```

## Tips and Best Practices

1. **Use Official Gene Symbols**: Always use HGNC-approved gene symbols (e.g., "TP53" not "p53")

2. **Combine Filters**: Most commands support multiple filters for precise results:

   ```bash
   biomcp article search --gene EGFR --disease "lung cancer" \
     --chemical erlotinib --keyword "resistance"
   ```

3. **Handle Large Results**: Use `--limit` and `--format json` for processing:

   ```bash
   biomcp article search --gene BRCA1 --limit 100 --format json | \
     jq '.results[] | {pmid: .pmid, title: .title}'
   ```

4. **Location Searches**: Always provide both latitude and longitude:

   ```bash
   # Find trials near Boston
   biomcp trial search --condition cancer \
     --latitude 42.3601 --longitude -71.0589 --distance 25
   ```

5. **Use OR Logic**: The pipe character enables flexible searches:

   ```bash
   # Find articles mentioning any form of a variant
   biomcp article search --gene BRAF --keyword "V600E|p.V600E|c.1799T>A"
   ```

6. **Check API Health**: Before bulk operations, verify API status:
   ```bash
   biomcp health check --apis-only
   ```

## Next Steps

- Set up [API keys](../getting-started/03-authentication-and-api-keys.md) for enhanced features
- Explore [MCP tools](02-mcp-tools-reference.md) for AI integration
- Read [how-to guides](../how-to-guides/01-find-articles-and-cbioportal-data.md) for complex workflows


<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->