openfda-cli

AI-native OpenFDA CLI — JSON-only output for autonomous agents. Query the entire openFDA API with a single pip-installable command.

Install

pip install -e .
# or from git:
pip install git+https://github.com/lesterppo/openfda-cli.git

Usage

openfda-cli --endpoint drug/event --limit 5
openfda-cli --endpoint drug/label --query "openfda.generic_name:semaglutide" --fields "indications_and_usage,dosage_and_administration" --limit 2
echo "semaglutide" | openfda-cli --endpoint drug/event --aggregate patient.reaction.reactionmeddrapt --top 15

Endpoints

All 26 openFDA endpoints are supported. The --endpoint flag passes directly to the API.

Category	Endpoints
Drug (6)	drug/event, drug/label, drug/enforcement, drug/ndc, drug/drugsfda, drug/shortages
Device (9)	device/event, device/recall, device/enforcement, device/510k, device/pma, device/classification, device/registrationlisting, device/udi, device/covid19serology
Food (2)	food/enforcement, food/event
Tobacco (4)	tobacco/problem, tobacco/researchpreventionads, tobacco/researchdigitalads, tobacco/researchsmokefree
Other (4)	other/nsde, other/substance, other/unii, other/historicaldocument
Animal & Vet (1)	animalandveterinary/event

Flags

Flag	Purpose
--endpoint	API endpoint (required)
--query	OpenFDA search query string
--limit	Results per page (1-100, default 10)
--fields	Comma-separated field paths for projection
--page	Page number (default 1)
--no-cache	Bypass SQLite cache
--count-only	Return only total result count
--output	Filter response to specific key paths
--aggregate	Field path to aggregate distinct values
--top	Limit aggregation to top N
--batch	Read JSON array of queries from stdin
--version	Print version
--help	Print help

Examples

Drug dosage and indications

openfda-cli --endpoint drug/label \
  --query "openfda.generic_name:semaglutide" \
  --fields "openfda.brand_name,dosage_and_administration,indications_and_usage" \
  --limit 2

Side effects (FAERS aggregation)

openfda-cli --endpoint drug/event \
  --query "patient.drug.openfda.generic_name:semaglutide" \
  --aggregate patient.reaction.reactionmeddrapt --top 15

Drug approval history

openfda-cli --endpoint drug/drugsfda \
  --query "openfda.generic_name:semaglutide" \
  --limit 3

Batch multi-source report

echo '[
  {"id":"adverse","endpoint":"drug/event",
   "query":"patient.drug.openfda.generic_name:semaglutide",
   "limit":50,"aggregate":"patient.reaction.reactionmeddrapt","top":15},
  {"id":"label","endpoint":"drug/label",
   "query":"openfda.generic_name:semaglutide",
   "limit":2,"fields":"openfda.brand_name,indications_and_usage,dosage_and_administration,boxed_warning"},
  {"id":"approval","endpoint":"drug/drugsfda",
   "query":"openfda.generic_name:semaglutide",
   "limit":3,"fields":"application_number,sponsor_name,products.brand_name,products.dosage_form,submissions.submission_status_date"}
]' | openfda-cli --batch --no-cache

Caching

SQLite cache at fda_cache.db with 24-hour TTL. Field projection is applied after cache retrieval, so different --fields values share cache entries. Use --no-cache to bypass.

For AI Agents

See skills/openfda-cli.md for a detailed skill file with field paths per endpoint, search syntax, error types, and report generation patterns.