Cline rules

1---
2description: CLI command patterns and workflow guidelines for mtg-utils Click-based commands
3author: Simone Gasbarroni
4version: 1.0
5tags: ["cli", "click", "workflows"]
6---
7 
8# CLI Workflows
9 
10## Click CLI Pattern
11 
12mtg-utils uses Click for building command-line interfaces. This document outlines the patterns and best practices for creating and modifying CLI commands.
13 
14---
15 
16## Directory Structure
17 
18```
19mtg_utils/
20└── commands/
21    ├── __init__.py
22    ├── check_missing_cards/
23    │   ├── __init__.py
24    │   ├── command.py  # CLI command wrapper with Click decorators
25    │   ├── logic.py    # Business logic
26    │   └── render.py   # Console output
27    └── update_card_library/
28        ├── __init__.py
29        ├── command.py
30        ├── logic.py
31        └── render.py
32```
33 
34---
35 
36## Command Structure
37 
38Each command follows a modular pattern:
39 
40### 1. `command.py` - CLI Wrapper
41 
42Contains the Click command definition with decorators and option parsing.
43 
44```python
45import click
46from rich.console import Console
47from mtg_utils.utils.console import console
48 
49@click.command()
50@click.option("--deck-file", "-f", help="Path to decklist file")
51@click.option("--moxfield-id", "-m", help="Moxfield deck ID")
52def check_missing_cards(deck_file: str | None, moxfield_id: str | None):
53    """
54    Check which cards are missing from your collection.
55    """
56    # Parse options and call logic
57    pass
58```
59 
60### 2. `logic.py` - Business Logic
61 
62Contains pure logic for processing and calculations.
63 
64```python
65from mtg_utils.utils.moxfield_api import get_binder_cards
66from mtg_utils.utils.readers import read_deck_list
67 
68def get_missing_cards(deck_file: str, binder_cards: list[str]) -> list[str]:
69    """Get list of cards missing from binder collection."""
70    deck_cards = read_deck_list(deck_file)
71    return [card for card in deck_cards if card not in binder_cards]
72```
73 
74### 3. `render.py` - Console Output
75 
76Contains Rich-based rendering for formatted output.
77 
78```python
79from rich.table import Table
80from mtg_utils.utils.console import console
81 
82def render_missing_cards(cards: list[str]) -> None:
83    """Render missing cards table."""
84    table = Table(title="Missing Cards")
85    table.add_column("Card Name", style="cyan")
86    for card in cards:
87        table.add_row(card)
88    console.print(table)
89```
90 
91---
92 
93## Adding a New Command
94 
951. Create a new directory under `mtg_utils/commands/`
962. Create `__init__.py`, `command.py`, `logic.py`, and `render.py`
973. Add the command to `mtg_utils/main.py` using `cli.add_command()`
984. Write tests in `tests/test_commands/test_<command_name>.py`
99 
100---
101 
102## Environment Variables
103 
104Use Click's `envvar` parameter for environment variable support:
105 
106```python
107@click.option(
108    "--debug",
109    envvar="DEBUG",
110    default=False,
111    type=bool,
112    is_flag=True,
113    help="Debug mode: set logging level to DEBUG",
114)
115```
116 
117---
118 
119## Error Handling
120 
121Always use `console.print()` for error messages:
122 
123```python
124# ✅ GOOD
125console.print(f"[bold red]Error:[/bold red] Deck file not found: {path}")
126 
127# ❌ BAD
128print(f"Error: Deck file not found: {path}")
129 
130```