earnrate 0.1.0 → 0.1.2

package/README.md

@@ -9,23 +9,26 @@ 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.
+- Runs on your machine. 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.
 
 ## Try it
 
-Needs Node 24 or later.
+Needs Node 22 or later.
 
 ```sh
 npm install -g earnrate
-mkdir -p ~/.earnrate
-curl -o ~/.earnrate/wallet.yaml https://raw.githubusercontent.com/cwasley/earnrate/main/wallet.example.yaml
+earnrate cards sapphire            # find your cards' ids
+earnrate add chase-sapphire-preferred
+earnrate add amex-gold
 earnrate whole foods 80
 ```
 
-Then edit `~/.earnrate/wallet.yaml` to list your own cards (see [Your wallet](#your-wallet)).
+Adding a card tells you anything else it needs to earn correctly, such as the categories you picked on Cash+, Amazon Prime for Prime Visa's 5%, or which rotating categories you've activated. `earnrate update` sets those. Using an AI assistant instead? [Add the MCP server](#use-it-from-an-ai-agent-mcp) and tell it which cards you have.
+
+With the [example wallet](wallet.example.yaml), it prints:
 
 ```
 Whole Foods Market · $80
@@ -50,7 +53,7 @@ Options: `--online` or `--in-store`, `--valuation flat|points-heavy`, `--all`, `
 
 ### Your wallet
 
-The wallet is a YAML file listing your cards by ID, which is each card's file name in [`data/cards/`](data/cards). Only the cards are required:
+The wallet is a YAML file (`~/.earnrate/wallet.yaml`) listing your cards by ID, which is each card's file name in [`data/cards/`](data/cards). `earnrate add`, `update`, `remove` and `memberships` write it for you and keep your comments, or you can edit it by hand. Only the cards are required:
 
 ```yaml
 valuations:
@@ -69,7 +72,7 @@ cards:
         two-percent: [gas-ev-charging]
 ```
 
-Rule IDs for `activated` and the choice slots for `chosen` are in each card's file. Currencies and their default values are in [`data/currencies.yaml`](data/currencies.yaml). Spending caps fill up as you record purchases from an AI agent or import a statement with `--apply`, and reset with each period.
+Rule IDs for `activated`, the choice slots for `chosen` and the membership IDs that unlock bonuses (such as `bofa-rewards-premier` for a BofA Rewards tier) are in each card's file. Currencies and their default values are in [`data/currencies.yaml`](data/currencies.yaml). Spending caps fill up as you record purchases from an AI agent or import a statement with `--apply`, and reset with each period.
 
 ### Merchants earnrate doesn't know
 
@@ -119,7 +122,7 @@ It totals what each card earned against the best card in your wallet for each pu
 
 ## Supported cards
 
-56 cards, each modeled from the issuer's own terms and checked weekly against them:
+57 cards, each modeled from the issuer's own terms and checked weekly against them:
 
 - **American Express:** Gold, Platinum, Blue Cash Preferred, Blue Cash Everyday, Blue Business Plus
 - **Chase:** Sapphire Preferred, Sapphire Reserve, Freedom Unlimited, Freedom Flex, Ink Business Cash, Ink Business Preferred, Prime Visa
@@ -127,7 +130,7 @@ It totals what each card earned against the best card in your wallet for each pu
 - **Citi:** Strata Elite, Strata Premier, Double Cash, Custom Cash, My Best Buy Visa, Costco Anywhere Visa (personal and business); AAdvantage MileUp, Platinum Select, Globe, Executive, Business
 - **Capital One:** Venture X, Venture, Savor, Kohl's Card, Kohl's Rewards Visa
 - **Wells Fargo:** Active Cash, Autograph
-- **Bank of America:** Atmos Rewards Ascent, Summit, Business
+- **Bank of America:** Atmos Rewards Ascent, Summit, Business; Customized Cash Rewards
 - **TD Bank:** Target Circle Card, Nordstrom card, Nordstrom Visa
 - **Others:** U.S. Bank Cash+, Bilt Obsidian, SoFi Unlimited 2%
 
@@ -139,13 +142,16 @@ 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 five tools:
+`earnrate mcp` runs earnrate as a local MCP server over stdio, with ten tools:
 
 - `best_card_for_purchase`: which card to use, with reasons
 - `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
 - `record_purchase`: books a purchase against its cap and any open welcome bonus in your wallet file, keeping your comments
+- `search_cards`, `add_card`, `update_card`, `remove_card` and `set_memberships`: set up the wallet in conversation
+
+There's no wallet to write first: tell the assistant which cards you have, and it finds them, adds them, and asks about anything a card needs, like this quarter's Cash+ picks.
 
 For a merchant earnrate doesn't know, the calling model can pass a `category` (e.g. `grocery.supermarket`). It's used only for unknown merchants and is labeled in the answer. The command line takes the same thing as `--category`.
 

package/data/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 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.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.
+
+| Card                                                          | Field                       | Old → new                | Source |
+| ------------------------------------------------------------- | --------------------------- | ------------------------ | ------ |
+| chase-freedom-flex                                            | caps.five-percent-quarterly | adds `rotating`          | n/a    |
+| capital-one-venture-x, capital-one-venture, capital-one-savor | issuer                      | capitalone → capital-one | n/a    |
+
+## 2026.10.28.2
+
+Bank of America Customized Cash Rewards, reviewed by Collin (`verified_by: collin`). Choice options can now be "any online purchase except these categories", and a choice period can be `until_changed` for picks that carry over.
+
+| Card                                    | Field | Old → new                                                                                                                                   | Source                                                                                                                                                                                                                                                                                                                     |
+| --------------------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| bank-of-america-customized-cash-rewards | new   | 3% in a choice category, 2% at grocery stores and wholesale clubs ($2,500 combined a quarter), 1% otherwise; BofA Rewards tiers add 10%–75% | [card page](https://www.bankofamerica.com/credit-cards/products/cash-back-credit-card/), [categories](https://www.bankofamerica.com/credit-cards/products/cash-back-credit-card/cash-back-category-choices/), terms, [BofA Rewards](https://www.bankofamerica.com/bofa-rewards/increasing-bofa-rewards-with-credit-cards/) |
+
 ## 2026.10.28.1
 
 Collin reviewed the family-cards and offers packets and kept every value as recorded, including the open calls: no Peloton rule on Sapphire Preferred yet, My Best Buy Visa's fee at the top of Citi's $0–59 range, and Amex "as high as" offers at the public figure. All 56 cards are now `verified_by: collin`.

package/data/VERSION

@@ -1 +1 @@
-2026.10.28.1
+2026.10.30.1

package/data/cards/bank-of-america-customized-cash-rewards.yaml

@@ -0,0 +1,210 @@
+id: bank-of-america-customized-cash-rewards
+name: Bank of America Customized Cash Rewards Credit Card
+issuer: bank-of-america
+# Bank of America's terms carry only the Visa and Visa Signature trademark
+# notice, so the network is Visa.
+network: visa
+currency: cash
+last_verified: 2026-10-28
+verified_by: collin
+source_urls:
+  - https://www.bankofamerica.com/credit-cards/products/cash-back-credit-card/
+  - https://www.bankofamerica.com/credit-cards/products/cash-back-credit-card/cash-back-category-choices/
+  - https://www.bankofamerica.com/credit-cards/terms-and-conditions/?campaignid=4079537&productoffercode=8H&locale=en_US
+  - https://www.bankofamerica.com/bofa-rewards/increasing-bofa-rewards-with-credit-cards/
+base_rate: 1
+annual_fee: 0
+welcome_offer:
+  dollars: 200
+  spend: 1000
+  months: 3
+  note: Online offer; the window is 90 days from account opening, modeled as 3 months. The offer may not be available elsewhere after leaving the page.
+caps:
+  - id: three-and-two-percent-combined
+    amount: 2500
+    period: quarter
+    then_rate: 1
+choices:
+  # Gas is the default until changed. It can be changed once per calendar
+  # month and otherwise carries over.
+  - id: three-percent
+    pick: 1
+    period: until_changed
+    default: [gas-ev-charging]
+    options:
+      gas-ev-charging: [gas, ev_charging]
+      # Bank of America also excludes doctors and hospitals, government
+      # services and taxes, insurance, schools and other non-retail services,
+      # which have no earnrate category.
+      online-shopping:
+        { channel: online, exclude: [utilities, shipping, fitness] }
+      dining: [dining]
+      travel: [travel, transit]
+      drug-stores: [drugstore]
+      home-improvement-furnishings: [home_improvement, furniture]
+rules:
+  - id: three-percent
+    match: { choice: three-percent }
+    rate: 3
+    cap: three-and-two-percent-combined
+    note: Gas and EV charging, online shopping, dining, travel, drug stores, or home improvement and furnishings, whichever you picked. Travel includes parking, transit, rideshare and tolls. Online shopping is any purchase paid on a website or app, as reported by the merchant; ordered online but paid in store, in-store mobile wallet and phone or mail orders don't count, and doctors, government, insurance, membership organizations, schools, some utilities and other non-retail services are excluded. The first $2,500 a calendar quarter across the 3% and 2% categories, then 1%.
+  - id: two-percent
+    match: { categories: [grocery.supermarket, warehouse_club] }
+    rate: 2
+    cap: three-and-two-percent-combined
+    note: Grocery stores, supermarkets, wholesale clubs, and meat and seafood, candy, dairy and bakery stores. Superstores and smaller stores that also sell groceries, like drug stores, are excluded. Shares the $2,500 quarterly cap with the 3% category.
+  # BofA Rewards members earn a tier bonus on all cash back: 10% for Member,
+  # 25% Preferred Plus, 50% Preferred Honors, 75% Premier.
+  - id: three-percent-bofa-rewards-member
+    match: { choice: three-percent }
+    rate: 3.3
+    cap: three-and-two-percent-combined
+    requires: { membership: bofa-rewards-member }
+    note: 3% plus the 10% BofA Rewards Member bonus.
+  - id: two-percent-bofa-rewards-member
+    match: { categories: [grocery.supermarket, warehouse_club] }
+    rate: 2.2
+    cap: three-and-two-percent-combined
+    requires: { membership: bofa-rewards-member }
+    note: 2% plus the 10% BofA Rewards Member bonus.
+  - id: everything-else-bofa-rewards-member
+    match: { any: true }
+    rate: 1.1
+    requires: { membership: bofa-rewards-member }
+    note: 1% plus the 10% BofA Rewards Member bonus.
+  - id: three-percent-bofa-rewards-preferred-plus
+    match: { choice: three-percent }
+    rate: 3.75
+    cap: three-and-two-percent-combined
+    requires: { membership: bofa-rewards-preferred-plus }
+    note: 3% plus the 25% BofA Rewards Preferred Plus bonus.
+  - id: two-percent-bofa-rewards-preferred-plus
+    match: { categories: [grocery.supermarket, warehouse_club] }
+    rate: 2.5
+    cap: three-and-two-percent-combined
+    requires: { membership: bofa-rewards-preferred-plus }
+    note: 2% plus the 25% BofA Rewards Preferred Plus bonus.
+  - id: everything-else-bofa-rewards-preferred-plus
+    match: { any: true }
+    rate: 1.25
+    requires: { membership: bofa-rewards-preferred-plus }
+    note: 1% plus the 25% BofA Rewards Preferred Plus bonus.
+  - id: three-percent-bofa-rewards-preferred-honors
+    match: { choice: three-percent }
+    rate: 4.5
+    cap: three-and-two-percent-combined
+    requires: { membership: bofa-rewards-preferred-honors }
+    note: 3% plus the 50% BofA Rewards Preferred Honors bonus.
+  - id: two-percent-bofa-rewards-preferred-honors
+    match: { categories: [grocery.supermarket, warehouse_club] }
+    rate: 3
+    cap: three-and-two-percent-combined
+    requires: { membership: bofa-rewards-preferred-honors }
+    note: 2% plus the 50% BofA Rewards Preferred Honors bonus.
+  - id: everything-else-bofa-rewards-preferred-honors
+    match: { any: true }
+    rate: 1.5
+    requires: { membership: bofa-rewards-preferred-honors }
+    note: 1% plus the 50% BofA Rewards Preferred Honors bonus.
+  - id: three-percent-bofa-rewards-premier
+    match: { choice: three-percent }
+    rate: 5.25
+    cap: three-and-two-percent-combined
+    requires: { membership: bofa-rewards-premier }
+    note: 3% plus the 75% BofA Rewards Premier bonus.
+  - id: two-percent-bofa-rewards-premier
+    match: { categories: [grocery.supermarket, warehouse_club] }
+    rate: 3.5
+    cap: three-and-two-percent-combined
+    requires: { membership: bofa-rewards-premier }
+    note: 2% plus the 75% BofA Rewards Premier bonus.
+  - id: everything-else-bofa-rewards-premier
+    match: { any: true }
+    rate: 1.75
+    requires: { membership: bofa-rewards-premier }
+    note: 1% plus the 75% BofA Rewards Premier bonus.
+# Issuer text backing each rule; `yarn check-sources` checks it weekly.
+evidence:
+  - rule: base_rate
+    url: https://www.bankofamerica.com/credit-cards/products/cash-back-credit-card/
+    quote: 'Unlimited 1% cash back on all other purchases'
+  - rule: three-percent
+    url: https://www.bankofamerica.com/credit-cards/products/cash-back-credit-card/cash-back-category-choices/
+    quote: '3% cash back in the category of your choice'
+  - rule: three-percent
+    url: https://www.bankofamerica.com/credit-cards/products/cash-back-credit-card/cash-back-category-choices/
+    quote: 'You can change it once each calendar month, or make no change and it stays the same.'
+  - rule: three-percent
+    url: https://www.bankofamerica.com/credit-cards/products/cash-back-credit-card/cash-back-category-choices/
+    quote: 'Until you change your category it will be set to Gas & EV Charging Stations.'
+  - rule: three-percent
+    url: https://www.bankofamerica.com/credit-cards/terms-and-conditions/?campaignid=4079537&productoffercode=8H&locale=en_US
+    quote: 'first $2,500 of combined Net Purchases posted to the account each calendar quarter'
+  - rule: three-percent
+    url: https://www.bankofamerica.com/credit-cards/terms-and-conditions/?campaignid=4079537&productoffercode=8H&locale=en_US
+    quote: 'purchases must be made online via a website or a digital application (an app)'
+  - rule: three-percent
+    url: https://www.bankofamerica.com/credit-cards/terms-and-conditions/?campaignid=4079537&productoffercode=8H&locale=en_US
+    quote: 'doctors and hospitals, government services and taxes, insurances, membership organizations, education/schools, and some utilities'
+  - rule: three-percent
+    url: https://www.bankofamerica.com/credit-cards/products/cash-back-credit-card/cash-back-category-choices/
+    quote: 'Courier Services (Air and Ground, Freight Forwarders)'
+  - rule: three-percent
+    url: https://www.bankofamerica.com/credit-cards/products/cash-back-credit-card/cash-back-category-choices/
+    quote: 'Clubs, Country Clubs, Membership (Athletic, Recreation, Sports)'
+  - rule: three-percent
+    url: https://www.bankofamerica.com/credit-cards/products/cash-back-credit-card/cash-back-category-choices/
+    quote: 'parking, public transit, taxis/ride share'
+  - rule: two-percent
+    url: https://www.bankofamerica.com/credit-cards/products/cash-back-credit-card/
+    quote: 'Automatic 2% cash back at grocery stores and wholesale clubs'
+  - rule: two-percent
+    url: https://www.bankofamerica.com/credit-cards/terms-and-conditions/?campaignid=4079537&productoffercode=8H&locale=en_US
+    quote: 'Excluded from this Bonus Category are superstores and smaller stores (like drug stores)'
+  - rule: three-percent-bofa-rewards-member
+    url: https://www.bankofamerica.com/bofa-rewards/increasing-bofa-rewards-with-credit-cards/
+    quote: 'a $100 purchase that earns 3% ($3.00) will actually earn $3.30'
+  - rule: two-percent-bofa-rewards-member
+    url: https://www.bankofamerica.com/bofa-rewards/increasing-bofa-rewards-with-credit-cards/
+    quote: 'bonus of 10% for the Member tier'
+  - rule: everything-else-bofa-rewards-member
+    url: https://www.bankofamerica.com/bofa-rewards/increasing-bofa-rewards-with-credit-cards/
+    quote: 'applied after all base and bonus cash rewards have been calculated on a purchase'
+  - rule: three-percent-bofa-rewards-preferred-plus
+    url: https://www.bankofamerica.com/bofa-rewards/increasing-bofa-rewards-with-credit-cards/
+    quote: 'will actually earn $3.30, $3.75, $4.50 or $5.25 based on your tier'
+  - rule: two-percent-bofa-rewards-preferred-plus
+    url: https://www.bankofamerica.com/bofa-rewards/increasing-bofa-rewards-with-credit-cards/
+    quote: '25% for the Preferred Plus tier'
+  - rule: everything-else-bofa-rewards-preferred-plus
+    url: https://www.bankofamerica.com/bofa-rewards/increasing-bofa-rewards-with-credit-cards/
+    quote: '25% for the Preferred Plus tier'
+  - rule: three-percent-bofa-rewards-preferred-honors
+    url: https://www.bankofamerica.com/bofa-rewards/increasing-bofa-rewards-with-credit-cards/
+    quote: 'will actually earn $3.30, $3.75, $4.50 or $5.25 based on your tier'
+  - rule: two-percent-bofa-rewards-preferred-honors
+    url: https://www.bankofamerica.com/bofa-rewards/increasing-bofa-rewards-with-credit-cards/
+    quote: '50% for the Preferred Honors tier'
+  - rule: everything-else-bofa-rewards-preferred-honors
+    url: https://www.bankofamerica.com/bofa-rewards/increasing-bofa-rewards-with-credit-cards/
+    quote: '50% for the Preferred Honors tier'
+  - rule: three-percent-bofa-rewards-premier
+    url: https://www.bankofamerica.com/bofa-rewards/increasing-bofa-rewards-with-credit-cards/
+    quote: 'will actually earn $3.30, $3.75, $4.50 or $5.25 based on your tier'
+  - rule: two-percent-bofa-rewards-premier
+    url: https://www.bankofamerica.com/bofa-rewards/increasing-bofa-rewards-with-credit-cards/
+    quote: 'or 75% for the Premier tier'
+  - rule: everything-else-bofa-rewards-premier
+    url: https://www.bankofamerica.com/bofa-rewards/increasing-bofa-rewards-with-credit-cards/
+    quote: 'or 75% for the Premier tier'
+  - rule: annual_fee
+    url: https://www.bankofamerica.com/credit-cards/products/cash-back-credit-card/
+    quote: 'Annual Fee $0'
+  - rule: welcome_offer
+    url: https://www.bankofamerica.com/credit-cards/products/cash-back-credit-card/
+    quote: 'Online $200 cash rewards bonus after making at least $1,000 in purchases in the first 90 days'
+todo:
+  - New accounts earn 6% in the choice category for the first year (an extra 3%, inside the same $2,500 quarterly cap, with no BofA Rewards bonus on the extra 3%). earnrate can't see when an account was opened, so this isn't modeled.
+  - 'The BofA Rewards rules use proposed membership ids: bofa-rewards-member, bofa-rewards-preferred-plus, bofa-rewards-preferred-honors and bofa-rewards-premier. Cardholders who joined Preferred Rewards before May 26, 2026 may have an "extended card benefit" that Bank of America doesn''t define.'
+  - With a BofA Rewards tier, a purchase that crosses the $2,500 cap counts the part past the cap at 1% instead of the tier's boosted base rate, so it's slightly understated.
+  - "Online shopping counts any online purchase earnrate can't place in an excluded category, including unknown merchants. Bank of America also excludes doctors, government, insurance, schools and other non-retail services, which earnrate can't tell apart."

package/data/cards/capital-one-savor.yaml

@@ -1,6 +1,6 @@
 id: capital-one-savor
 name: Capital One Savor Rewards Credit Card
-issuer: capitalone
+issuer: capital-one
 # The card page never names the network in visible text; its embedded
 # product data says MasterCard.
 network: mastercard

package/data/cards/capital-one-venture-x.yaml

@@ -1,6 +1,6 @@
 id: capital-one-venture-x
 name: Capital One Venture X Rewards Credit Card
-issuer: capitalone
+issuer: capital-one
 network: visa # Visa Infinite, per the card page's footnotes
 currency: C1
 last_verified: 2026-10-26

package/data/cards/capital-one-venture.yaml

@@ -1,6 +1,6 @@
 id: capital-one-venture
 name: Capital One Venture Rewards Credit Card
-issuer: capitalone
+issuer: capital-one
 # The card page never names the network in visible text. Its embedded product
 # data says MasterCard; older Venture accounts may be on Visa.
 network: mastercard

package/data/cards/chase-freedom-flex.yaml

@@ -31,6 +31,7 @@ caps:
     amount: 1500
     period: quarter
     then_rate: 1
+    rotating: true
 rules:
   - id: chase-travel
     match: { merchants: [chase-travel] }

package/dist/cli/cards.js

@@ -0,0 +1,34 @@
+const NETWORKS = {
+    visa: 'Visa',
+    mastercard: 'Mastercard',
+    amex: 'Amex',
+    discover: 'Discover',
+    store: 'store card',
+};
+export function formatCardInfo(card) {
+    const fee = card.annualFee === null
+        ? ''
+        : card.annualFee === 0
+            ? ', no annual fee'
+            : `, $${String(card.annualFee)} a year`;
+    const needs = [
+        ...card.choices.map((c) => `${c.id}: pick ${String(c.pick)} of ${c.options.join(', ')}${c.default ? ` (default ${c.default.join(', ')})` : ''}`),
+        ...(card.memberships.length > 0
+            ? [`rates that need a membership: ${card.memberships.join(', ')}`]
+            : []),
+        ...(card.activation.length > 0
+            ? [`activate with the issuer: ${card.activation.join(', ')}`]
+            : []),
+        ...(card.needsAnniversary ? ['cap resets on the card anniversary'] : []),
+        ...(card.onlyAt ? [`works only at ${card.onlyAt.join(', ')}`] : []),
+    ];
+    return [
+        `${card.id}: ${card.name} (${NETWORKS[card.network]}${fee})${card.held ? ' [in wallet]' : ''}`,
+        ...needs.map((n) => `    ${n}`),
+    ].join('\n');
+}
+export function formatNotes(notes) {
+    return notes.length === 0
+        ? 'Nothing else to set up for it.'
+        : `Still to set:\n${notes.map((n) => `- ${n.text}`).join('\n')}`;
+}

package/dist/cli/run.js

@@ -14,6 +14,7 @@ import { packageVersion } from "../version.js";
 import { parseCliArgs } from "./args.js";
 import { runImport } from "./import.js";
 import { runOffers } from "./offers.js";
+import { runWalletCommand, WALLET_HELP } from "./wallet.js";
 import { formatRecommendation, plain } from "./format.js";
 export const HELP = `Usage: ${CLI_NAME} <merchant> [amount] [options]
 
@@ -24,11 +25,18 @@ Examples:
   ${CLI_NAME} costco --in-store
   ${CLI_NAME} delta.com 450 --valuation points-heavy
 
+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.
+  ${CLI_NAME} update <card-id> [--pick ...]        Change picks, label or activations.
+  ${CLI_NAME} remove <card-id>                     Remove a card.
+  ${CLI_NAME} memberships [names...]               Show or set memberships (amazon-prime).
+
 Other commands:
   ${CLI_NAME} import <statement.csv> --card <id>   Replay a statement against your wallet.
   ${CLI_NAME} offers [--cash | --points]           Rank welcome offers on cards you don't have.
   ${CLI_NAME} mcp                                  Run the MCP server over stdio, for AI agents.
-  Add --help to import or offers for its options.
+  Add --help to any command for its options.
 
 Options:
   --online, --in-store   How you're paying. Default: inferred from the merchant.
@@ -66,7 +74,7 @@ export async function readWallet(file, io) {
     }
     catch (e) {
         if (e instanceof Error && 'code' in e && e.code === 'ENOENT') {
-            io.stderr(`No wallet at ${displayPath(file)}. Copy the example there and edit it:\n  mkdir -p ${displayPath(path.dirname(file))} && cp ${displayPath(EXAMPLE_WALLET)} ${displayPath(file)}\nOr set ${WALLET_ENV_VAR} to your wallet's path.\n`);
+            io.stderr(`No wallet at ${displayPath(file)} yet. Add the cards you hold:\n  ${CLI_NAME} cards sapphire          find a card's id\n  ${CLI_NAME} add chase-sapphire-preferred\nOr start from the example: mkdir -p ${displayPath(path.dirname(file))} && cp ${displayPath(EXAMPLE_WALLET)} ${displayPath(file)}\nOr set ${WALLET_ENV_VAR} to your wallet's path.\n`);
         }
         else {
             io.stderr(`Couldn't read your wallet:\n${e instanceof Error ? e.message : String(e)}\n`);
@@ -79,6 +87,10 @@ export async function run(argv, io) {
         return runImport(argv.slice(1), io);
     if (argv[0] === 'offers')
         return runOffers(argv.slice(1), io);
+    const command = argv[0];
+    if (command !== undefined && Object.hasOwn(WALLET_HELP, command)) {
+        return runWalletCommand(command, argv.slice(1), io);
+    }
     if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-v')) {
         io.stdout(`${CLI_NAME} ${await packageVersion()}\n`);
         return 0;

package/dist/cli/wallet.js

@@ -0,0 +1,194 @@
+import { parseArgs } from 'node:util';
+import { CLI_NAME } from "../brand.js";
+import { loadCatalog, loadWallet, walletPath } from "../data/load.js";
+import { addCard, removeCard, setMemberships, updateCard, } from "../data/wallet-setup.js";
+import { knownMemberships, searchCards } from "../engine/setup.js";
+import { formatCardInfo, formatNotes } from "./cards.js";
+import { displayPath, RUNTIME_ERROR, USAGE_ERROR } from "./run.js";
+const CARD_OPTIONS = `Options:
+  --label <text>             How the card appears at checkout, e.g. "Amex Gold".
+  --pick <choice>=<options>  Bonus categories you picked for this period, e.g.
+                             --pick five-percent=fast-food,movie-theaters.
+                             Repeat for each choice.
+  --anniversary <MM-DD>      Account anniversary, for caps that reset on it.
+  --activated <rules>        Rules you've activated with the issuer, comma
+                             separated. Replaces the current list.
+  -h, --help                 Show this help.`;
+export const WALLET_HELP = {
+    cards: `Usage: ${CLI_NAME} cards [search words]
+
+Finds cards in earnrate's catalog by name or issuer, with the id to add them
+by and anything they need set up. With no words, lists every card.
+
+Examples:
+  ${CLI_NAME} cards sapphire
+  ${CLI_NAME} cards bofa
+`,
+    add: `Usage: ${CLI_NAME} add <card-id> [options]
+
+Adds a card you hold to your wallet, creating the wallet if needed. Find the
+id with \`${CLI_NAME} cards\`.
+
+${CARD_OPTIONS}
+`,
+    update: `Usage: ${CLI_NAME} update <card-id> [options]
+
+Changes a card in your wallet: picks for this period, label, anniversary or
+activations. Picks for the current period are merged with ones already set.
+
+${CARD_OPTIONS}
+`,
+    remove: `Usage: ${CLI_NAME} remove <card-id>
+
+Removes a card from your wallet, with its tracked cap usage.
+`,
+    memberships: `Usage: ${CLI_NAME} memberships [<membership>...] [--none]
+
+With no arguments, shows your memberships and the ones earnrate knows. With
+names, replaces the list. --none clears it.
+`,
+};
+const HINTS = {
+    pick: (id) => `${CLI_NAME} update ${id} --pick <choice>=<option>,...`,
+    membership: () => `${CLI_NAME} memberships <membership>...`,
+    activation: (id) => `${CLI_NAME} update ${id} --activated <rule>,...`,
+    anniversary: (id) => `${CLI_NAME} update ${id} --anniversary MM-DD`,
+};
+function parsePicks(values) {
+    const picks = {};
+    for (const v of values) {
+        const [choice, options] = v.split('=', 2);
+        const ids = (options ?? '')
+            .split(',')
+            .map((o) => o.trim())
+            .filter((o) => o !== '');
+        if (!choice || ids.length === 0) {
+            return `"--pick ${v}" should look like --pick five-percent=fast-food,movie-theaters.`;
+        }
+        picks[choice] = ids;
+    }
+    return picks;
+}
+async function heldWallet(io) {
+    try {
+        return await loadWallet(walletPath(io.env));
+    }
+    catch {
+        return null;
+    }
+}
+function report(result, message, cardId, io) {
+    if (!result.ok) {
+        io.stderr(`${result.error}\n`);
+        return RUNTIME_ERROR;
+    }
+    const lines = [message];
+    if (cardId !== null) {
+        lines.push(formatNotes(result.notes));
+        const hints = [...new Set(result.notes.map((n) => n.kind))]
+            .map((kind) => HINTS[kind]?.(cardId))
+            .filter((h) => h !== undefined);
+        if (hints.length > 0)
+            lines.push(`Set them with:\n${hints.map((h) => `  ${h}`).join('\n')}`);
+    }
+    io.stdout(`${lines.join('\n')}\n`);
+    return 0;
+}
+export async function runWalletCommand(command, argv, io) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                label: { type: 'string' },
+                pick: { type: 'string', multiple: true },
+                anniversary: { type: 'string' },
+                activated: { type: 'string' },
+                none: { type: 'boolean' },
+                help: { type: 'boolean', short: 'h' },
+            },
+        });
+    }
+    catch (e) {
+        io.stderr(`${e instanceof Error ? e.message : String(e)}\nRun ${CLI_NAME} ${command} --help for usage.\n`);
+        return USAGE_ERROR;
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        io.stdout(WALLET_HELP[command]);
+        return 0;
+    }
+    const usage = (message) => {
+        io.stderr(`${message}\nRun ${CLI_NAME} ${command} --help for usage.\n`);
+        return USAGE_ERROR;
+    };
+    const cardOptionsGiven = values.label !== undefined ||
+        values.pick !== undefined ||
+        values.anniversary !== undefined ||
+        values.activated !== undefined;
+    if (command !== 'add' && command !== 'update' && cardOptionsGiven) {
+        return usage(`${CLI_NAME} ${command} doesn't take card options.`);
+    }
+    if (command !== 'memberships' && values.none) {
+        return usage('--none is only for memberships.');
+    }
+    const catalog = await loadCatalog();
+    const file = walletPath(io.env);
+    const where = displayPath(file);
+    if (command === 'cards') {
+        const query = positionals.join(' ');
+        const result = searchCards(catalog, query, await heldWallet(io), io.today);
+        if (result.cards.length === 0) {
+            io.stderr(`No card matches "${query}". Run ${CLI_NAME} cards with no words to list all ${String(catalog.cards.length)}.\n`);
+            return RUNTIME_ERROR;
+        }
+        const header = result.exact ? '' : 'No card matches every word. Closest:\n';
+        io.stdout(`${header}${result.cards.map(formatCardInfo).join('\n')}\n`);
+        return 0;
+    }
+    if (command === 'memberships') {
+        if (positionals.length === 0 && !values.none) {
+            const held = await heldWallet(io);
+            io.stdout(`Yours: ${held && held.memberships.length > 0 ? held.memberships.join(', ') : 'none'}\nKnown: ${knownMemberships(catalog).join(', ')}\n`);
+            return 0;
+        }
+        if (positionals.length > 0 && values.none) {
+            return usage('Give memberships or --none, not both.');
+        }
+        const list = values.none ? [] : positionals;
+        return report(await setMemberships(file, catalog, list), list.length > 0
+            ? `Memberships set to ${list.join(', ')} in ${where}.`
+            : `Memberships cleared in ${where}.`, null, io);
+    }
+    if (positionals.length !== 1) {
+        return usage('Give one card id.');
+    }
+    const id = positionals[0] ?? '';
+    const name = catalog.cards.find((c) => c.id === id)?.name ?? id;
+    if (command === 'remove') {
+        return report(await removeCard(file, catalog, id), `Removed ${name} from ${where}.`, null, io);
+    }
+    const input = { id };
+    if (values.label !== undefined)
+        input.checkoutLabel = values.label;
+    if (values.anniversary !== undefined)
+        input.anniversary = values.anniversary;
+    if (values.activated !== undefined) {
+        input.activated = values.activated
+            .split(',')
+            .map((r) => r.trim())
+            .filter((r) => r !== '');
+    }
+    if (values.pick !== undefined) {
+        const picks = parsePicks(values.pick);
+        if (typeof picks === 'string')
+            return usage(picks);
+        input.picks = picks;
+    }
+    if (command === 'add') {
+        const result = await addCard(file, catalog, input, io.today);
+        return report(result, `Added ${name} to ${where}${result.ok && result.created ? ' (a new wallet)' : ''}.`, id, io);
+    }
+    return report(await updateCard(file, catalog, input, io.today), `Updated ${name} in ${where}.`, id, io);
+}