# pd-cards CLI Reference

Complete command reference for the Paper Dynasty card creation CLI.

## Installation

```bash
# Install in development mode
uv pip install -e .

# Verify installation
pd-cards version
```

## Command Structure

```
pd-cards <subcommand> <command> [OPTIONS]
```

**Subcommands:**
- `custom` - Custom character card management
- `live-series` - Live season card updates
- `retrosheet` - Historical Retrosheet data processing
- `scouting` - Scouting report generation
- `upload` - Card image upload to S3

---

## custom - Custom Character Cards

Manage fictional player cards using YAML profiles stored in `pd_cards/custom/profiles/`.

### custom list

List all available character profiles.

```bash
pd-cards custom list
```

**Output:** Table showing name, type (batter/pitcher), target OPS, positions, and player ID.

---

### custom preview

Preview a character's calculated ratings without submitting.

```bash
pd-cards custom preview <character>
```

**Arguments:**
- `character` - Profile name (e.g., `kalin_young`, `tony_smehrik`)

**Output:** Displays:
- Player info (name, hand, target OPS, IDs)
- Defensive positions with ratings
- Batting/pitching ratings vs L and R
- Calculated AVG/OBP/SLG/OPS for each platoon split
- Verification that ratings total 108

**Example:**
```bash
pd-cards custom preview kalin_young
```

---

### custom submit

Submit a custom character to the database.

```bash
pd-cards custom submit <character> [OPTIONS]
```

**Arguments:**
- `character` - Profile name

**Options:**
| Option | Short | Description |
|--------|-------|-------------|
| `--dry-run` | `-n` | Preview changes without saving |
| `--skip-s3` | | Skip S3 upload after submit |

**Requirements:** Profile must have valid `player_id` and `batting_card_id`/`pitching_card_id` set.

**Example:**
```bash
pd-cards custom submit kalin_young --dry-run  # Validate first
pd-cards custom submit kalin_young            # Actually submit
```

---

### custom new

Create a new character profile template.

```bash
pd-cards custom new --name <name> [OPTIONS]
```

**Options:**
| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--name` | `-n` | (required) | Character name |
| `--type` | `-t` | `batter` | Player type (`batter` or `pitcher`) |
| `--hand` | `-h` | `R` | Batting/throwing hand (`L`, `R`, or `S` for switch) |
| `--target-ops` | | `0.750` | Target OPS (or OPS allowed for pitchers) |

**Output:** Creates YAML file at `pd_cards/custom/profiles/<name>.yaml`

**Examples:**
```bash
pd-cards custom new --name "Mike Power" --type batter --hand R --target-ops 0.850
pd-cards custom new --name "Sandy Lefty" --type pitcher --hand L --target-ops 0.620
```

---

## live-series - Live Season Updates

Generate cards from current season FanGraphs/Baseball Reference data.

### live-series update

Update live series cards from statistical data.

```bash
pd-cards live-series update --cardset <name> [OPTIONS]
```

**Options:**
| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--cardset` | `-c` | (required) | Target cardset name |
| `--season` | `-s` | (from cardset) | Season year |
| `--games` | `-g` | `162` | Number of games played (1-162) |
| `--description` | `-d` | (year) | Player description |
| `--pull-fielding/--no-pull-fielding` | | `True` | Pull fielding stats from Baseball Reference |
| `--post-batters/--skip-batters` | | `True` | Post batting cards and ratings |
| `--post-pitchers/--skip-pitchers` | | `True` | Post pitching cards and ratings |
| `--post-fielders/--skip-fielders` | | `True` | Post card positions |
| `--post-players/--skip-players` | | `True` | Post player updates |
| `--live/--not-live` | | `True` | Look up current MLB clubs from statsapi |
| `--ignore-limits` | | `False` | Ignore minimum PA/TBF requirements |
| `--dry-run` | `-n` | `False` | Preview without saving to database |

**Data Input:** Reads from `data-input/{cardset} Cardset/`

**Examples:**
```bash
pd-cards live-series update --cardset "2025 Season" --games 81 --dry-run
pd-cards live-series update --cardset "2025 Season" --games 162
pd-cards live-series update --cardset "2025 Season" --games 40 --ignore-limits
```

---

### live-series status

Show status of live series cardsets.

```bash
pd-cards live-series status [OPTIONS]
```

**Options:**
| Option | Short | Description |
|--------|-------|-------------|
| `--cardset` | `-c` | Filter by cardset name |

**Output:** Table showing cardset ID, name, season, and player count.

**Examples:**
```bash
pd-cards live-series status
pd-cards live-series status --cardset "2025"
```

---

## retrosheet - Historical Data Processing

Generate cards from Retrosheet play-by-play historical data.

### retrosheet process

Process Retrosheet data and create player cards.

```bash
pd-cards retrosheet process <year> --cardset-id <id> [OPTIONS]
```

**Arguments:**
- `year` - Season year to process (e.g., 2005)

**Options:**
| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--cardset-id` | `-c` | (required) | Target cardset ID |
| `--description` | `-d` | `Live` | Player description (`Live` or `<Month> PotM`) |
| `--start` | | `{year}0301` | Start date YYYYMMDD |
| `--end` | | `{year}1002` | End date YYYYMMDD |
| `--events` | `-e` | `retrosheets_events_{year}.csv` | Retrosheet events CSV filename |
| `--input` | `-i` | `data-input/{year} Live Cardset/` | Data input directory |
| `--season-pct` | | `1.0` | Season percentage (0.0-1.0) |
| `--min-pa-vl` | | `20` (Live) / `1` (PotM) | Minimum PA vs LHP |
| `--min-pa-vr` | | `40` (Live) / `1` (PotM) | Minimum PA vs RHP |
| `--post/--no-post` | | `True` | Post data to database |
| `--dry-run` | `-n` | `False` | Preview without saving |

**Examples:**
```bash
pd-cards retrosheet process 2005 --cardset-id 27 --description Live --dry-run
pd-cards retrosheet process 2005 --cardset-id 27 --description Live
pd-cards retrosheet process 2005 --cardset-id 28 --description "April PotM" --start 20050401 --end 20050430
```

---

### retrosheet arms

Generate outfield arm ratings from Retrosheet play-by-play data.

```bash
pd-cards retrosheet arms <year> --events <file> [OPTIONS]
```

**Arguments:**
- `year` - Season year

**Options:**
| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--events` | `-e` | (required) | Retrosheet events CSV file |
| `--output` | `-o` | `data-output/retrosheet_arm_ratings_{year}.csv` | Output CSV file |
| `--season-pct` | | `1.0` | Season percentage for min sample |

**Output:** CSV with player_id, position, arm_rating, balls_fielded, assist_rate, z_score

**Example:**
```bash
pd-cards retrosheet arms 2005 --events data-input/retrosheet/retrosheets_events_2005.csv
```

---

### retrosheet validate

Validate positions for a cardset.

```bash
pd-cards retrosheet validate <cardset_id> [OPTIONS]
```

**Arguments:**
- `cardset_id` - Cardset ID to validate

**Options:**
| Option | Default | Description |
|--------|---------|-------------|
| `--api` | `https://pd.manticorum.com/api` | API URL |

**Checks:**
- Anomalous DH counts (should be <5 for full-season cards)
- Missing outfield positions (LF, CF, RF)

**Example:**
```bash
pd-cards retrosheet validate 27
pd-cards retrosheet validate 27 --api https://pddev.manticorum.com/api
```

---

### retrosheet defense

Fetch defensive statistics from Baseball Reference.

```bash
pd-cards retrosheet defense <year> [OPTIONS]
```

**Arguments:**
- `year` - Season year to fetch

**Options:**
| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--output` | `-o` | `data-input/{year} Live Cardset/` | Output directory |

**Output:** Creates `defense_{position}.csv` files for: c, 1b, 2b, 3b, ss, lf, cf, rf, of, p

**Note:** Includes 8-second delay between requests for rate limiting.

**Example:**
```bash
pd-cards retrosheet defense 2005 --output "data-input/2005 Live Cardset/"
```

---

## scouting - Scouting Reports

Generate scouting reports and ratings comparisons.

### scouting batters

Generate batting scouting reports.

```bash
pd-cards scouting batters [OPTIONS]
```

**Options:**
| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--cardset-id` | `-c` | (all) | Cardset ID(s) to include (repeatable) |
| `--output` | `-o` | `scouting` | Output directory |

**Output:** Creates `batting-basic.csv` and `batting-ratings.csv`

**Examples:**
```bash
pd-cards scouting batters --cardset-id 27
pd-cards scouting batters --cardset-id 27 --cardset-id 29
pd-cards scouting batters --output reports/
```

---

### scouting pitchers

Generate pitching scouting reports.

```bash
pd-cards scouting pitchers [OPTIONS]
```

**Options:**
| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--cardset-id` | `-c` | (all) | Cardset ID(s) to include (repeatable) |
| `--output` | `-o` | `scouting` | Output directory |

**Output:** Creates `pitching-basic.csv` and `pitching-ratings.csv`

**Examples:**
```bash
pd-cards scouting pitchers --cardset-id 27
pd-cards scouting pitchers --cardset-id 27 --cardset-id 29
```

---

### scouting all

Generate all scouting reports (batters and pitchers).

```bash
pd-cards scouting all [OPTIONS]
```

**Options:**
| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--cardset-id` | `-c` | (all) | Cardset ID(s) to include (repeatable) |
| `--output` | `-o` | `scouting` | Output directory |

**Output:** Creates all four scouting CSV files.

**Example:**
```bash
pd-cards scouting all --cardset-id 27
```

---

## upload - S3 Card Upload

Upload card images to AWS S3.

### upload s3

Upload card images to AWS S3 bucket.

```bash
pd-cards upload s3 --cardset <name> [OPTIONS]
```

**Options:**
| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--cardset` | `-c` | (required) | Cardset name to upload |
| `--start-id` | | | Player ID to start from (for resuming) |
| `--limit` | `-l` | | Limit number of cards to process |
| `--html` | | `False` | Upload HTML preview cards instead of PNG |
| `--skip-batters` | | `False` | Skip batting cards |
| `--skip-pitchers` | | `False` | Skip pitching cards |
| `--upload/--no-upload` | | `True` | Upload to S3 |
| `--update-urls/--no-update-urls` | | `True` | Update player URLs in database |
| `--dry-run` | `-n` | `False` | Preview without uploading |

**Prerequisites:** AWS CLI configured with credentials (`~/.aws/credentials`)

**S3 URL Structure:** `cards/cardset-{id:03d}/player-{player_id}/{batting|pitching}card.png?d={date}`

**Examples:**
```bash
pd-cards upload s3 --cardset "2005 Live" --dry-run
pd-cards upload s3 --cardset "2005 Live" --limit 10
pd-cards upload s3 --cardset "2005 Live" --start-id 5000
pd-cards upload s3 --cardset "2005 Live" --skip-pitchers
```

---

### upload refresh

Refresh (re-generate and re-upload) card images.

```bash
pd-cards upload refresh --cardset <name> [OPTIONS]
```

**Options:**
| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--cardset` | `-c` | (required) | Cardset name |
| `--limit` | `-l` | | Limit number of cards |
| `--dry-run` | `-n` | `False` | Preview without refreshing |

**Example:**
```bash
pd-cards upload refresh --cardset "2005 Live" --limit 10
```

---

### upload check

Check and validate card images without uploading.

```bash
pd-cards upload check --cardset <name> [OPTIONS]
```

**Options:**
| Option | Short | Default | Description |
|--------|-------|---------|-------------|
| `--cardset` | `-c` | (required) | Cardset name |
| `--limit` | `-l` | | Limit number of cards to check |
| `--output` | `-o` | `data-output` | Output directory |

**Example:**
```bash
pd-cards upload check --cardset "2005 Live" --limit 10
```

---

## YAML Profile Schema

**See also:** [`docs/CUSTOM_CARD_TIERS.md`](CUSTOM_CARD_TIERS.md) for tier progression system.

### Batter Profile

```yaml
name: Player Name
player_type: batter
hand: R  # L, R, or S (switch)

# Tier tracking (see CUSTOM_CARD_TIERS.md for values)
tier: M-STR          # Current tier code
target_ops: 0.850    # Must match tier target
tier_history:
  - tier: L-STR
    date: 2025-01-15
    reason: Initial card creation
  - tier: M-STR
    date: 2025-03-20
    reason: Season 5 championship reward

cardset_id: 29
player_id: null      # Set after creation
batting_card_id: null

positions:
  RF:
    range: 3      # 1-5 (lower = better)
    error: 7      # 1-20 (higher = better)
    arm: 0        # -6 to +5 (negative = strong)
  LF:
    range: 4
    error: 6
    arm: 2

baserunning:
  steal_jump: 0.166667  # Fraction for steal success
  steal_high: 15        # High end of steal range
  steal_low: 8          # Low end of steal range
  steal_auto: 0         # Auto-steal threshold
  running: 12           # Base running rating
  hit_and_run: A        # A/B/C/D
  bunting: B            # A/B/C/D

ratings:
  vs_L:  # All values must sum to 108
    homerun: 2.0
    bp_homerun: 1.0      # Ballpark home run
    triple: 0.5
    double_three: 0.0    # Double to 3-zone
    double_two: 4.0      # Double to 2-zone
    double_pull: 2.0     # Pulled double
    single_two: 5.0
    single_one: 5.0
    single_center: 5.0
    bp_single: 3.0       # Ballpark single
    walk: 10.0
    hbp: 1.0
    strikeout: 20.0
    lineout: 12.0
    popout: 2.0
    flyout_a: 2.0
    flyout_bq: 2.0
    flyout_lf_b: 4.0
    flyout_rf_b: 4.0
    groundout_a: 5.0
    groundout_b: 10.0
    groundout_c: 8.5
    pull_rate: 0.30
    center_rate: 0.40
    slap_rate: 0.30
  vs_R:
    # Same structure as vs_L
```

### Pitcher Profile

```yaml
name: Pitcher Name
player_type: pitcher
hand: L
target_ops: 0.620  # OPS allowed
cardset_id: 29
player_id: null
pitching_card_id: null

positions:
  P: null

pitching:
  starter_rating: 5   # 1-5 (higher = better starter)
  relief_rating: 5    # 1-5 (higher = better reliever)
  closer_rating: null # null or 1-5 for closers

ratings:
  vs_L:  # All values must sum to 108 (includes 29 for x-checks)
    homerun: 1.0
    bp_homerun: 1.0
    triple: 0.5
    double_three: 0.0
    double_two: 3.0
    double_cf: 2.0       # Pitchers use double_cf, not double_pull
    single_two: 4.0
    single_one: 3.0
    single_center: 4.0
    bp_single: 5.0
    walk: 8.0
    hbp: 1.0
    strikeout: 20.0
    flyout_lf_b: 4.0
    flyout_cf_b: 5.0     # Pitchers have flyout_cf_b
    flyout_rf_b: 4.0
    groundout_a: 6.0
    groundout_b: 7.5
    # X-checks (fielder plays) - must sum to 29
    xcheck_p: 1.0
    xcheck_c: 3.0
    xcheck_1b: 2.0
    xcheck_2b: 6.0
    xcheck_3b: 3.0
    xcheck_ss: 7.0
    xcheck_lf: 2.0
    xcheck_cf: 3.0
    xcheck_rf: 2.0
  vs_R:
    # Same structure as vs_L
```

---

## Common Workflows

### Creating a New Custom Character

```bash
# 1. Create template
pd-cards custom new --name "John Slugger" --type batter --hand R --target-ops 0.850

# 2. Edit the YAML file
# pd_cards/custom/profiles/john_slugger.yaml

# 3. Preview ratings
pd-cards custom preview john_slugger

# 4. Create player in database (get IDs)
# Use Paper Dynasty admin interface

# 5. Update YAML with player_id and batting_card_id

# 6. Submit
pd-cards custom submit john_slugger --dry-run
pd-cards custom submit john_slugger
```

### Processing a Historical Season

```bash
# 1. Fetch defensive stats
pd-cards retrosheet defense 2005 --output "data-input/2005 Live Cardset/"

# 2. Generate arm ratings
pd-cards retrosheet arms 2005 --events data-input/retrosheet/retrosheets_events_2005.csv

# 3. Process cards
pd-cards retrosheet process 2005 --cardset-id 27 --description Live --dry-run
pd-cards retrosheet process 2005 --cardset-id 27 --description Live

# 4. Validate positions
pd-cards retrosheet validate 27

# 5. Upload to S3
pd-cards upload s3 --cardset "2005 Live" --dry-run
pd-cards upload s3 --cardset "2005 Live"

# 6. Generate scouting reports
pd-cards scouting all --cardset-id 27
```

### Updating Live Season Cards

```bash
# Mid-season update (81 games)
pd-cards live-series update --cardset "2025 Season" --games 81 --dry-run
pd-cards live-series update --cardset "2025 Season" --games 81

# Full season update
pd-cards live-series update --cardset "2025 Season" --games 162

# Upload updated cards
pd-cards upload s3 --cardset "2025 Season"
```