CLI Report: Single-Pass Deck Analysis and JSON Output

The CLI (main.py) runs a complete deck analysis in a single pass and prints the results — either as a color-coded terminal table or as machine-readable JSON — then exits. There is no interactive prompt and no state between runs. Use it when you want a quick overview of where savings are possible, when you are scripting against multiple decks in a loop, or when you need to pipe the output into another tool.

Command syntax

python main.py <deck> [--top-n N] [--json]

Arguments and flags

deck

string

required

The Moxfield deck URL (e.g. https://moxfield.com/decks/YOUR-DECK-ID) or the raw deck ID string. This is a positional argument — no flag prefix is needed.

--top-n

integer

Maximum number of cheaper suggestions to show per card. Defaults to 5. Pass a smaller value (e.g. --top-n 1) to get only the single best alternative for each card, which makes the table easier to scan and keeps JSON output compact.

--json

boolean

When present, the full report is serialized with json.dumps() and written to stdout instead of the rich terminal table. No color codes or progress text are emitted — only the JSON object. Useful for piping into other programs.

Table output

Without --json, the tool prints a rich table with one row per suggestion. The columns are:

Column	Content
Carta original	Name of the card in the deck (bold).
Precio	Current price of the original card in USD.
Sugerencia	Name of the cheaper candidate card (bold).
Precio	Price of the candidate in USD.
Ahorro	Percentage savings vs. the original, color-coded: green ≥ 50 %, yellow ≥ 20 %, white < 20 %.
Puntaje	Similarity score, color-coded: green ≥ 3.0, yellow ≥ 1.5, white < 1.5.
Razón	Human-readable explanation of why the candidate was matched (shared keywords, overlapping oracle text terms, CMC delta, or fallback to type/color/popularity).

After the table, the tool prints the score legend and the average best savings percentage across all cards that had at least one suggestion.

JSON output

With --json, the tool prints the object returned by build_report(). The structure is:

{
  "deck_name": "My Commander Deck",
  "format": "commander",
  "total_cards": 100,
  "matched": 97,
  "unmatched": ["Jeweled Lotus"],
  "no_price": ["Mox Sapphire"],
  "no_suggestions": ["Sol Ring"],
  "suggestions": [
    {
      "carta_original": "Smothering Tithe",
      "precio_original": 12.50,
      "sugerencia": "Monologue Tax",
      "precio_sugerido": 0.25,
      "ahorro_pct": 98.0,
      "razon": "keywords: treasure; texto: token, whenever; cmc similar (diff 0.0)",
      "score": 3.87
    }
  ],
  "best_savings_pct_avg": 61.4
}

Key	Type	Description
`deck_name`	string	Deck name as returned by the Moxfield API.
`format`	string	Format key, e.g. `"commander"`, `"modern"`.
`total_cards`	integer	Total number of card entries in the deck (including the commander).
`matched`	integer	Number of cards successfully matched in the local database.
`unmatched`	array of strings	Card names that could not be found in the local database.
`no_price`	array of strings	Matched cards with no known USD price (excluded from suggestion logic).
`no_suggestions`	array of strings	Matched cards with a price but no cheaper alternative found in the candidate pool.
`suggestions`	array of objects	One object per (original card, candidate) pair, sorted by original card price descending. See row fields below.
`best_savings_pct_avg`	float or null	Average of the single best savings percentage per card across all cards that had suggestions. `null` if no suggestions were found.

Each object in suggestions contains:

Field	Type	Description
`carta_original`	string	Name of the original deck card.
`precio_original`	float	Price of the original card in USD (rounded to 2 decimal places).
`sugerencia`	string	Name of the suggested replacement.
`precio_sugerido`	float	Price of the suggested card in USD.
`ahorro_pct`	float	Percentage saved vs. the original (rounded to 1 decimal place).
`razon`	string	Plain-text reason string explaining the match.
`score`	float	Similarity score (rounded to 2 decimal places).

Score formula

The similarity score is computed as:

score = 3 × keyword similarity
      + 2.5 × oracle text overlap
      + 1 × CMC proximity
      + 1 × EDHREC popularity

Each component is normalized to the range [0, 1], making the theoretical maximum 7.5. In practice scores rarely exceed 5.0, because that would require nearly identical oracle text. Scores of 3.0 or above indicate a strong functional match; below 1.5 the suggestion shares mainly card type, color identity, and EDHREC popularity rank.

Exit codes

Code	Meaning
`0`	Analysis completed successfully (table or JSON printed to stdout).
`1`	The Moxfield API request failed (network error, private deck, invalid ID). The error message is printed to the console.

Pipeline example

Pretty-print the JSON report using Python’s built-in json.tool module:

python main.py "https://moxfield.com/decks/YOUR-DECK-ID" --json | python -m json.tool

Or filter to only the suggestions with a score above 3.0 using jq:

python main.py "https://moxfield.com/decks/YOUR-DECK-ID" --json \
  | jq '.suggestions[] | select(.score >= 3.0)'

Get Started

Interfaces

Configuration

How It Works

CLI Report: Single-Pass Deck Analysis and JSON Output

Command syntax

Arguments and flags

Table output

JSON output

Score formula

Exit codes

Pipeline example

Build docs developers (and LLMs) love

Get Started

Interfaces

Configuration

How It Works

Documentation Index

​Command syntax

​Arguments and flags

​Table output

​JSON output

​Score formula

​Exit codes

​Pipeline example

Build docs developers (and LLMs) love

Command syntax

Arguments and flags

Table output

JSON output

Score formula

Exit codes

Pipeline example