CLI

The BiomAPI CLI is a zero-dependency Python script that calls the REST API and formats results for the terminal. It also works as an Agent Skill through Claude Code and Codex plugin marketplaces, letting AI assistants process biometry reports directly in conversation.

Processing uploads the source report to BiomAPI. PDF and image extraction also sends the report to Google Gemini; see the Privacy Policy before processing patient data.

See Supported Devices for the list of biometers BiomAPI can extract from.

Installation

Standalone

Download biomapi-cli.zip, unzip it, and run biomapi.py directly — no pip, no dependencies, pure Python 3.11+:

python biomapi.py status
python biomapi.py process report.pdf

Claude Code plugin

/plugin marketplace add mglraimundo/biomapi-cli
/plugin install biomapi-cli@mglraimundo-biomapi-cli

Codex

codex plugin marketplace add mglraimundo/biomapi-cli
codex plugin add biomapi-cli@biomapi

Start a new task after installation so Codex loads the bundled skill.

Source repo: mglraimundo/biomapi-cli

---

Configuration

Interactive setup (saves to ~/.config/biomapi/config):

python biomapi.py configure

Or set directly:

python biomapi.py configure --key biom_your_key_here
python biomapi.py configure --gemini-key AIza_your_key
python biomapi.py configure --show

Priority: CLI flags > environment variables (BIOMAPI_KEY, GEMINI_API_KEY, ESCRS_IOL_CALCULATOR_URL) > config file.

Prefer interactive configuration or environment variables so secrets do not appear in shell history. On POSIX systems, the CLI writes the configuration directory with mode 0700 and the file with mode 0600; on Windows, access follows the user profile’s ACLs.

---

Commands

process

python biomapi.py process report.pdf
python biomapi.py process *.pdf         # Multiple files (concurrent)
python biomapi.py process *.pdf --service-tier slow
python biomapi.py process report.pdf --no-pin

The server enforces its configured per-file upload limit. Multiple files use at most four concurrent workers, while stdout remains in input order. --service-tier standard is the default and costs 1 BiomAI credit per PDF/image; slow costs 0.5 credit and may take substantially longer.

Output includes patient name (as acronym), BiomPIN, BiomAPI URL, and ESCRS IOL Calculator link. When patient identifiers are available, both URLs can include a reversible #biomctx=... fragment so name/ID can be restored in a new browser session. The fragment is not sent in a normal HTTP request, but anyone receiving the complete URL can decode it; treat that URL as patient-identifying data.

The full response is saved beside the source. If that filename already exists, the CLI adds -2, -3, and subsequent numeric suffixes instead of replacing it.

retrieve

python biomapi.py retrieve lunar-rocket-731904

You may also pass a full BiomAPI or ESCRS URL containing #biomctx=... to restore browser-local patient identifiers during retrieval.

export

Generate a ZIP containing combined CSV and XLSX spreadsheets plus the saved JSON responses:

python biomapi.py export result-one.json result-two.json --output ./exports

The command returns the absolute path to biomapi_export.zip as JSON on stdout.

usage

python biomapi.py usage

status

python biomapi.py status

Prints lightweight API status and deployment metadata, including db_id. For active Gemini/database health checks, call GET /api/v1/health directly.

configure

python biomapi.py configure --key biom_...
python biomapi.py configure --gemini-key AIza_...
python biomapi.py configure --show

---

Access tiers

BIOMAPI_KEY	GEMINI_API_KEY	process limit	retrieve limit
—	—	Public biomai quota	Public retrieve quota
✓	—	Custom quota	Custom quota
—	✓	biomai_byok bucket (your Gemini quota)	Public retrieve quota
✓	✓	biomai_byok bucket (your Gemini quota)	Custom quota