@seanyao/roll 0.5.0 → 2.602.2

package/lib/model_prices.py

@@ -0,0 +1,194 @@
+"""
+model_prices — list-price table for AI model API pricing.
+
+Pricing is per million tokens (MTok), in the vendor's native currency.
+These are the public list rates; discounts (Pro subscription, prepay
+credits, etc.) are intentionally not modeled — IDEA-025 is about
+cross-account / cross-project comparable cost.
+
+US-VIEW-013: prices are no longer hardcoded here. They live in versioned
+snapshot files under ``lib/prices/snapshot-YYYY-MM-DD.json`` and are loaded
+at module import time. ``roll prices refresh`` produces new snapshots; this
+module never writes — it only loads all snapshots and merges them.
+
+FIX-116: multi-vendor support — snapshots carry ``vendor`` and ``currency``
+fields. All snapshots are loaded and merged into a single PRICES map, with
+each model entry carrying its native ``currency``. Vendor-prefixed model
+names (``deepseek/deepseek-chat``) are resolved by stripping the vendor
+segment when no exact match exists.
+
+Unknown models fall back to the snapshot's ``default_model`` with a stderr
+warning so dashboards don't blank out.
+"""
+
+import json
+import os
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+
+_LIB_DIR = os.path.dirname(os.path.abspath(__file__))
+SNAPSHOT_DIR = os.path.join(_LIB_DIR, "prices")
+
+
+def list_snapshots(snapshot_dir: str = SNAPSHOT_DIR) -> List[str]:
+    """Return absolute paths of all snapshot files, sorted oldest → newest by filename."""
+    if not os.path.isdir(snapshot_dir):
+        return []
+    entries = [
+        os.path.join(snapshot_dir, name)
+        for name in os.listdir(snapshot_dir)
+        if name.startswith("snapshot-") and name.endswith(".json")
+    ]
+    return sorted(entries)
+
+
+def load_snapshot(path: str) -> Dict[str, Any]:
+    """Load a snapshot file and validate its shape."""
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    for key in ("version", "effective_at", "source_url", "prices"):
+        if key not in data:
+            raise ValueError(f"snapshot {path!r} missing required key {key!r}")
+    if not isinstance(data["prices"], dict) or not data["prices"]:
+        raise ValueError(f"snapshot {path!r} has empty or invalid prices map")
+    data.setdefault("default_model", next(iter(data["prices"])))
+    data.setdefault("vendor", "anthropic")
+    data.setdefault("currency", "USD")
+    return data
+
+
+def load_all_snapshots(snapshot_dir: str = SNAPSHOT_DIR) -> List[Dict[str, Any]]:
+    """Load all snapshots, sorted oldest → newest. Raises FileNotFoundError if none."""
+    snaps = list_snapshots(snapshot_dir)
+    if not snaps:
+        raise FileNotFoundError(
+            f"no price snapshots found in {snapshot_dir}; run `roll prices refresh`"
+        )
+    return [load_snapshot(p) for p in snaps]
+
+
+_SNAPSHOTS: List[Dict[str, Any]] = load_all_snapshots()
+_DEFAULT_SNAP: Dict[str, Any] = _SNAPSHOTS[-1]
+
+# Merge PRICES from all snapshots, injecting currency per model.
+# Later snapshots override earlier ones for the same model name.
+PRICES: Dict[str, Dict[str, float]] = {}
+_CURRENCY: Dict[str, str] = {}
+for _snap in _SNAPSHOTS:
+    _snap_currency = _snap.get("currency", "USD")
+    for _model, _rates in _snap["prices"].items():
+        PRICES[_model] = dict(_rates)
+        PRICES[_model]["currency"] = _snap_currency
+        _CURRENCY[_model] = _snap_currency
+
+DEFAULT: str = _DEFAULT_SNAP["default_model"]
+VERSION: str = _DEFAULT_SNAP["version"]
+EFFECTIVE_AT: str = _DEFAULT_SNAP["effective_at"]
+SOURCE_URL: str = _DEFAULT_SNAP["source_url"]
+
+_warned: set = set()
+
+
+def snapshot_meta() -> Tuple[str, str, str]:
+    """Return (version, effective_at, source_url) of the active snapshot."""
+    return VERSION, EFFECTIVE_AT, SOURCE_URL
+
+
+def _resolve(model: Optional[str], prices: Optional[Dict[str, Dict[str, float]]] = None,
+             default: Optional[str] = None) -> Dict[str, float]:
+    table = prices if prices is not None else PRICES
+    fallback = default if default is not None else DEFAULT
+    if not model:
+        return table[fallback]
+    base = model.split("[")[0].rstrip("0123456789-")
+
+    # Direct match: model starts with a known key
+    candidates = [k for k in table if model.startswith(k) or base.startswith(k)]
+    if candidates:
+        return table[max(candidates, key=len)]
+
+    # Vendor prefix: try stripping "vendor/" segment for proxy tools (pi, etc.)
+    if "/" in model:
+        inner = model.split("/", 1)[1]
+        inner_base = inner.split("[")[0].rstrip("0123456789-")
+        for k in table:
+            if inner == k or inner_base == k or inner.startswith(k) or inner_base.startswith(k):
+                return table[k]
+
+    if model not in _warned:
+        _warned.add(model)
+        print(f"[model_prices] warn: unknown model {model!r}, falling back to {fallback}",
+              file=sys.stderr)
+    return table[fallback]
+
+
+def _resolve_name(model: Optional[str],
+                  prices: Optional[Dict[str, Dict[str, float]]] = None,
+                  default: Optional[str] = None) -> str:
+    """Return the canonical model name (key in PRICES) for a given model string.
+
+    Same resolution logic as _resolve, but returns the matched key name
+    instead of the rate dict. Used by currency_for() to find the currency.
+    """
+    table = prices if prices is not None else PRICES
+    fallback = default if default is not None else DEFAULT
+    if not model:
+        return fallback
+    base = model.split("[")[0].rstrip("0123456789-")
+
+    # Direct match: model starts with a known key
+    candidates = [k for k in table if model.startswith(k) or base.startswith(k)]
+    if candidates:
+        return max(candidates, key=len)
+
+    # Vendor prefix: try stripping "vendor/" segment
+    if "/" in model:
+        inner = model.split("/", 1)[1]
+        inner_base = inner.split("[")[0].rstrip("0123456789-")
+        for k in table:
+            if inner == k or inner_base == k or inner.startswith(k) or inner_base.startswith(k):
+                return k
+
+    return fallback
+
+
+_NO_CURRENCY_MATCH = "\x00__no_currency_match__\x00"
+
+
+def currency_for(model: Optional[str]) -> str:
+    """Return the native currency code (USD/CNY) for a model.
+
+    Falls back to 'USD' when the model isn't in any snapshot. FIX-162: resolve
+    with a sentinel default so a *genuinely unknown* model returns USD instead
+    of inheriting the global DEFAULT model's currency (which is a CNY kimi
+    entry — that would mislabel unrelated unknown models as CNY).
+    """
+    name = _resolve_name(model, default=_NO_CURRENCY_MATCH)
+    if name == _NO_CURRENCY_MATCH:
+        return "USD"
+    return _CURRENCY.get(name, "USD")
+
+
+def compute_list_cost(model: Optional[str],
+                      *,
+                      input_tokens: int = 0,
+                      output_tokens: int = 0,
+                      cache_creation_tokens: int = 0,
+                      cache_read_tokens: int = 0,
+                      prices: Optional[Dict[str, Dict[str, float]]] = None,
+                      default: Optional[str] = None) -> float:
+    """Return cost (in native currency) at list price for one cycle's token usage."""
+    p = _resolve(model, prices=prices, default=default)
+    total = (input_tokens         * p["in"]
+           + output_tokens        * p["out"]
+           + cache_creation_tokens * p["cache_create"]
+           + cache_read_tokens    * p["cache_read"]) / 1_000_000
+    return round(total, 4)
+
+
+def total_tokens(*,
+                 input_tokens: int = 0,
+                 output_tokens: int = 0,
+                 cache_creation_tokens: int = 0,
+                 cache_read_tokens: int = 0) -> int:
+    return int(input_tokens + output_tokens + cache_creation_tokens + cache_read_tokens)

package/lib/prices/README.md

@@ -0,0 +1,35 @@
+> **Draft** — auto-generated by roll-doc on 2026-05-28. Review before treating as authoritative.
+
+# lib/prices/ — Model price snapshots
+
+Dated JSON snapshots of AI model list prices, used by `roll loop status` to compute per-cycle cost in both USD and native currency (CNY for pi/DeepSeek/Kimi).
+
+## Files
+
+| File | Contents |
+|------|---------|
+| `snapshot-2026-05-22.json` | Multi-vendor snapshot (Claude, GPT, Gemini, DeepSeek, Kimi, pi) |
+| `snapshot-2026-05-23-deepseek.json` | DeepSeek-specific refresh |
+| `snapshot-2026-05-23-kimi.json` | Kimi-specific refresh |
+
+## Format
+
+Each snapshot is a JSON object keyed by model ID:
+
+```json
+{
+  "claude-opus-4-7": {
+    "input_per_mtok": 15.0,
+    "output_per_mtok": 75.0,
+    "cache_write_per_mtok": 18.75,
+    "cache_read_per_mtok": 1.5,
+    "currency": "USD"
+  }
+}
+```
+
+CNY-priced models (pi, DeepSeek, Kimi) use `"currency": "CNY"`.
+
+## Refresh
+
+`prices_fetcher.py` fetches fresh snapshots from vendor pricing APIs and writes a new dated file here. Run via `roll prices refresh`.

package/lib/prices/snapshot-2026-05-22.json

@@ -0,0 +1,22 @@
+{
+  "version": "2026-05-22",
+  "effective_at": "2026-05-22",
+  "source_url": "https://platform.claude.com/docs/en/about-claude/pricing",
+  "vendor": "anthropic",
+  "currency": "USD",
+  "default_model": "claude-sonnet-4-6",
+  "notes": "Rates per million tokens (USD). cache_create = 5-minute cache write (1.25x input). 1-hour cache writes (2x input) are not modeled — Roll loop uses the default 5m caching only. 2026-05 repricing: Opus 4.5+ moved to $5/$25 base (3x cheaper than Opus 4/4.1).",
+  "prices": {
+    "claude-opus-4-7":   {"in":  5.00, "out": 25.00, "cache_create":  6.25, "cache_read": 0.50},
+    "claude-opus-4-6":   {"in":  5.00, "out": 25.00, "cache_create":  6.25, "cache_read": 0.50},
+    "claude-opus-4-5":   {"in":  5.00, "out": 25.00, "cache_create":  6.25, "cache_read": 0.50},
+    "claude-opus-4-1":   {"in": 15.00, "out": 75.00, "cache_create": 18.75, "cache_read": 1.50},
+    "claude-opus-4":     {"in": 15.00, "out": 75.00, "cache_create": 18.75, "cache_read": 1.50},
+    "claude-sonnet-4-6": {"in":  3.00, "out": 15.00, "cache_create":  3.75, "cache_read": 0.30},
+    "claude-sonnet-4-5": {"in":  3.00, "out": 15.00, "cache_create":  3.75, "cache_read": 0.30},
+    "claude-sonnet-4":   {"in":  3.00, "out": 15.00, "cache_create":  3.75, "cache_read": 0.30},
+    "claude-haiku-4-5":  {"in":  1.00, "out":  5.00, "cache_create":  1.25, "cache_read": 0.10},
+    "claude-haiku-3-5":  {"in":  0.80, "out":  4.00, "cache_create":  1.00, "cache_read": 0.08},
+    "claude-3-5-sonnet": {"in":  3.00, "out": 15.00, "cache_create":  3.75, "cache_read": 0.30}
+  }
+}

package/lib/prices/snapshot-2026-05-23-deepseek.json

@@ -0,0 +1,15 @@
+{
+  "version": "2026-05-23",
+  "effective_at": "2026-05-23",
+  "source_url": "https://api-docs.deepseek.com/zh-cn/quick_start/pricing/",
+  "vendor": "deepseek",
+  "currency": "CNY",
+  "default_model": "deepseek-chat",
+  "notes": "Rates per million tokens in CNY (¥) — DeepSeek's native billing currency; we never convert to USD (the dashboard already shows the currency symbol). deepseek-chat and deepseek-reasoner are both deepseek-v4-flash with different thinking modes — same pricing. deepseek-v4-pro is under a 2.5折 (75% off) promo until Beijing time 2026-05-31 23:59 (normal: in 12 / out 24); after expiry, refresh this snapshot. cache_read is the official cache-hit input price (reduced to 1/10 of launch price since 2026-04-26). cache_create = cache-miss input rate: DeepSeek levies no separate cache-write surcharge, and pi reports cacheWrite cost as 0, so this rate only ever applies to (near-zero) cacheWrite tokens. pi's own per-message cost.total is computed in USD and is kept as cost_reported_usd for audit, NOT used for the authoritative cost.",
+  "prices": {
+    "deepseek-chat":        {"in": 1, "out": 2, "cache_create": 1, "cache_read": 0.02},
+    "deepseek-reasoner":    {"in": 1, "out": 2, "cache_create": 1, "cache_read": 0.02},
+    "deepseek-v4-flash":    {"in": 1, "out": 2, "cache_create": 1, "cache_read": 0.02},
+    "deepseek-v4-pro":      {"in": 3, "out": 6, "cache_create": 3, "cache_read": 0.025}
+  }
+}

package/lib/prices/snapshot-2026-05-23-kimi.json

@@ -0,0 +1,15 @@
+{
+  "version": "2026-05-23",
+  "effective_at": "2026-05-23",
+  "source_url": "https://platform.kimi.com/docs/pricing/chat",
+  "vendor": "kimi",
+  "currency": "CNY",
+  "default_model": "kimi-k2.5",
+  "notes": "Rates per million tokens (CNY). cache_create estimated at 1.25x input. Prices from public Kimi API platform docs — verify with `roll prices refresh` if page layout changes. Model names: kimi-k2 (prior gen), kimi-k2.5 (current), kimi-k2.6 (latest). kimi-for-coding is the kimi-code CLI's model id (alias of the current K2 line) — FIX-162 so usage events tagged `kimi-code/kimi-for-coding` resolve to a real CNY entry instead of falling back to USD.",
+  "prices": {
+    "kimi-k2":   {"in": 1.00, "out": 4.00, "cache_create": 1.25, "cache_read": 0.25},
+    "kimi-k2.5": {"in": 1.00, "out": 4.00, "cache_create": 1.25, "cache_read": 0.25},
+    "kimi-k2.6": {"in": 1.00, "out": 4.00, "cache_create": 1.25, "cache_read": 0.25},
+    "kimi-for-coding": {"in": 1.00, "out": 4.00, "cache_create": 1.25, "cache_read": 0.25}
+  }
+}

package/lib/prices_fetcher.py

@@ -0,0 +1,285 @@
+"""
+prices_fetcher — fetch + parse + diff + write Claude API pricing snapshots.
+
+US-VIEW-013: replaces the hardcoded PRICES table in ``model_prices.py`` with
+versioned JSON snapshots under ``lib/prices/``. The fetcher pulls the live
+pricing docs page, extracts the model rate rows, and writes a new snapshot
+only when the rates differ from the most recent one on disk.
+
+Design:
+  * ``fetch_pricing_html(url, timeout)`` — pure I/O, raises ``FetchError``
+  * ``parse_pricing_html(html)`` — pure parser, raises ``ParseError``
+  * ``diff_prices(old, new)`` — pure diff, returns list of changes
+  * ``write_snapshot(prices, ...)`` — pure I/O, returns the path written
+  * ``refresh(...)`` — orchestrator; the only function with side effects on
+                       both network and disk
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import os
+import re
+import sys
+from html.parser import HTMLParser
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+DEFAULT_SOURCE_URL = "https://platform.claude.com/docs/en/about-claude/pricing"
+DEFAULT_TIMEOUT = 15
+
+_MODEL_RE = re.compile(r"claude-(?:opus|sonnet|haiku)-[0-9](?:-[0-9])?")
+_DOLLAR_RE = re.compile(r"\$\s*([0-9]+(?:\.[0-9]+)?)")
+
+
+class FetchError(RuntimeError):
+    """Raised when fetching the pricing page fails."""
+
+
+class ParseError(ValueError):
+    """Raised when the pricing HTML cannot be parsed into a prices map."""
+
+
+def fetch_pricing_html(url: str = DEFAULT_SOURCE_URL,
+                       timeout: float = DEFAULT_TIMEOUT) -> str:
+    """Fetch the pricing docs page and return its raw HTML."""
+    req = Request(url, headers={"User-Agent": "roll/prices_fetcher"})
+    try:
+        with urlopen(req, timeout=timeout) as resp:
+            data = resp.read()
+            charset = resp.headers.get_content_charset() or "utf-8"
+            return data.decode(charset, errors="replace")
+    except (URLError, OSError, TimeoutError) as exc:
+        raise FetchError(f"could not fetch {url}: {exc}") from exc
+
+
+class _TableTextExtractor(HTMLParser):
+    """Walk an HTML document and yield <tr> cell-text lists per row."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.rows: List[List[str]] = []
+        self._in_row = False
+        self._in_cell = False
+        self._cells: List[str] = []
+        self._cur: List[str] = []
+
+    def handle_starttag(self, tag: str, attrs):  # noqa: ANN001
+        if tag == "tr":
+            self._in_row = True
+            self._cells = []
+        elif tag in ("td", "th") and self._in_row:
+            self._in_cell = True
+            self._cur = []
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in ("td", "th") and self._in_cell:
+            self._cells.append(" ".join(self._cur).strip())
+            self._in_cell = False
+        elif tag == "tr" and self._in_row:
+            if self._cells:
+                self.rows.append(self._cells)
+            self._in_row = False
+
+    def handle_data(self, data: str) -> None:
+        if self._in_cell:
+            self._cur.append(data)
+
+
+def parse_pricing_html(html: str) -> Dict[str, Dict[str, float]]:
+    """Parse pricing docs HTML into a {model: rates} map.
+
+    The parser is intentionally tolerant: it scans every table row, looks for
+    one ``claude-*`` model identifier and four dollar amounts on that row, and
+    treats them as ``in / cache_create / cache_read / out`` in the order they
+    appear. (Anthropic's table renders columns in that order.)
+    """
+    parser = _TableTextExtractor()
+    parser.feed(html)
+
+    prices: Dict[str, Dict[str, float]] = {}
+    for row in parser.rows:
+        text = " ".join(row)
+        model_match = _MODEL_RE.search(text)
+        if not model_match:
+            continue
+        model = model_match.group(0)
+        amounts = [float(m.group(1)) for m in _DOLLAR_RE.finditer(text)]
+        if len(amounts) < 4:
+            continue
+        in_rate, cache_create, cache_read, out_rate = amounts[:4]
+        prices[model] = {
+            "in": in_rate,
+            "out": out_rate,
+            "cache_create": cache_create,
+            "cache_read": cache_read,
+        }
+
+    if not prices:
+        raise ParseError("no price rows found in HTML; page layout may have changed")
+    return prices
+
+
+def diff_prices(old: Dict[str, Dict[str, float]],
+                new: Dict[str, Dict[str, float]]
+                ) -> List[Tuple[str, str, str, Optional[float], Optional[float]]]:
+    """Return a list of (kind, model, field, old_val, new_val) tuples.
+
+    kind is one of: ``added``, ``removed``, ``changed``. For added rows the
+    old_val is None; for removed, the new_val is None.
+    """
+    changes: List[Tuple[str, str, str, Optional[float], Optional[float]]] = []
+    for model in sorted(set(old) | set(new)):
+        if model not in old:
+            for field, val in new[model].items():
+                changes.append(("added", model, field, None, val))
+            continue
+        if model not in new:
+            for field, val in old[model].items():
+                changes.append(("removed", model, field, val, None))
+            continue
+        for field in sorted(set(old[model]) | set(new[model])):
+            old_val = old[model].get(field)
+            new_val = new[model].get(field)
+            if old_val != new_val:
+                changes.append(("changed", model, field, old_val, new_val))
+    return changes
+
+
+def format_diff(changes: List[Tuple[str, str, str, Optional[float], Optional[float]]],
+                colored: bool = True) -> str:
+    """Render diff_prices output as red-/green-coded lines."""
+    if not changes:
+        return ""
+    red = "\033[31m" if colored else ""
+    green = "\033[32m" if colored else ""
+    dim = "\033[2m" if colored else ""
+    reset = "\033[0m" if colored else ""
+    lines: List[str] = []
+    for kind, model, field, old, new in changes:
+        if kind == "added":
+            lines.append(f"{green}+ {model} {field} = {new}{reset}")
+        elif kind == "removed":
+            lines.append(f"{red}- {model} {field} = {old}{reset}")
+        else:
+            lines.append(f"{dim}~ {model} {field}{reset} {red}{old}{reset} → {green}{new}{reset}")
+    return "\n".join(lines)
+
+
+def write_snapshot(prices: Dict[str, Dict[str, float]],
+                   *,
+                   snapshot_dir: str,
+                   source_url: str = DEFAULT_SOURCE_URL,
+                   effective_at: Optional[str] = None,
+                   default_model: Optional[str] = None,
+                   notes: Optional[str] = None) -> str:
+    """Write a new snapshot JSON and return its path."""
+    os.makedirs(snapshot_dir, exist_ok=True)
+    today = effective_at or _dt.date.today().isoformat()
+    payload: Dict[str, Any] = {
+        "version": today,
+        "effective_at": today,
+        "source_url": source_url,
+        "default_model": default_model or _pick_default(prices),
+        "prices": prices,
+    }
+    if notes:
+        payload["notes"] = notes
+    dest = os.path.join(snapshot_dir, f"snapshot-{today}.json")
+    with open(dest, "w", encoding="utf-8") as f:
+        json.dump(payload, f, indent=2, sort_keys=False)
+        f.write("\n")
+    return dest
+
+
+def _pick_default(prices: Dict[str, Dict[str, float]]) -> str:
+    """Pick a sensible fallback model: prefer the cheapest sonnet, else first key."""
+    for k in prices:
+        if "sonnet" in k:
+            return k
+    return next(iter(prices))
+
+
+def refresh(*,
+            snapshot_dir: str,
+            url: str = DEFAULT_SOURCE_URL,
+            timeout: float = DEFAULT_TIMEOUT,
+            html: Optional[str] = None,
+            ) -> Tuple[str, List[Tuple[str, str, str, Optional[float], Optional[float]]]]:
+    """Fetch (or accept fixture HTML), parse, diff against latest snapshot, write.
+
+    Returns (action, changes) where action is one of:
+      ``"unchanged"`` — no diff vs latest snapshot, nothing written
+      ``"written:<path>"`` — new snapshot written at <path>
+      ``"first:<path>"`` — no prior snapshot existed; baseline written
+    """
+    if html is None:
+        html = fetch_pricing_html(url, timeout=timeout)
+    new_prices = parse_pricing_html(html)
+
+    # Load latest if any
+    latest = _latest_snapshot_path(snapshot_dir)
+    if latest is None:
+        dest = write_snapshot(new_prices, snapshot_dir=snapshot_dir, source_url=url)
+        return f"first:{dest}", diff_prices({}, new_prices)
+
+    with open(latest, "r", encoding="utf-8") as f:
+        old = json.load(f).get("prices", {})
+    changes = diff_prices(old, new_prices)
+    if not changes:
+        return "unchanged", []
+    dest = write_snapshot(new_prices, snapshot_dir=snapshot_dir, source_url=url)
+    return f"written:{dest}", changes
+
+
+def _latest_snapshot_path(snapshot_dir: str) -> Optional[str]:
+    if not os.path.isdir(snapshot_dir):
+        return None
+    snaps = sorted(
+        os.path.join(snapshot_dir, n)
+        for n in os.listdir(snapshot_dir)
+        if n.startswith("snapshot-") and n.endswith(".json")
+    )
+    return snaps[-1] if snaps else None
+
+
+# CLI entry — `python3 lib/prices_fetcher.py refresh|show` is the fallback when
+# bin/roll is unavailable (e.g. running tests directly).
+def _main(argv: List[str]) -> int:
+    snapshot_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "prices")
+    if not argv or argv[0] in ("-h", "--help", "help"):
+        print("usage: prices_fetcher.py refresh|show [--url URL]")
+        return 0
+    cmd = argv[0]
+    url = DEFAULT_SOURCE_URL
+    if "--url" in argv:
+        url = argv[argv.index("--url") + 1]
+    if cmd == "show":
+        latest = _latest_snapshot_path(snapshot_dir)
+        if not latest:
+            print("no snapshot found", file=sys.stderr)
+            return 1
+        with open(latest) as f:
+            print(f.read())
+        return 0
+    if cmd == "refresh":
+        try:
+            action, changes = refresh(snapshot_dir=snapshot_dir, url=url)
+        except FetchError as exc:
+            print(f"fetch failed: {exc}", file=sys.stderr)
+            return 2
+        except ParseError as exc:
+            print(f"parse failed: {exc}", file=sys.stderr)
+            return 3
+        print(action)
+        if changes:
+            print(format_diff(changes, colored=sys.stdout.isatty()))
+        return 0
+    print(f"unknown command: {cmd}", file=sys.stderr)
+    return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(_main(sys.argv[1:]))