# 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, search | Retrieve gene information and annotations |
| **disease** | get, search | Get disease definitions and synonyms |
| **drug** | get, search | Retrieve drug information from MyChem.info |
| **organization** | search | Search NCI organization database |
| **intervention** | search | Find interventions (drugs, devices, procedures) |
| **biomarker** | search | Search biomarkers used in trials |
| **openfda** | various | Search FDA data (adverse events, drug labels) |
| **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/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 with optional functional enrichment analysis.
```bash
biomcp gene get GENE_NAME [OPTIONS]
```
**Options:**
- `--enrich TEXT`: Enrichment analysis type (feature in development)
- `--json, -j`: Output in JSON format
**Available enrichment types (feature in development):**
- pathway, kegg, reactome, wikipathways
- ontology, go_process, go_molecular, go_cellular
- celltypes, tissues
- diseases, gwas
- transcription_factors, tf
- `--enrich, -e TEXT`: Add functional enrichment analysis (pathway, ontology, celltypes, etc.)
- `--json, -j`: Output in JSON format
**Available Enrichment Types:**
| Category | Short Name | Full Database Name |
| ------------- | ----------------------- | -------------------------- |
| Pathways | `pathway` | KEGG_2021_Human |
| | `kegg` | KEGG_2021_Human |
| | `reactome` | Reactome_2022 |
| | `wikipathways` | WikiPathways_2024_Human |
| Gene Ontology | `ontology` | GO_Biological_Process_2021 |
| | `go_process` | GO_Biological_Process_2021 |
| | `go_molecular` | GO_Molecular_Function_2021 |
| | `go_cellular` | GO_Cellular_Component_2021 |
| Cell Types | `celltypes` | PanglaoDB_Augmented_2021 |
| | `tissues` | Human_Gene_Atlas |
| Diseases | `diseases` | DisGeNET |
| | `gwas` | GWAS_Catalog_2023 |
| TFs | `transcription_factors` | ChEA_2022 |
| | `tf` | ChEA_2022 |
**Examples:**
```bash
# Get basic gene information
biomcp gene get TP53
biomcp gene get BRAF
# Gene information with enrichment (feature in development)
biomcp gene get TP53 --enrich pathway
biomcp gene get BRCA1 --enrich ontology
biomcp gene get EGFR --enrich celltypes
# JSON output
biomcp gene get TP53 --json
```
### gene search
# Basic gene information
biomcp gene get TP53
biomcp gene get BRAF
# With pathway enrichment
biomcp gene get TP53 --enrich pathway
# With Gene Ontology enrichment
biomcp gene get BRCA1 --enrich ontology
# With cell type associations
biomcp gene get EGFR --enrich celltypes
# Using full database name
biomcp gene get TP53 --enrich KEGG_2021_Human
# JSON output with enrichment
biomcp gene get TP53 --enrich pathway --json
````
**Note:** Enrichment analysis is powered by the Enrichr API and inspired by [gget enrichr](https://github.com/pachterlab/gget) (Luebbert & Pachter, 2023).
### drug get
Search for genes in MyGene.info database.
```bash
biomcp gene search QUERY [OPTIONS]
````
**Options:**
- `--page, -p INTEGER`: Page number (default: 1)
- `--page-size INTEGER`: Results per page (default: 10, max: 100)
- `--json, -j`: Output in JSON format
**Examples:**
```bash
# Search by gene symbol
biomcp gene search TP53
# Search by gene name
biomcp gene search "tumor protein"
# Search with pagination
biomcp gene search kinase --page 2 --page-size 20
```
### 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"
biomcp disease get GIST
```
### disease search
Search for diseases in MyDisease.info or NCI CTS database.
```bash
biomcp disease search [NAME] [OPTIONS]
```
**Options:**
- `--source TEXT`: Data source: 'mydisease' (default) or 'nci'
- `--category TEXT`: Disease category/type filter (NCI only)
- `--page INTEGER`: Page number (default: 1)
- `--page-size INTEGER`: Results per page (default: 20, max: 100)
- `--api-key TEXT`: NCI API key (required for NCI source)
**Examples:**
```bash
# Search MyDisease.info (default)
biomcp disease search melanoma
# Search NCI cancer terms
biomcp disease search melanoma --source nci
# Filter by category
biomcp disease search --category neoplasm --source nci
```
## Drug Commands
Retrieve comprehensive drug information from MyChem.info, which aggregates data from multiple sources including DrugBank, ChEMBL, PubChem, and more.
### drug get
Retrieve detailed drug information by name or identifier.
```bash
biomcp drug get DRUG_ID_OR_NAME [OPTIONS]
```
**Arguments:**
- `DRUG_ID_OR_NAME`: Drug name, trade name, or identifier (DrugBank ID, ChEMBL ID, PubChem CID)
**Options:**
- `--json, -j`: Output in JSON format
**Examples:**
```bash
# Get drug information by name
biomcp drug get imatinib
biomcp drug get aspirin
# Get drug by identifier
biomcp drug get DB00945 # DrugBank ID
biomcp drug get CHEMBL25 # ChEMBL ID
# JSON output for programmatic use
biomcp drug get imatinib --json
```
**Output includes:**
- Drug identifiers (DrugBank, ChEMBL, PubChem, ChEBI, UNII)
- Description and mechanism of action
- Trade names and synonyms
- Chemical properties
- Links to external databases
### drug search
Search for drugs in the MyChem.info database.
```bash
biomcp drug search QUERY [OPTIONS]
```
**Arguments:**
- `QUERY`: Drug name, trade name, or search term
**Options:**
- `--page, -p INTEGER`: Page number (default: 1)
- `--page-size INTEGER`: Results per page (default: 10, max: 100)
- `--json, -j`: Output in JSON format
**Examples:**
```bash
# Search by drug name
biomcp drug search imatinib
# Search by partial name
biomcp drug search "kinase inhibitor"
# Search with pagination
biomcp drug search aspirin --page 2 --page-size 20
# JSON output
biomcp drug search imatinib --json
```
**Note:** Full search with pagination is currently in development. The search currently returns basic drug information for the query term.
## 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
