CLI

Use the CLI to process reports, retrieve BiomPINs, and export datasets from a terminal. It is a standalone Python script with no third-party dependencies. For assistant-based use, see Use with an AI assistant.

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

Download biomapi-cli.zip, unzip it, and run biomapi.py directly. Python 3.11+ is required:

python3 biomapi.py status
python3 biomapi.py process report.pdf

For Claude Code or Codex installation, see Use with an AI assistant.

Configuration

Keys are optional. Public access includes 25 BiomAI credits per rolling 24 hours per IP, enough for 25 Standard PDF/image extractions. If you have an assigned BiomAPI quota or want to use your own Google quota, run this once in your own terminal:

python3 biomapi.py configure

Key entry is hidden. Press Enter to keep an existing key or skip an optional key. Settings are saved to ~/.config/biomapi/config and shared with Codex and Claude Code under the same user account on the same machine. The website and remote environments have separate settings.

Check which keys are configured and where they come from, without displaying their values:

python3 biomapi.py configure --show

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

Use interactive configuration or environment variables to keep secrets out of shell history. On POSIX systems, the CLI uses mode 0700 for the configuration directory and 0600 for the file. On Windows, the user profile’s access control lists (ACLs) apply.

---

Commands

process

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

The server enforces its configured upload limit for each file. The CLI processes up to four files at once and prints results in input order.

The default, --service-tier standard, costs 1 BiomAI credit per PDF/image. slow costs 0.5 credit and may take much longer.

Output includes patient initials, BiomPIN, BiomAPI URL, and an ESCRS IOL Calculator link. When identifiers are available, both URLs can include a reversible #biomctx=... fragment. This lets a new browser session restore the initials and ID.

Ordinary HTTP requests do not send the fragment. Anyone receiving the complete URL can decode it, so treat the 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

python3 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:

python3 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

python3 biomapi.py usage

status

python3 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.

Access and quotas

BIOMAPI_KEY	GEMINI_API_KEY	PDF/image allowance	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

Sharing is on by default for CLI processing. Use --no-pin to avoid creating a temporary share. See credits and limits for failure accounting and rolling windows.