pp-zillow

<!-- GENERATED FILE — DO NOT EDIT. This file is a verbatim mirror of library/other/zillow/SKILL.md, regenerated post-merge by tools/generate-skills/. Hand-edits here are silently overwritten on the next regen. Edit the library/ source instead. See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". --> # Zillow — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `zillow-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first: 1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows: ```bash npx -y @mvanhorn/printing-press-library install zillow --cli-only ``` 2. Verify: `zillow-pp-cli --version` 3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill. If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.5 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead: ```bash go install github.com/mvanhorn/printing-press-library/library/other/zillow/cmd/zillow-pp-cli@latest ``` If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds. Sync public Zillow Research time series, compare regions, and build sourced affordability, supply, demand, negotiation, and relocation analysis. Core commands never scrape Zillow.com; optional Bridge requests remain separately authorized and uncached. ## High-value workflows Use `--agent` for JSON, compact output, and non-interactive behavior. ```bash # Resolve names before multi-market comparisons zillow-pp-cli region resolve "Austin, TX" --agent # One-region snapshot and client brief zillow-pp-cli summary "Austin, TX" --agent zillow-pp-cli client-brief "Austin, TX" --income 120000 --format markdown # Explainable compound analysis zillow-pp-cli negotiation "Austin, TX" --agent zillow-pp-cli buy-vs-rent "Austin, TX" --rate 6.5 --years 7 --agent zillow-pp-cli explain --agent -- negotiation # Offline SQLite workflow zillow-pp-cli sync market --agent zillow-pp-cli sql "SELECT metric, COUNT(*) AS rows FROM observations GROUP BY metric" --agent ``` Core commands use 17 public Zillow Research CSV datasets and require no authentication. They never scrape Zillow.com or automate consumer pages. Bridge is separate and optional. Use only with an approved `BRIDGE_ACCESS_TOKEN`: ```bash zillow-pp-cli bridge status --agent zillow-pp-cli bridge request --dataset <approved-dataset-id> --resource Property --top 10 --agent ``` Bridge responses are never cached. Never put its token in command arguments, URLs, notes, or output. ## When Not to Use This CLI Do not activate this CLI for requests that require creating, updating, deleting, publishing, commenting, upvoting, inviting, ordering, sending messages, booking, purchasing, or changing remote state. This printed CLI exposes read-only commands for inspection, export, sync, and analysis. ## Unique Capabilities These capabilities aren't available in any other tool for this API. ### Client decisions - **`affordability gap`** — Compare household income with Zillow's regional homeowner-income-needed estimate. _Use when an agent must turn a generic affordability estimate into a client-specific answer._ ```bash zillow-pp-cli affordability gap "Austin, TX" --income 120000 --agent ``` - **`yield-proxy`** — Join ZORI and ZHVI on a common date for a transparent gross rent-to-value proxy. _Use for quick, explainable rent-versus-value comparisons without pretending the proxy is net yield._ ```bash zillow-pp-cli yield-proxy "Austin, TX" --agent ``` - **`buy-vs-rent`** — Run a visible-assumption ownership-versus-rent cash-flow scenario. _Use when an agent needs an inspectable scenario rather than a black-box recommendation._ ```bash zillow-pp-cli buy-vs-rent "Austin, TX" --rate 6.5 --years 7 --agent ``` - **`negotiation`** — Combine price cuts, sale-to-list ratio, days pending, and inventory into an explainable score. _Use for buyer preparation when every score component must be shown._ ```bash zillow-pp-cli negotiation "Austin, TX" --agent ``` ### Market structure - **`supply-ratio`** — Join inventory and sales nowcast into an approximate months-of-inventory ratio. _Use when an agent needs a compact supply-balance signal with its approximation stated._ ```bash zillow-pp-cli supply-ratio "Austin, TX" --agent ``` - **`turning-points`** — Find dated slope sign reversals across temperature, inventory, days pending, and ZHVI. _Use when an agent must identify when a market changed direction, not merely its current level._ ```bash zillow-pp-cli turning-points "Austin, TX" --months 24 --agent ``` - **`tier-spread`** — Compare bottom-, middle-, and top-tier ZHVI growth. _Use when affordability tiers may be moving differently from the headline market._ ```bash zillow-pp-cli tier-spread "Austin, TX" --agent ``` - **`demand-pressure`** — Combine rental demand and for-sale market momentum with component-level evidence. _Use when an agent must compare rental and ownership demand in one sourced view._ ```bash zillow-pp-cli demand-pressure "Austin, TX" --agent ``` - **`new-build-gap`** — Compare new-construction pricing and sales activity with typical regional home value. _Use when an agent needs to quantify the new-build premium and activity context._ ```bash zillow-pp-cli new-build-gap "Austin, TX" --agent ``` ### Regional screening - **`shortlist`** — Rank regions with explicit user weights and visible min-max-normalized components. _Use for relocation or market-screening work where ranking criteria must remain auditable._ ```bash zillow-pp-cli shortlist --regions "394355,394530" --weight zhvi=-0.4 --weight zori=0.6 --agent ``` - **`breadth`** — Measure rising, falling, and unchanged regions by state or geography type. _Use when an agent needs to tell whether a trend is broad or isolated._ ```bash zillow-pp-cli breadth --months 12 --group-by state --agent -- zhvi ``` ### Evidence quality - **`quality audit`** — Detect missing observations, duplicate regions, coverage gaps, and large monthly jumps. _Use before analysis when freshness, gaps, or anomalous changes could invalidate a conclusion._ ```bash zillow-pp-cli quality audit --jump-threshold 20 --agent -- zhvi ``` - **`explain`** — Show formulas, datasets, freshness behavior, and caveats for compound commands. _Use before relying on a compound score or scenario in consequential work._ ```bash zillow-pp-cli explain --agent -- negotiation ``` ### Agent delivery - **`client-brief`** — Compose deterministic Markdown or JSON briefs from sourced regional metrics. _Use when an agent must hand a human a concise brief without inventing narrative facts._ ```bash zillow-pp-cli client-brief "Austin, TX" --income 120000 --format markdown ``` ## Recipes ### Buyer negotiation brief ```bash zillow-pp-cli negotiation "Austin, TX" --agent ``` Shows leverage score, every component, source dates, and caveats. ### Buy-versus-rent scenario ```bash zillow-pp-cli buy-vs-rent "Austin, TX" --rate 6.5 --years 7 --agent ``` Compares cash flow using visible financing, growth, tax, insurance, maintenance, and transaction assumptions. ### Regional shortlist ```bash zillow-pp-cli shortlist --regions "394355,394530" --weight zhvi=-0.4 --weight zori=0.6 --agent ``` Ranks candidate markets while exposing normalized components and user-supplied weights. ### Compact sourced snapshot ```bash zillow-pp-cli summary "Austin, TX" --agent --select results.region,results.metrics,results.evidence ``` Keeps only the region, core metrics, and evidence fields for low-context agent use. ### Offline SQL ```bash zillow-pp-cli sql "SELECT metric, COUNT(*) AS rows FROM observations GROUP BY metric" --agent ``` Queries normalized observations locally after sync with a read-only SQL gate. ## Command Reference **research** — Official Zillow Research regional time-series downloads. - `zillow-pp-cli research days-pending` — Download monthly metro mean days-to-pending observations. - `zillow-pp-cli research homeowner-income` — Download monthly metro income-needed estimates for a typical home purchase with 20 percent down. - `zillow-pp-cli research inventory` — Download monthly metro for-sale inventory observations. - `zillow-pp-cli research market-temperature` — Download monthly metro market-temperature index observations. - `zillow-pp-cli research new-con-price` — Download monthly metro new-construction median sale prices. - `zillow-pp-cli research new-con-price-per-sqft` — Download monthly metro new-construction median sale price per square foot. - `zillow-pp-cli research new-con-sales` — Download monthly metro new-construction sales counts. - `zillow-pp-cli research price-cut-share` — Download monthly metro share of listings with a price cut. - `zillow-pp-cli research sale-to-list` — Download monthly metro mean sale-to-list ratio observations. - `zillow-pp-cli research sales` — Download monthly metro sales-count nowcast observations. - `zillow-pp-cli research total-monthly-payment` — Download monthly metro total housing payment estimates for a typical home purchase with 20 percent down. - `zillow-pp-cli research zhvf` — Download monthly metro Zillow Home Value Forecast growth observations. - `zillow-pp-cli research zhvi` — Download monthly metro Zillow Home Value Index observations. - `zillow-pp-cli research zhvi-bottom-tier` — Download monthly metro bottom-tier Zillow Home Value Index observations. - `zillow-pp-cli research zhvi-top-tier` — Download monthly metro top-tier Zillow Home Value Index observations. - `zillow-pp-cli research zordi` — Download monthly metro Zillow Observed Renter Demand Index observations. - `zillow-pp-cli research zori` — Download monthly metro Zillow Observed Rent Index observations. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash zillow-pp-cli which "<capability in your own words>" ``` `which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query. ## Auth Setup Public Zillow Research commands require no authentication. Bridge access is optional and requires an approved BRIDGE_ACCESS_TOKEN; the CLI sends it only as bearer authorization and never caches Bridge responses. Run `zillow-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color --yes`. - **Pipeable** — JSON on stdout, errors on stderr - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs: ```bash zillow-pp-cli research days-pending --agent --select id,name,status ``` - **Previewable** — `--dry-run` shows the request without sending - **Offline-friendly** — sync/search commands can use the local SQLite store when available - **Non-interactive** — never prompts, every input is a flag - **Read-only** — do not use this CLI for create, update, delete, publish, comment, upvote, invite, order, send, or other mutating requests ### Response envelope Commands that read from the local store or the API wrap output in a provenance envelope: ```json { "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."}, "results": <data> } ``` Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout. ## Paths and state Agents should treat the CLI's path resolver as part of the runtime contract: - Use `--home <dir>` for one invocation, or set `ZILLOW_HOME=<dir>` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `ZILLOW_CONFIG_DIR`, `ZILLOW_DATA_DIR`, `ZILLOW_STATE_DIR`, `ZILLOW_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `ZILLOW_HOME`, XDG (`XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`), then platform defaults. - `config` contains settings like `config.toml` and profiles. `data` contains `credentials.toml`, `data.db`, cookies, and auth sidecars. `state` contains persisted queries, jobs, and `teach.log`. `cache` contains regenerable HTTP/cache files. - Stored secrets live in `credentials.toml` under the data dir. Existing legacy `config.toml` secrets are read for compatibility and leave `config.toml` on the first auth write. - Run `zillow-pp-cli doctor --fail-on warn` to surface path and credential-location warnings. `agent-context` exposes a schema v4 `paths` block for agents that need the resolved dirs. - For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags: ```json { "mcpServers": { "zillow": { "command": "zillow-pp-mcp", "env": { "ZILLOW_HOME": "/srv/zillow" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `ZILLOW_HOME` or per-kind vars as durable fleet levers, and use `--home` only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing `ZILLOW_HOME`, or `doctor` will not find credentials left under the former root. ## Automatic learning This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a `flag_alias` candidate, and a `teach` on a query family without a playbook auto-synthesizes a `playbook_candidate` from the session's journal. Your job is judgment only: `recall` first, act on surfaced candidates, `teach` the final answer, `playbook amend` when you observe a correction. You never record failures by hand. ### Step 1: `recall` before any discovery Before list/search/drill commands on a new user question, run: ```bash zillow-pp-cli recall "<user's question>" --agent ``` The response envelope: ```json { "query": "...", "normalized": "<normalized form>", "query_entities": ["..."], "found": true | false, "match_score": 0.0, "results": [ { "resource_id": "...", "resource_type": "...", "venue": "...", "confidence": 2, "entity_match": "exact|partial|unknown", "source": "taught|preseed|pattern", "warnings": ["..."] } ], "mismatches": [ /* only when --debug-mismatches */ ],