Look up dogs' OFA health clearances (hips, elbows, eyes, cardiac, DNA) and CHIC status by breed, age, and report year, and roll them up by kennel.
Query OFA's hip, elbow, eye, cardiac, and DNA records from the terminal with every Advanced Search filter. Multi-year searches work correctly (the website keeps only one year per query), every page is fetched, and 'kennels' turns raw records into a ranked list of breeders who actually test.
Quick Start
# Check that the OFA search backend is reachable.
ofa-health-clearances-pp-cli doctor
# Find the breed code OFA uses (AUK for Australian Koolie).
ofa-health-clearances-pp-cli breeds koolie
# List this year's Koolie test records.
ofa-health-clearances-pp-cli results --breed AUK --report-year 2026
# Rank kennels testing young Koolies over three report years.
ofa-health-clearances-pp-cli kennels --breed AUK --born-from 2021 --report-year 2024,2025,2026
# Open one dog's full clearance record, including sire and dam.
ofa-health-clearances-pp-cli dog 2682765
Unique Features
These capabilities aren't available in any other tool for this API.
Breeder vetting
-
kennels — See which kennels in a breed are actively health-testing young dogs, ranked by tested dogs, CHIC dogs, and latest test date.
Reach for this when an agent needs to find breeders who test, since OFA exposes no breeder field and no kennel view.
ofa-health-clearances-pp-cli kennels --breed AUK --born-from 2021 --report-year 2024,2025,2026 --agent
Recipes
Records-first breeder search
ofa-health-clearances-pp-cli kennels --breed AUK --born-from 2021 --report-year 2022,2023,2024,2025,2026
Kennel prefixes of young Koolies tested in the last five report years.
CHIC dogs only
ofa-health-clearances-pp-cli results --breed AS --chic --report-year 2026 --agent --select name,ofa_number,test
Narrow a large breed to CHIC-certified records and keep only the identifying fields.
Hip records for a kennel prefix
ofa-health-clearances-pp-cli results --breed AUK --name AVALON --test HD
Every hip record whose registered name starts with the kennel prefix.
One dog and its parents
ofa-health-clearances-pp-cli dog 2682765 --json
Full registry conclusions plus sire and dam as structured JSON.
Usage
Run ofa-health-clearances-pp-cli --help for the full command reference and flag list.
Paths & environment variables
This CLI separates local files into four path kinds:
| Kind | Contents |
|---|
config | User-editable settings such as config.toml and saved profiles |
data | Durable local data such as data.db |
state | Runtime state such as persisted queries, jobs, and teach.log |
cache | Regenerable HTTP/cache files |
Each kind resolves independently. The ladder is:
- Per-kind env var:
OFA_HEALTH_CLEARANCES_CONFIG_DIR, OFA_HEALTH_CLEARANCES_DATA_DIR, OFA_HEALTH_CLEARANCES_STATE_DIR, or OFA_HEALTH_CLEARANCES_CACHE_DIR
--home <dir> for this invocationOFA_HEALTH_CLEARANCES_HOME for a flat relocated root- XDG env vars:
XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME
- Platform defaults matching existing installs
For containers and agent sandboxes, prefer a single relocated root:
export OFA_HEALTH_CLEARANCES_HOME=/srv/ofa-health-clearances
ofa-health-clearances-pp-cli doctor
Under OFA_HEALTH_CLEARANCES_HOME=/srv/ofa-health-clearances, the four dirs resolve to /srv/ofa-health-clearances/config, /srv/ofa-health-clearances/data, /srv/ofa-health-clearances/state, and /srv/ofa-health-clearances/cache.
MCP servers do not receive CLI flags from the host. Put relocation in the host env block:
{
"mcpServers": {
"ofa-health-clearances": {
"command": "ofa-health-clearances-pp-mcp",
"env": {
"OFA_HEALTH_CLEARANCES_HOME": "/srv/ofa-health-clearances"
}
}
}
}
Precedence matters in fleets: an ambient per-kind variable such as OFA_HEALTH_CLEARANCES_DATA_DIR overrides an explicit --home for that kind. Use OFA_HEALTH_CLEARANCES_HOME or the per-kind variables for durable fleet relocation; treat --home as the weaker per-invocation lever.
Relocation is one-way. Unsetting OFA_HEALTH_CLEARANCES_HOME does not move files back to platform defaults, and doctor cannot find files left under a former root. Move the files manually before unsetting relocation variables.
Existing installs keep working because the platform-default rung matches the legacy layout. Run ofa-health-clearances-pp-cli doctor --fail-on warn to check path warnings in automation.
Commands
backend
Raw OFA Advanced Search backend calls (HTML). Prefer 'results', 'dog', and 'kennels'.
ofa-health-clearances-pp-cli backend detail - Fetch one dog's raw detail page (HTML) by OFA application numberofa-health-clearances-pp-cli backend search - Run one raw Advanced Search query and return the result table rows (20 rows per page)
kennels
ofa-health-clearances-pp-cli kennels - See which kennels in a breed are actively health-testing young dogs, ranked by tested dogs, CHIC dogs, and latest test date.
Self-learning loop
This CLI caches per-question discovery so repeat queries skip the walk and structurally similar queries get answered via entity substitution. The loop also self-captures: every invocation is journaled locally, and failed-flag corrections plus fresh teaches surface as candidates on the next recall for confirm/reject judgment. Agents call recall before discovery and fire teach & after answering. See the ## Automatic learning section in SKILL.md for the full protocol.
ofa-health-clearances-pp-cli recall <query> - Look up cached resources for a query before running discoveryofa-health-clearances-pp-cli teach - Record a query -> resource mapping (silent on success, safe to background with &)ofa-health-clearances-pp-cli learnings list - Inspect taught rowsofa-health-clearances-pp-cli learnings forget <query> - Undo a teachofa-health-clearances-pp-cli learnings candidates - List auto-captured candidates awaiting confirm/rejectofa-health-clearances-pp-cli learnings stats - Local loop metrics: recall hit rate, teach-to-reuse, playbook resolution, candidate countsofa-health-clearances-pp-cli teach-pattern - Install a query/resource template up frontofa-health-clearances-pp-cli teach-lookup - Add an entity mapping (e.g. country code, team alias) for pattern substitution
Pass --no-learn or set OFA_HEALTH_CLEARANCES_NO_LEARN=true to disable the loop for deterministic flows.
The local store's schema version stamp is one-way: once this version of ofa-health-clearances-pp-cli opens the database, older binaries refuse it with a version error — upgrade the binary rather than downgrading.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
ofa-health-clearances-pp-cli backend search
# JSON for scripting and agents
ofa-health-clearances-pp-cli backend search --json
# Filter to specific fields by name
ofa-health-clearances-pp-cli backend search --json --select <field>[,<field>...]
# Dry run — show the request without sending
ofa-health-clearances-pp-cli backend search --dry-run
# Agent mode — JSON + compact + no prompts in one flag
ofa-health-clearances-pp-cli backend search --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 <field>[,<field>...] 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
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 5 API error, 7 rate limited or blocked, 10 config error.
Health Check
ofa-health-clearances-pp-cli doctor
Verifies configuration and connectivity to the API.
Configuration
Run ofa-health-clearances-pp-cli doctor to see the resolved config, data, state, and cache directories. The platform-default config path is ``; --home, OFA_HEALTH_CLEARANCES_HOME, and per-kind env vars can relocate it.
Static request headers can be configured under headers; per-command header overrides take precedence.
Troubleshooting
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- Multi-year search returns only one year's rows on the website — Pass years to --report-year as a comma list; the CLI runs one query per year and merges them.
- Empty results for a breed name — Use the breed code from 'ofa-health-clearances-pp-cli breeds ', not the display name.
- Requests slow or throttled — The CLI rate-limits to 1 request/second by default; narrow --report-year or --born-from to reduce pages.