CLI Reference

A consolidated reference of every CLI entry point across the project: the buildings-scraper package CLI and the standalone scripts under scripts/. See Data Pipeline Architecture for how these entry points map onto the six scheduled/manual triggers.

buildings-scraper subcommands

Command	Purpose
leads	The core product — discover/enrich/tier buildings for a ZIP or city
benchmark	Compare output coverage against a client benchmark CSV
merge	Merge/union multiple run outputs
stats	Print summary statistics for a run
outreach	Build/send an outreach campaign
followup	Send scheduled follow-up messages
reply	Draft/send a reply to an inbound message
poll	Poll IMAP once for new replies
daemon	Run the reply daemon continuously (IMAP poll loop)
senders	Manage/inspect the outreach sender pool
send	Send a single outreach message
report	Print operational metrics/reporting
db-migrate	Apply warehouse schema migrations
backfill	Backfill warehouse data from CSVs
metrics	Print/refresh warehouse rollup metrics
target	Set/inspect refresh-priority targeting for a property

leads flags

Flag	Purpose
--zip / --city	Scope the run to a ZIP code or a city
--offline	Free layers only — skip paid discovery/resolution
--sources apartments_com,zillow,rentcafe,zumper,hotpads	Restrict which listing aggregators are scraped
--pages N	Aggregator pagination depth
--anchor-max N	Cap SERP queries anchored to a specific building name
--no-crawl	Skip the site-crawl layer
--crawl-max-sites N	Cap distinct sites crawled
--crawl-max-pages N	Cap pages crawled per site
--outlink-sites N	Cap one-hop outlink crawl for portfolio/directory pages
--resolve-max N	Cap website-resolution attempts for URL-less buildings
--ai-enrich	Enable LLM-assisted enrichment
--include-small	Include small buildings normally filtered out
--max-markets N	Cap the number of markets processed in one run
--outreach	Kick off outreach after the run completes

See Discovery & Enrichment for what each discovery layer these flags control actually does.

Standalone scripts (scripts/)

Script	Purpose
metro_sweep.py	Full-metro discovery sweep (paid, manual)
resolve_sweep.py	Resolve missing official websites for URL-less buildings
unit_sweep.py	Fetch/refresh floorplan & unit data (--tier hql\|phql\|both, --refresh-only, --budget, --max-seconds, --warehouse require\|skip, --csv-mirror, --metro)
enrich_sweep.py	Weekly free enrichment (contacts, commission, PM, re-tier)
hql_quality_gate.py	Post-upsert quality gate; downgrades tiers that fail checks
drain_refresh_queue.py	Drains the on-demand refresh queue (every 10 min on VPS)
plan_refresh_cycle.py	Enqueues buildings due for cadence-based refresh (every 30 min on VPS)
unit_depth_sweep.py	Deep per-unit detail pass (manual, free)
relive_overlay_api.py	Local stdlib-only API backing the (retired) Chrome extension in dev
relive_overlay_ingest.py	Rebuilds the Relive-comparison tables in the warehouse
resync_warehouse_csvs.py	One-directional CSV → warehouse resync
cost_report.py	Regenerates the cost-optimization report
calibrate_cost.py	Recalibrates the per-request cost rate
coverage_by_approach.py	Measures discovery coverage by source/approach
run_enrich_sample.py / run_live_full_sample.py	Offline/live enrichment sampling for QA

See Warehouse Schema for the tables db-migrate, backfill, enrich_sweep.py, and drain_refresh_queue.py read and write.

Testing/lint

See Development for full detail.

uv run pytest -q
uv run ruff check src/ tests/
uv run mypy src/buildings_scraper/

Note

Some scripts — for example the Windows-scheduled .ps1 wrappers — are documented in Scheduled Jobs rather than here, since their invocation is tied to a specific scheduler rather than being a plain CLI call.