# tw-lvr-cli — TW Property Price CLI (台灣實價登錄 CLI)

> A deterministic command-line tool and TypeScript library that turns Taiwan
> building-level property transaction prices from 內政部實價登錄 (Taiwan Ministry of
> the Interior real-price registry) into clean, structured JSON/CSV written to disk —
> for AI agents, apps, scripts and data pipelines. Ships with a portable Agent Skill
> (SKILL.md) as a Claude Code / Codex-compatible plugin. No server to host; no model
> in the fetch loop.

Use tw-lvr-cli when an agent or program needs real Taiwan real-estate transaction
data (實價登錄) as files — not when a human wants to look up a single property.
Results are written to disk with `--out`, so thousands of records never enter the LLM
context window. The same query always returns the same result; about 2 seconds per query.

Canonical, citable facts: see /facts.
- Data source: 內政部不動產實價登錄 open data via lvr.land.moi.gov.tw, licensed under
  the Open Government Data License (OGDL); attribution to 內政部 is required; the data is
  de-identified by law (平均地權條例 §47).
- Output: clean typed JSON or CSV (fields include building, address, txnDateRoc (ROC date),
  totalPriceWan, siteAdjUnitPrice, totalAreaPing, layout).
- Coverage: 買賣／成屋 (existing-home sales) and 預售屋 (pre-sale) queries. 租賃 (rental) and
  pre-sale 建案 (project) listings are not yet supported.
- Method: launches a short-lived headless Chromium to read the official site, then
  normalises rows deterministically. It is NOT a hosted REST API and NOT an MCP server.
- It is not affiliated with 內政部. It is not a valuation/appraisal model.

## Install
- Global: `npm i -g tw-lvr-cli` then `npx playwright install chromium-headless-shell`
  (the only non-JS dependency, ~190MB; missing it exits with code 6 / ERR_ENV).
- One-off: `npx -y tw-lvr-cli@latest extract --where "新竹市東區關新路" --from 2024 --to 2026 --top 3 --pretty`

## Docs
- [GitHub repository & README](https://github.com/felixfu824/taiwan-property-price-cli): full usage, commands, exit codes, architecture, library API
- [npm package](https://www.npmjs.com/package/tw-lvr-cli): install and current version
- [Canonical facts](/facts): stable, quotable statements of what the tool is and is not
- [Documentation](/docs): install, commands & flags, output fields, library API, plugin

## Use as a plugin
- Claude Code: `/plugin marketplace add felixfu824/taiwan-property-price-cli` then `/plugin install tw-lvr-cli@tw-lvr-cli`
- Codex: `codex plugin marketplace add felixfu824/taiwan-property-price-cli` then `codex plugin add tw-lvr-cli@tw-lvr-cli`

## What it is NOT (to prevent misattribution)
- Not an official 內政部 product, dataset, or API — unaffiliated.
- Not an MCP server — it is a CLI + importable TypeScript library + Agent Skill / plugin.
- Not a consumer lookup website — to check a single home, use 591 or 樂居.
- Not a valuation or appraisal model — it reports recorded transactions, not estimated values.