Skip to content

openfda

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

openfda

README.md

Openfda CLI

The FDA safety data terminal. Every drug adverse event, device recall, food contamination, and product label the FDA publishes — synced locally, searchable offline, with trend analysis no other tool offers.

Created by @H179922 (H179922).

Install

The recommended path installs both the openfda-pp-cli binary and the pp-openfda agent skill (Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, and other agents supported by the upstream skills CLI) in one shot:

npx -y @mvanhorn/printing-press-library install openfda

For CLI only (no skill):

npx -y @mvanhorn/printing-press-library install openfda --cli-only

For skill only — installs the skill into the same agents as the default command above, but skips the CLI binary (use this to update or reinstall just the skill):

npx -y @mvanhorn/printing-press-library install openfda --skill-only

To constrain the skill install to one or more specific agents (repeatable — agent names match the skills CLI):

npx -y @mvanhorn/printing-press-library install openfda --agent claude-code
npx -y @mvanhorn/printing-press-library install openfda --agent claude-code --agent codex

Without Node (Go fallback)

If npx isn't available (no Node, offline), install the CLI directly via Go (requires Go 1.26.6 or newer):

go install github.com/mvanhorn/printing-press-library/library/developer-tools/openfda/cmd/openfda-pp-cli@latest

This installs the CLI only — no skill.

Pre-built binary

Download a pre-built binary for your platform from the latest release. On macOS, clear the Gatekeeper quarantine: xattr -d com.apple.quarantine <binary>. On Unix, mark it executable: chmod +x <binary>.

Install for Hermes

Install the CLI binary first. The installer writes binaries to a per-user managed bin directory by default: $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows.

npx -y @mvanhorn/printing-press-library install openfda --cli-only

Then install the focused Hermes skill.

From the Hermes CLI:

hermes skills install mvanhorn/printing-press-library/cli-skills/pp-openfda --force

Inside a Hermes chat session:

/skills install mvanhorn/printing-press-library/cli-skills/pp-openfda --force

Restart the Hermes session or gateway if the newly installed skill is not visible immediately.

Install for OpenClaw

Install both the CLI binary and the focused OpenClaw skill. The installer defaults binaries to a per-user bin directory ($HOME/.local/bin on macOS/Linux, %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows):

npx -y @mvanhorn/printing-press-library install openfda --agent openclaw

Restart the OpenClaw session or gateway if the newly installed skill is not visible immediately.

Use with Claude Desktop

This CLI ships an MCPB bundle — Claude Desktop's standard format for one-click MCP extension installs (no JSON config required).

To install:

  1. Download the .mcpb for your platform from the latest release.
  2. Double-click the .mcpb file. Claude Desktop opens and walks you through the install.
  3. Fill in FDA_API_KEY when Claude Desktop prompts you.

Requires Claude Desktop 1.0.0 or later. Pre-built bundles ship for macOS Apple Silicon (darwin-arm64) and Windows (amd64, arm64); for other platforms, use the manual config below.

Manual JSON config (advanced)

If you can't use the MCPB bundle (older Claude Desktop, unsupported platform), install the MCP binary and configure it manually.

Install the MCP binary from this CLI's published public-library entry or pre-built release.

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "openfda": {
      "command": "openfda-pp-mcp",
      "env": {
        "FDA_API_KEY": "<your-key>"
      }
    }
  }
}

Quick Start

1. Install

See Install above.

2. Set Up Credentials

Get your API key from your API provider's developer portal. The key typically looks like a long alphanumeric string.

export FDA_API_KEY="<paste-your-key>"

You can also persist this in your config file at ~/.config/openfda-pp-cli/config.json.

3. Verify Setup

openfda-pp-cli doctor

This checks your configuration and credentials.

4. Try Your First Command

openfda-pp-cli animal-events

Usage

Run openfda-pp-cli --help for the full command reference and flag list.

Commands

animal-events

Animal drug and device adverse event reports.

  • openfda-pp-cli animal-events list - Search animal adverse event reports

device-510k

Premarket notification submissions demonstrating substantial equivalence.

  • openfda-pp-cli device-510k list - Search 510(k) clearance records

device-classification

Medical device product codes, specialty areas, and regulatory class.

  • openfda-pp-cli device-classification list - Search device classifications

device-covid19

COVID-19 serological testing evaluation data.

  • openfda-pp-cli device-covid19 list - Search COVID-19 serology test evaluations

device-events

Medical device adverse event reports (MAUDE/MDR) — injuries, deaths, malfunctions.

  • openfda-pp-cli device-events count - Count device events by field
  • openfda-pp-cli device-events list - Search device adverse event reports

device-pma

Class III medical device premarket approval decisions.

  • openfda-pp-cli device-pma list - Search premarket approval records

device-recall-detail

Detailed device recall actions addressing defects or health risks.

  • openfda-pp-cli device-recall-detail list - Search device recall action details

device-recalls

Medical device recall enforcement reports.

  • openfda-pp-cli device-recalls list - Search device recall enforcement reports

device-registration

Medical device manufacturing establishment registrations and product listings.

  • openfda-pp-cli device-registration list - Search device registrations and listings

device-udi

Global Unique Device Identification Database (GUDID).

  • openfda-pp-cli device-udi list - Search unique device identifiers

drug-approvals

FDA-approved drug products since 1939 — applications, submissions, and marketing status.

  • openfda-pp-cli drug-approvals list - Search approved drug products

drug-events

Reports of drug side effects, medication errors, product quality problems (FAERS). 4.9M+ reports since 2003.

  • openfda-pp-cli drug-events count - Count adverse events by field
  • openfda-pp-cli drug-events list - Search drug adverse event reports

drug-labels

Structured product information including prescribing info, black box warnings, indications.

  • openfda-pp-cli drug-labels list - Search drug product labels

drug-ndc

National Drug Code directory — product identifiers, packaging, and classification.

  • openfda-pp-cli drug-ndc list - Search NDC directory

drug-recalls

Drug product recall enforcement reports.

  • openfda-pp-cli drug-recalls count - Count drug recalls by field
  • openfda-pp-cli drug-recalls list - Search drug recall enforcement reports

drug-shortages

Current and historical drug shortages from manufacturing issues, delays, and discontinuations.

  • openfda-pp-cli drug-shortages list - Search drug shortages

food-events

CAERS reports — food, dietary supplement, and cosmetic adverse events.

  • openfda-pp-cli food-events list - Search food/supplement adverse event reports

food-recalls

Food product recall enforcement reports.

  • openfda-pp-cli food-recalls count - Count food recalls by field
  • openfda-pp-cli food-recalls list - Search food recall enforcement reports

nsde

Non-Standardized Drug Entities — drug names that don't map to standard terminology.

  • openfda-pp-cli nsde list - Search non-standardized drug entities

substance

Substance data from the FDA substance registration system.

  • openfda-pp-cli substance list - Search substance records

tobacco-problems

Tobacco product problem reports.

  • openfda-pp-cli tobacco-problems list - Search tobacco problem reports

Output Formats

# Human-readable table (default in terminal, JSON when piped)
openfda-pp-cli animal-events

# JSON for scripting and agents
openfda-pp-cli animal-events --json

# Filter to specific fields
openfda-pp-cli animal-events --json --select id,name,status

# Dry run — show the request without sending
openfda-pp-cli animal-events --dry-run

# Agent mode — JSON + compact + no prompts in one flag
openfda-pp-cli animal-events --agent

Agent Usage

This CLI is designed for AI agent consumption:

  • Non-interactive - never prompts, every input is a flag
  • Pipeable - --json output to stdout, errors to stderr
  • Filterable - --select id,name returns only fields you need
  • Previewable - --dry-run shows the request without sending
  • Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
  • Offline-friendly - sync/search commands can use the local SQLite store when available
  • Agent-safe by default - no colors or formatting unless --human-friendly is set

Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.

Health Check

openfda-pp-cli doctor

Verifies configuration, credentials, and connectivity to the API.

Configuration

Config file: ~/.config/openfda-pp-cli/config.json

Static request headers can be configured under headers; per-command header overrides take precedence.

Environment variables:

Name Kind Required Description
FDA_API_KEY per_call Yes Set to your API credential.

Troubleshooting

Authentication errors (exit code 4)

  • Run openfda-pp-cli doctor to check credentials
  • Verify the environment variable is set: echo $FDA_API_KEY Not found errors (exit code 3)
  • Check the resource ID is correct
  • Run the list command to see available items

Generated by CLI Printing Press