earnrate 0.1.2 → 0.1.3

package/README.md

@@ -9,7 +9,7 @@ I wanted a ghost card: one card that always charges the best of my cards. The ca
 
 **earnrate is the best-card decision layer for people and AI agents.** Give it a merchant, and it tells you which card in your wallet earns the most there, and why. It's stateful (it knows your caps and chosen categories), valuation-aware, and transparent about its assumptions. It never sees a card number.
 
-- Runs on your machine. No account, no telemetry, no affiliate links. See the [privacy page](https://earnrate.dev/privacy).
+- Runs on your machine, or in your browser at [earnrate.dev](https://earnrate.dev) with nothing to install. No account, no telemetry, no affiliate links. See the [privacy page](https://earnrate.dev/privacy).
 - US cards and US merchants, for now.
 
 > **Status:** early, and it works: the engine, CLI, optional Claude merchant lookup and MCP server. See [the benchmark](docs/benchmark.md) for how it compares to an existing card-picking MCP server.
@@ -98,6 +98,16 @@ While the bonus is open, that card wins wherever it's accepted, and the answer s
 
 ### Which new card?
 
+No wallet needed for these:
+
+```sh
+earnrate best groceries                               # every card, ranked for one purchase
+earnrate simulate groceries=600 dining=300 other=1000 # best cards and pairs for a year
+earnrate simulate groceries=600 other=1000 --wallet   # what a new card would add to yours
+```
+
+`best` ranks every card earnrate knows for a merchant or a category, each set up at its best (the right category pick, activated, cap unused), with its annual fee and what earning the rate takes. Rates that need a membership like Amazon Prime are listed separately unless you pass `--member amazon-prime`. `simulate` spends your monthly amounts for a year, applying caps as they fill and reset, and ranks single cards and two-card pairs by rewards minus annual fees. Both take `--no-fee`, `--cash` or `--points`, `--issuer`, `--business` and `--valuation`. Welcome bonuses are left out of both; for those:
+
 ```sh
 earnrate offers --cash
 ```
@@ -142,9 +152,10 @@ Spotted a wrong rate, or want a card added? [Open an issue](https://github.com/c
 
 ## Use it from an AI agent (MCP)
 
-`earnrate mcp` runs earnrate as a local MCP server over stdio, with ten tools:
+`earnrate mcp` runs earnrate as a local MCP server over stdio, with twelve tools:
 
 - `best_card_for_purchase`: which card to use, with reasons
+- `best_cards_for` and `simulate_spending`: compare every card earnrate knows, for one purchase or a year of spending, with no wallet needed
 - `resolve_merchant`: how a merchant was identified
 - `list_wallet`: your cards, caps left this period, chosen categories and welcome-bonus progress
 - `compare_welcome_offers`: the best public sign-up offers on cards you don't have
@@ -185,8 +196,8 @@ merchant text
 
 - **Card terms are data, not code.** Each card is a YAML file of rules (category, rate, cap, channel, dates, activation, required membership), validated with Zod. Every rule carries a short quote from the issuer's own page, and a test fails if one is missing. The engine has no card-specific branches.
 - **Merchants resolve to a category plus the assumption behind it.** "Whole Foods codes as a supermarket (MCC 5411)" is stated in the answer, and venues that can code more than one way (a restaurant inside a stadium or hotel) come back at medium confidence with the alternative spelled out. Unknown merchants fall back to base rates, or to an opt-in, cached and labeled Claude guess.
-- **The engine is pure and deterministic.** Given a purchase, a date and a wallet, it checks every rule against network acceptance, the date window, caps already used (split when a purchase straddles one), quarterly picks and activations, then values points at your cents-per-point, including pooling (Freedom Unlimited points are worth Sapphire points when you hold both). Ties, the valuation at which the runner-up would win, and stale data all show up in the answer.
-- **Wallet edits keep your file intact.** Recording a purchase rewrites only the numbers that changed, so comments and formatting in your YAML survive.
+- **The engine is pure and deterministic.** Given a purchase, a date and a wallet, it checks every rule against network acceptance, the date window, caps already used (split when a purchase straddles one), quarterly picks and activations, then values points at your cents-per-point, including pooling (Freedom Unlimited points are worth Sapphire points when you hold both). Ties, the valuation at which the runner-up would win, stale data, and a rotating card whose new quarter isn't in the data yet all show up in the answer.
+- **Wallet edits keep your file intact.** Adding or changing a card, or recording a purchase, splices in only the lines that changed and checks the result before saving, so comments and formatting in your YAML survive.
 - **Drift detection.** A weekly GitHub Action opens each issuer page in a headless browser, checks every quote is still there, and opens an issue when terms move. It stores only hashes of issuer text.
 - **Tested end to end.** Golden cases written from issuer terms, CLI snapshot tests, an MCP round trip over real stdio, an install test that packs and installs the npm package, and a check that no committed file contains a card number. CI runs all of it on every push.
 
@@ -201,6 +212,8 @@ Every rule in `data/cards/` carries a short quote from the issuer's own page. In
 
 A GitHub Action runs it every Monday and opens a "Card source changes" issue when something moved. After updating a card file, run `yarn check-sources --update` to record the new baseline. Some issuers block headless browsers on shared servers; those pages are listed as "couldn't check", and running the command locally covers them. The first run needs `yarn playwright install chromium`.
 
+Rotating categories (Freedom Flex) are added each quarter once the issuer posts them. Until then, answers say that quarter's categories are missing rather than guessing.
+
 ## Working on earnrate
 
 ```sh

package/data/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 Every change to card rules, merchants, categories or currencies under `data/`. Bump `data/VERSION` (`YYYY.MM.DD`, plus `.N` for a second release on the same day) and add a section here in the same commit. Each row cites the issuer page the new value came from.
 
+## 2026.10.30.2
+
+Cards record when the issuer stopped taking applications, so "best card for" lists can leave out cards nobody can get. Categories gain `aliases`, the everyday words people search by ("groceries" finds supermarkets). No rates changed.
+
+| Card             | Field               | Old → new  | Source                                                                      |
+| ---------------- | ------------------- | ---------- | --------------------------------------------------------------------------- |
+| citi-custom-cash | applications_closed | 2026-05-28 | [card page](https://www.citi.com/credit-cards/citi-custom-cash-credit-card) |
+
 ## 2026.10.30.1
 
 Freedom Flex's quarterly cap is marked `rotating`, so a quarter whose categories aren't in the data yet gets a warning instead of quietly ranking Flex at its everyday rates. Capital One's issuer id is now spelled the same on every card. No rates changed.

package/data/VERSION

@@ -1 +1 @@
-2026.10.30.1
+2026.10.30.2

package/data/cards/citi-custom-cash.yaml

@@ -5,9 +5,10 @@ network: mastercard
 currency: cash
 last_verified: 2026-10-26
 verified_by: collin
-# Citi stopped taking applications on May 28, 2026; existing cardmembers keep
-# the card and its rewards. The card page no longer lists the categories, so
-# the definitions come from the card's current ThankYou terms (Sept 2026).
+applications_closed: 2026-05-28
+# Existing cardmembers keep the card and its rewards. The card page no longer
+# lists the categories, so the definitions come from the card's current
+# ThankYou terms (Sept 2026).
 source_urls:
   - https://www.citi.com/credit-cards/citi-custom-cash-credit-card
   - https://www.thankyou.com/ccterms

package/data/categories.yaml

@@ -5,24 +5,30 @@
 
 - id: dining
   name: Restaurants
+  aliases: [dining, restaurant, food, eating out, takeout]
   mccs: [5812, 5813, 5814]
 - id: dining.fast_food
   name: Fast food
+  aliases: [fast food restaurants]
   mccs: [5814]
 
 - id: grocery
   name: Grocery
 - id: grocery.supermarket
   name: Supermarkets
+  aliases: [groceries, grocery, grocery stores, supermarket]
   mccs: [5411]
 - id: grocery.online
   name: Online grocery and delivery
+  aliases: [grocery delivery]
 
 - id: superstore
   name: Superstores
+  aliases: [superstore, big box stores]
   mccs: [5310]
 - id: warehouse_club
   name: Warehouse clubs
+  aliases: [warehouse club, wholesale clubs]
   mccs: [5300]
 
 - id: convenience_store
@@ -31,6 +37,7 @@
 
 - id: gas
   name: Gas stations
+  aliases: [gas, fuel, gas station]
   mccs: [5541, 5542]
 - id: gas.grocery_store
   name: Gas at grocery stores
@@ -38,6 +45,7 @@
   name: Gas at superstores and warehouse clubs
 - id: ev_charging
   name: EV charging
+  aliases: [ev, charging]
   mccs: [5552]
 
 - id: transit
@@ -45,6 +53,7 @@
   mccs: [4111, 4112, 4131, 4784, 7523]
 - id: transit.rideshare
   name: Rideshare and taxis
+  aliases: [rideshare, taxi, taxis]
   mccs: [4121]
 
 - id: travel
@@ -52,41 +61,53 @@
   mccs: [4722]
 - id: travel.flights
   name: Flights
+  aliases: [flights, airfare, airlines]
   mccs: [4511]
 - id: travel.hotels
   name: Hotels
+  aliases: [hotel]
   mccs: [7011]
 - id: travel.car_rental
   name: Car rental
+  aliases: [car rentals, rental cars]
   mccs: [7512]
 - id: travel.cruise
   name: Cruises
+  aliases: [cruise]
   mccs: [4411]
 
 - id: streaming
   name: Streaming services
+  aliases: [streaming, subscriptions]
   mccs: [4899, 5815]
 - id: tv_internet
   name: TV and internet service
+  aliases: [internet, cable]
   mccs: [4899]
 - id: phone
   name: Cell phone service
+  aliases: [phone, cell phone, wireless]
   mccs: [4814]
 - id: utilities
   name: Home utilities
+  aliases: [utilities, electric, electricity]
   mccs: [4900]
 
 - id: drugstore
   name: Drugstores and pharmacies
+  aliases: [drugstores, pharmacy, pharmacies]
   mccs: [5912]
 - id: movie_theaters
   name: Movie theaters
+  aliases: [movies, movie theater]
   mccs: [7832]
 - id: entertainment
   name: Live entertainment and events
+  aliases: [concerts, events, tickets]
   mccs: [7922, 7941]
 - id: fitness
   name: Gyms and fitness
+  aliases: [gym, gyms, fitness]
   mccs: [7997]
 
 - id: department_store
@@ -103,6 +124,7 @@
   mccs: [5941]
 - id: home_improvement
   name: Home improvement
+  aliases: [hardware stores]
   mccs: [5200, 5211]
 - id: furniture
   name: Furniture stores
@@ -110,6 +132,7 @@
 
 - id: online_retail
   name: Online retail
+  aliases: [online shopping, shopping online]
 - id: office_supply
   name: Office supply stores
 - id: shipping
@@ -119,3 +142,4 @@
 
 - id: other
   name: Everything else
+  aliases: [everything, everything else, other]

package/dist/cli/explore.js

@@ -0,0 +1,364 @@
+import { parseArgs } from 'node:util';
+import { CLI_NAME } from "../brand.js";
+import { walletProblems } from "../data/integrity.js";
+import { loadCatalog, walletPath } from "../data/load.js";
+import { ALL_PERSONAL_CARDS, exploreCards, findCategory, } from "../engine/explore.js";
+import { isValuationProfile, VALUATION_PROFILES, withValuationProfile, } from "../engine/profiles.js";
+import { resolveSpendLines, simulateAdditions, simulateCatalog, } from "../engine/simulate.js";
+import { knownMemberships } from "../engine/setup.js";
+import { displayPath, readWallet, RUNTIME_ERROR, USAGE_ERROR, } from "./run.js";
+const FILTER_OPTIONS = `  --cash, --points        Cash back cards only, or points and miles cards only.
+  --no-fee                Cards with no annual fee.
+  --issuer <id>           One issuer's cards, e.g. chase or amex.
+  --business              Business cards instead of personal ones.
+  --closed                Include cards the issuer no longer takes applications for.
+  --member <name>         A membership you have, e.g. amazon-prime. Repeatable.
+  --valuation <profile>   flat (points at 1¢, the default) or points-heavy
+                          (MR and UR at 1.7¢).`;
+export const BEST_HELP = `Usage: ${CLI_NAME} best <merchant or category> [amount] [options]
+
+Ranks every card in earnrate's catalog for one purchase, not just yours. Each
+card is set up at its best: the right category pick, activated, cap unused.
+
+Examples:
+  ${CLI_NAME} best groceries
+  ${CLI_NAME} best amazon 120 --member amazon-prime
+  ${CLI_NAME} best dining --no-fee
+
+Options:
+${FILTER_OPTIONS}
+  --online, --in-store    How you're paying. Default: inferred from the merchant.
+  --date <YYYY-MM-DD>     Purchase date. Default: today.
+  --all                   List every card, not just the top 10.
+  --json                  Print the full result as JSON.
+  -h, --help              Show this help.
+`;
+export const SIMULATE_HELP = `Usage: ${CLI_NAME} simulate <what>=<dollars a month>... [options]
+
+Spends this much every month for a year and ranks the cards, and the
+two-card pairs, that earn the most after annual fees. Each <what> is a
+category (groceries, dining, gas, travel, streaming, other) or a merchant
+(amazon, costco).
+
+Examples:
+  ${CLI_NAME} simulate groceries=600 dining=300 gas=150 other=1000
+  ${CLI_NAME} simulate groceries=600 amazon=150 other=800 --wallet
+
+Options:
+  --wallet                Start from your wallet and rank the cards that would
+                          add the most to it, after their fee.
+${FILTER_OPTIONS}
+  --start <YYYY-MM-DD>    First month of the year simulated. Default: today.
+  --all                   List more results.
+  --json                  Print the full result as JSON.
+  -h, --help              Show this help.
+`;
+const FILTER_FLAGS = {
+    cash: { type: 'boolean' },
+    points: { type: 'boolean' },
+    'no-fee': { type: 'boolean' },
+    issuer: { type: 'string' },
+    business: { type: 'boolean' },
+    closed: { type: 'boolean' },
+    member: { type: 'string', multiple: true },
+    valuation: { type: 'string' },
+    all: { type: 'boolean' },
+    json: { type: 'boolean' },
+    help: { type: 'boolean', short: 'h' },
+};
+function settingsFrom(values, catalog) {
+    if (values.cash && values.points)
+        return 'Pick --cash or --points, not both.';
+    if (values.valuation !== undefined && !isValuationProfile(values.valuation))
+        return `Unknown valuation "${values.valuation}". Use flat or points-heavy.`;
+    const issuers = [...new Set(catalog.cards.map((c) => c.issuer))].sort();
+    if (values.issuer !== undefined && !issuers.includes(values.issuer))
+        return `Unknown issuer "${values.issuer}". Use one of: ${issuers.join(', ')}.`;
+    const known = knownMemberships(catalog);
+    const unknown = (values.member ?? []).filter((m) => !known.includes(m));
+    if (unknown.length > 0)
+        return `Unknown membership "${unknown.join('", "')}". Use one of: ${known.join(', ')}.`;
+    return {
+        filters: {
+            ...ALL_PERSONAL_CARDS,
+            kind: values.cash ? 'cash' : values.points ? 'points' : 'any',
+            business: values.business ?? false,
+            noAnnualFee: values['no-fee'] ?? false,
+            issuer: values.issuer ?? null,
+            includeClosed: values.closed ?? false,
+        },
+        memberships: values.member ?? [],
+        valuations: values.valuation !== undefined && isValuationProfile(values.valuation)
+            ? VALUATION_PROFILES[values.valuation]
+            : {},
+    };
+}
+const usd = (n) => `$${n.toLocaleString('en-US', { minimumFractionDigits: Number.isInteger(n) ? 0 : 2, maximumFractionDigits: 2 })}`;
+const wholeUsd = (n) => usd(Math.round(n));
+const pct = (n) => `${String(Number(n.toFixed(2)))}%`;
+function feeText(e) {
+    if (e.annualFee === null)
+        return 'annual fee not on file';
+    if (e.annualFee === 0)
+        return 'no annual fee';
+    if (e.firstYearFee !== null && e.firstYearFee !== e.annualFee)
+        return `${usd(e.annualFee)} annual fee (${e.firstYearFee === 0 ? 'waived' : usd(e.firstYearFee)} the first year)`;
+    return `${usd(e.annualFee)} annual fee`;
+}
+const TOP_BEST = 10;
+export function formatExploration(r, all) {
+    const m = r.merchant;
+    const title = m.source === 'caller'
+        ? m.resolvedName.toLowerCase()
+        : m.source === 'none'
+            ? `"${m.input}" (not recognized)`
+            : m.resolvedName;
+    if (r.ranked.length === 0)
+        return `No cards match at ${title}.\n`;
+    const shown = all ? r.ranked : r.ranked.slice(0, TOP_BEST);
+    const width = Math.max(...shown.map((e) => e.cardName.length));
+    const lines = [`Best cards for ${title}:`, ''];
+    shown.forEach((e, i) => {
+        const earned = e.earned === null ? '' : `  ${usd(e.earned)}`;
+        lines.push(`${String(i + 1).padStart(2)}. ${e.cardName.padEnd(width)}  ${pct(e.effectiveReturnPct).padStart(5)}${earned}  ${feeText(e)}`);
+        for (const c of e.conditions)
+            lines.push(`    ${c}`);
+        const upgrade = e.withMembership[0];
+        if (upgrade)
+            lines.push(`    With ${upgrade.membership}: ${pct(upgrade.effectiveReturnPct)}.`);
+        for (const w of e.warnings)
+            lines.push(`    ! ${w}`);
+    });
+    if (r.ranked.length > shown.length)
+        lines.push(`  + ${String(r.ranked.length - shown.length)} more (--all lists them)`);
+    for (const w of r.warnings)
+        lines.push('', `! ${w}`);
+    lines.push('', ...r.assumptions);
+    return `${lines.join('\n')}\n`;
+}
+function picksText(picks) {
+    const parts = Object.entries(picks).map(([choice, options]) => `${choice}: ${options.join(', ')}`);
+    return parts.length === 0 ? '' : ` (picks ${parts.join('; ')})`;
+}
+function cardNamer(catalog) {
+    return (id) => catalog.cards.find((c) => c.id === id)?.name ?? id;
+}
+function splitText(sim, name) {
+    const byCard = new Map();
+    for (const line of sim.lines) {
+        const first = line.cards[0];
+        if (first === undefined)
+            continue;
+        byCard.set(first, [...(byCard.get(first) ?? []), line.label]);
+    }
+    return [...byCard].map(([id, labels]) => `${labels.join(', ')} → ${name(id)}`);
+}
+const TOP_SIMULATED = 5;
+export function formatCatalogSimulation(r, catalog, all) {
+    const name = cardNamer(catalog);
+    const first = r.singles[0];
+    if (!first)
+        return 'No cards match.\n';
+    const top = all ? 20 : TOP_SIMULATED;
+    const lines = [
+        `A year of this spending: ${wholeUsd(first.spend)}.`,
+        '',
+        'Best single cards (rewards minus annual fee, per year):',
+    ];
+    r.singles.slice(0, top).forEach((s, i) => {
+        const card = s.cards[0];
+        if (!card)
+            return;
+        lines.push(`${String(i + 1).padStart(2)}. ${name(card.cardId)}  ${wholeUsd(s.net)}  (${wholeUsd(s.rewards)} rewards, ${wholeUsd(s.annualFees)} fee)${picksText(card.picks)}`);
+    });
+    const pairs = r.pairs.slice(0, top);
+    if (pairs.length > 0) {
+        lines.push('', 'Best two-card pairs:');
+        pairs.forEach((s, i) => {
+            lines.push(`${String(i + 1).padStart(2)}. ${s.cards.map((c) => `${name(c.cardId)}${picksText(c.picks)}`).join(' + ')}  ${wholeUsd(s.net)}`);
+            if (s.alternatives.length > 0)
+                lines.push(`    Same result with ${s.alternatives.map(name).join(' or ')} as the second card.`);
+            for (const split of splitText(s, name))
+                lines.push(`    ${split}`);
+        });
+        const bestPair = r.pairs[0];
+        if (bestPair && bestPair.net <= first.net)
+            lines.push('', `One card is enough here: no pair beats ${name(first.cards[0]?.cardId ?? '')}.`);
+    }
+    const notes = new Set([
+        ...r.singles.slice(0, top).flatMap((s) => s.notes),
+        ...pairs.flatMap((s) => s.notes),
+    ]);
+    if (notes.size > 0)
+        lines.push('', ...notes);
+    lines.push('', "Assumes each card's best picks, activations done each quarter, and no welcome bonuses.");
+    return `${lines.join('\n')}\n`;
+}
+export function formatAdditions(r, catalog, all) {
+    const name = cardNamer(catalog);
+    const lines = [
+        `Your wallet earns about ${wholeUsd(r.current.rewards)} a year on this spending${r.current.annualFees > 0 ? `, with ${wholeUsd(r.current.annualFees)} in annual fees` : ''}.`,
+    ];
+    for (const split of splitText(r.current, name))
+        lines.push(`  ${split}`);
+    const gains = r.additions.filter((a) => a.gain > 0);
+    if (gains.length === 0) {
+        lines.push('', 'No card would add more than its annual fee costs.');
+    }
+    else {
+        lines.push('', 'Cards that would add the most (after their annual fee):');
+        gains.slice(0, all ? 20 : TOP_SIMULATED).forEach((a, i) => {
+            lines.push(`${String(i + 1).padStart(2)}. ${name(a.cardId)}  +${wholeUsd(a.gain)} a year  (+${wholeUsd(a.extraRewards)} rewards, ${wholeUsd(a.annualFee)} fee)${picksText(a.picks)}`);
+        });
+    }
+    const notes = new Set(r.current.notes);
+    if (notes.size > 0)
+        lines.push('', ...notes);
+    lines.push('', 'Assumes your picks carry over, rotating categories get activated, and caps start fresh.');
+    return `${lines.join('\n')}\n`;
+}
+export async function runBest(argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                ...FILTER_FLAGS,
+                online: { type: 'boolean' },
+                'in-store': { type: 'boolean' },
+                date: { type: 'string' },
+            },
+        });
+    }
+    catch (e) {
+        io.stderr(`${e instanceof Error ? e.message : String(e)}\n${BEST_HELP}`);
+        return USAGE_ERROR;
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        io.stdout(BEST_HELP);
+        return 0;
+    }
+    const words = [...positionals];
+    const last = words.at(-1);
+    const amount = words.length > 1 && last !== undefined && /^\$?\d+(\.\d+)?$/.test(last)
+        ? Number(last.replace('$', ''))
+        : null;
+    if (amount !== null)
+        words.pop();
+    const text = words.join(' ').trim();
+    if (text === '') {
+        io.stderr(`Say what you're buying, e.g. ${CLI_NAME} best groceries.\n`);
+        return USAGE_ERROR;
+    }
+    if (values.online && values['in-store']) {
+        io.stderr('Pick --online or --in-store, not both.\n');
+        return USAGE_ERROR;
+    }
+    const catalog = await loadCatalog();
+    const settings = settingsFrom(values, catalog);
+    if (typeof settings === 'string') {
+        io.stderr(`${settings}\n`);
+        return USAGE_ERROR;
+    }
+    const category = findCategory(catalog, text);
+    const result = exploreCards(catalog, {
+        merchant: category === null ? text : null,
+        category,
+        amount,
+        channel: values.online
+            ? 'online'
+            : values['in-store']
+                ? 'in_store'
+                : null,
+        date: values.date ?? io.today,
+    }, settings);
+    io.stdout(values.json
+        ? `${JSON.stringify(result, null, 2)}\n`
+        : formatExploration(result, values.all ?? false));
+    return 0;
+}
+export function parseSpend(catalog, args) {
+    const lines = [];
+    for (const arg of args) {
+        const match = /^(.+)=\$?(\d+(?:\.\d+)?)$/.exec(arg);
+        if (!match?.[1] || match[2] === undefined)
+            return `"${arg}" isn't <what>=<dollars a month>, e.g. groceries=600.`;
+        const what = match[1].replace(/[-_]/g, ' ');
+        const category = findCategory(catalog, what);
+        lines.push({
+            merchant: category === null ? what : null,
+            category,
+            monthly: Number(match[2]),
+        });
+    }
+    if (lines.length === 0)
+        return `Give your monthly spending, e.g. ${CLI_NAME} simulate groceries=600 dining=300 other=1000.`;
+    return lines;
+}
+export async function runSimulate(argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                ...FILTER_FLAGS,
+                wallet: { type: 'boolean' },
+                start: { type: 'string' },
+            },
+        });
+    }
+    catch (e) {
+        io.stderr(`${e instanceof Error ? e.message : String(e)}\n${SIMULATE_HELP}`);
+        return USAGE_ERROR;
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        io.stdout(SIMULATE_HELP);
+        return 0;
+    }
+    const catalog = await loadCatalog();
+    const settings = settingsFrom(values, catalog);
+    if (typeof settings === 'string') {
+        io.stderr(`${settings}\n`);
+        return USAGE_ERROR;
+    }
+    const spend = parseSpend(catalog, positionals);
+    if (typeof spend === 'string') {
+        io.stderr(`${spend}\n`);
+        return USAGE_ERROR;
+    }
+    const lines = resolveSpendLines(catalog, spend);
+    const unknown = lines.filter((l) => l.merchant.source === 'none');
+    if (unknown.length > 0) {
+        io.stderr(`Not a category or a merchant earnrate knows: ${unknown.map((l) => `"${l.merchant.input}"`).join(', ')}. Categories include groceries, dining, gas, travel, streaming and other.\n`);
+        return USAGE_ERROR;
+    }
+    const options = { ...settings, start: values.start ?? io.today };
+    if (values.wallet) {
+        const file = walletPath(io.env);
+        const wallet = await readWallet(file, io);
+        if (!wallet)
+            return RUNTIME_ERROR;
+        const problems = walletProblems(wallet, catalog);
+        if (problems.length > 0) {
+            io.stderr(`Your wallet at ${displayPath(file)} has problems:\n${problems.map((p) => `  - ${p}\n`).join('')}`);
+            return RUNTIME_ERROR;
+        }
+        const valued = values.valuation !== undefined && isValuationProfile(values.valuation)
+            ? withValuationProfile(wallet, values.valuation)
+            : wallet;
+        const result = simulateAdditions(catalog, valued, lines, options);
+        io.stdout(values.json
+            ? `${JSON.stringify(result, null, 2)}\n`
+            : formatAdditions(result, catalog, values.all ?? false));
+        return 0;
+    }
+    const result = simulateCatalog(catalog, lines, options);
+    io.stdout(values.json
+        ? `${JSON.stringify(result, null, 2)}\n`
+        : formatCatalogSimulation(result, catalog, values.all ?? false));
+    return 0;
+}

package/dist/cli/run.js

@@ -12,6 +12,7 @@ import { llmEnabled, openLlmSession } from "../merchants/from-env.js";
 import { resolveMerchant, withCallerCategory } from "../merchants/resolve.js";
 import { packageVersion } from "../version.js";
 import { parseCliArgs } from "./args.js";
+import { runBest, runSimulate } from "./explore.js";
 import { runImport } from "./import.js";
 import { runOffers } from "./offers.js";
 import { runWalletCommand, WALLET_HELP } from "./wallet.js";
@@ -25,6 +26,10 @@ Examples:
   ${CLI_NAME} costco --in-store
   ${CLI_NAME} delta.com 450 --valuation points-heavy
 
+Compare every card, no wallet needed:
+  ${CLI_NAME} best <merchant or category>          Rank all cards for one purchase.
+  ${CLI_NAME} simulate groceries=600 dining=300    Best cards and pairs for a year of spending.
+
 Set up your wallet:
   ${CLI_NAME} cards [search words]                 Find cards and their ids.
   ${CLI_NAME} add <card-id> [--pick ...]           Add a card you hold.
@@ -87,6 +92,10 @@ export async function run(argv, io) {
         return runImport(argv.slice(1), io);
     if (argv[0] === 'offers')
         return runOffers(argv.slice(1), io);
+    if (argv[0] === 'best')
+        return runBest(argv.slice(1), io);
+    if (argv[0] === 'simulate')
+        return runSimulate(argv.slice(1), io);
     const command = argv[0];
     if (command !== undefined && Object.hasOwn(WALLET_HELP, command)) {
         return runWalletCommand(command, argv.slice(1), io);