feat(cli): add combined import mode, structured logging, and v0.4.0 CLI overhaul

- introduce combined Last.fm + Spotify import with deduplication
- add sync and deduplicate modes
- replace legacy flags with unified --mode interface (backwards compatible)
- add structured, colour-coded logging with verbose/quiet levels
- improve batching, rate limiting, and graceful shutdown
- update docs, CLI help, and bump version to v0.4.0

README.md

···
 
 ## Features
 
+- ✅ **Structured Logging**: Color-coded output with debug/verbose modes
 - ✅ **Batch Operations**: Uses `com.atproto.repo.applyWrites` for efficient batch publishing (up to 200 records per call)
 - ✅ **Spotify Support**: Import from Spotify Extended Streaming History (JSON format)
+- ✅ **Combined Import**: Merge Last.fm and Spotify exports, automatically deduplicating overlapping plays
 - ✅ **TID-based Record Keys**: Records use timestamp-based identifiers for chronological ordering
 - ✅ **Re-Sync Mode**: Check existing Teal records and only import new scrobbles (no duplicates!)
 - ✅ **Rate Limiting**: Automatically limits imports to 1K records per day to prevent rate limiting your entire PDS
···
 
 ## Usage
 
-### Re-Sync Mode (NEW!)
+### Combined Import Mode
+
+Merge your Last.fm and Spotify listening history into a single, deduplicated import:
+
+```bash
+# Preview the merged import
+npm start -- -i lastfm.csv --spotify-input spotify-export/ -m combined --dry-run
+
+# Perform the combined import
+npm start -- -i lastfm.csv --spotify-input spotify-export/ -m combined -h alice.bsky.social -p xxxx-xxxx-xxxx-xxxx -y
+```
+
+Combined mode will:
+1. Parse both Last.fm CSV and Spotify JSON exports
+2. Normalize track names and artist names for comparison
+3. Identify duplicate plays (same track within 5 minutes)
+4. Choose the best version of each play:
+   - Prefers Last.fm records with MusicBrainz IDs
+   - Otherwise prefers Spotify for better metadata quality
+5. Merge into a single chronological timeline
+6. Show detailed statistics about the merge
+
+This is perfect for:
+- Getting complete listening history from both services
+- Filling gaps where one service was used more than the other
+- Ensuring the best metadata quality for each play
+- Avoiding duplicate entries when both services tracked the same play
+
+**Example Output:**
+```
+📊 Merge Statistics
+═══════════════════════════════════════════
+Last.fm records:     15,234
+Spotify records:     8,567
+Total before merge:  23,801
+
+Duplicates removed:  3,421
+Last.fm unique:      11,813
+Spotify unique:      5,146
+
+Final merged total:  16,959
+
+Date range:
+  First: 2015-03-15 10:23:45
+  Last:  2025-01-07 14:32:11
+═══════════════════════════════════════════
+```
+
+### Re-Sync Mode
 
 If you've already imported scrobbles before and want to sync your Last.fm export with Teal without creating duplicates:
 
 ```bash
 # Preview what will be synced
-npm start -- -f lastfm.csv -i alice.bsky.social -p xxxx-xxxx-xxxx-xxxx --sync --dry-run
+npm start -- -i lastfm.csv -h alice.bsky.social -p xxxx-xxxx-xxxx-xxxx -m sync --dry-run
 
 # Perform the sync
-npm start -- -f lastfm.csv -i alice.bsky.social -p xxxx-xxxx-xxxx-xxxx --sync -y
+npm start -- -i lastfm.csv -h alice.bsky.social -p xxxx-xxxx-xxxx-xxxx -m sync -y
 ```
 
 Sync mode will:
···
 
 **Note:** Sync mode requires authentication even in dry-run mode to fetch existing records.
 
+### Remove Duplicates Mode
+
+If you accidentally imported duplicate records, you can clean them up:
+
+```bash
+# Preview duplicates (dry run)
+npm start -- -m deduplicate -h alice.bsky.social -p xxxx-xxxx-xxxx-xxxx --dry-run
+
+# Remove duplicates (keeps first occurrence)
+npm start -- -m deduplicate -h alice.bsky.social -p xxxx-xxxx-xxxx-xxxx
+```
+
+This will:
+1. Fetch all existing records from Teal
+2. Identify duplicate plays (same track, artist, and timestamp)
+3. Keep the first occurrence of each duplicate
+4. Delete the rest
+
 ### Interactive Mode
 
 The simplest way to use the importer - just run it and follow the prompts:
···
 
 ```bash
 # Full automation (Last.fm)
-npm start -- -f lastfm.csv -i alice.bsky.social -p xxxx-xxxx-xxxx-xxxx -y
+npm start -- -i lastfm.csv -h alice.bsky.social -p xxxx-xxxx-xxxx-xxxx -y
 
 # Import from Spotify (single file)
-npm start -- -f Streaming_History_Audio_2021-2023_0.json --spotify -i alice.bsky.social -p xxxx-xxxx-xxxx-xxxx -y
+npm start -- -i Streaming_History_Audio_2021-2023_0.json -m spotify -h alice.bsky.social -p xxxx-xxxx-xxxx-xxxx -y
 
 # Import from Spotify (directory with multiple files - recommended)
-npm start -- -f '/path/to/Spotify Extended Streaming History' --spotify -i alice.bsky.social -p xxxx-xxxx-xxxx-xxxx -y
+npm start -- -i '/path/to/Spotify Extended Streaming History' -m spotify -h alice.bsky.social -p xxxx-xxxx-xxxx-xxxx -y
+
+# Combined import (merge Last.fm and Spotify)
+npm start -- -i lastfm.csv --spotify-input '/path/to/Spotify Extended Streaming History' -m combined -h alice.bsky.social -p xxxx-xxxx-xxxx-xxxx -y
 
 # Preview without publishing
-npm start -- -f lastfm.csv --dry-run
+npm start -- -i lastfm.csv --dry-run
 
-# Preview Spotify import
-npm start -- -f '/path/to/Spotify Extended Streaming History' --spotify --dry-run
+# Preview with verbose debug output
+npm start -- -i lastfm.csv --dry-run -v
+
+# Quiet mode (only warnings and errors)
+npm start -- -i lastfm.csv -h alice.bsky.social -p xxxx-xxxx-xxxx-xxxx -q -y
 
 # Custom batch settings (advanced users)
-npm start -- -f lastfm.csv -i alice.bsky.social -b 20 -d 3000
+npm start -- -i lastfm.csv -h alice.bsky.social -b 20 -d 3000
 
 # Process newest tracks first
-npm start -- -f lastfm.csv -i alice.bsky.social -r -y
+npm start -- -i lastfm.csv -h alice.bsky.social -r -y
 ```
 
 ## Command Line Options
 
+### Authentication
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--handle <handle>` | `-h` | ATProto handle or DID (e.g., alice.bsky.social) |
+| `--password <pass>` | `-p` | ATProto app password |
+
+### Input
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--input <path>` | `-i` | Path to Last.fm CSV or Spotify JSON file/directory |
+| `--spotify-input <path>` | | Path to Spotify export (for combined mode) |
+
+### Mode
 | Option | Short | Description | Default |
 |--------|-------|-------------|---------|
-| `--help` | `-h` | Show help message | - |
-| `--file <path>` | `-f` | Path to Last.fm CSV or Spotify JSON file/directory | (prompted) |
-| `--spotify` | | Import from Spotify JSON export instead of Last.fm | false |
-| `--identifier <id>` | `-i` | ATProto handle or DID | (prompted) |
-| `--password <pass>` | `-p` | ATProto app password | (prompted) |
+| `--mode <mode>` | `-m` | Import mode | `lastfm` |
+
+**Available modes:**
+- `lastfm` - Import Last.fm export only
+- `spotify` - Import Spotify export only
+- `combined` - Merge Last.fm + Spotify exports
+- `sync` - Skip existing records (sync mode)
+- `deduplicate` - Remove duplicate records
+
+### Batch Configuration
+| Option | Short | Description | Default |
+|--------|-------|-------------|---------|
 | `--batch-size <num>` | `-b` | Records per batch | Auto-calculated |
-| `--batch-delay <ms>` | `-d` | Delay between batches in ms | 2000 (min: 1000) |
-| `--yes` | `-y` | Skip confirmation prompt | false |
-| `--dry-run` | `-n` | Preview without publishing | false |
-| `--reverse-chronological` | `-r` | Process newest first | false (oldest first) |
-| `--sync` | `-s` | Re-sync mode: only import new records | false |
+| `--batch-delay <ms>` | `-d` | Delay between batches in ms | 500 (min: 500) |
+
+### Import Options
+| Option | Short | Description | Default |
+|--------|-------|-------------|---------|
+| `--reverse` | `-r` | Process newest first | false (oldest first) |
+| `--yes` | `-y` | Skip confirmation prompts | false |
+| `--dry-run` | | Preview without importing | false |
+
+### Output
+| Option | Short | Description | Default |
+|--------|-------|-------------|---------|
+| `--verbose` | `-v` | Enable debug logging | false |
+| `--quiet` | `-q` | Suppress non-essential output | false |
+| `--help` | | Show help message | - |
+
+### Legacy Flags (Backwards Compatible)
+
+For backwards compatibility, the following old flags still work:
+- `--file` → Use `--input` instead
+- `--identifier` → Use `--handle` instead
+- `--spotify-file` → Use `--spotify-input` instead
+- `--reverse-chronological` → Use `--reverse` instead
+- `--spotify` → Use `--mode spotify` instead
+- `--combined` → Use `--mode combined` instead
+- `--sync` → Use `--mode sync` instead
+- `--remove-duplicates` → Use `--mode deduplicate` instead
 
 ### Batch Settings
 
 The importer automatically calculates optimal batch settings based on your total record count and rate limits. You generally **don't need** to specify batch settings unless you have specific requirements.
 
 **Automatic behavior:**
-- For imports < 1K records: Uses default settings (50 records/batch, 2s delay)
+- For imports < 1K records: Uses default settings (200 records/batch, 500ms delay)
 - For imports > 1K records: Automatically calculates settings to spread across multiple days
 
 **Manual override** (advanced):
 - `--batch-size`: Number of records processed per batch (1-200, PDS maximum)
-- `--batch-delay`: Milliseconds to wait between batches (min: 1000)
+- `--batch-delay`: Milliseconds to wait between batches (min: 500)
 
 ⚠️ Lower delays increase speed but risk hitting rate limits. The automatic calculation is recommended.
 
+## Logging and Output
+
+The importer includes a structured logging system with color-coded output:
+
+- **Green (✓)**: Success messages
+- **Cyan (→)**: Progress updates
+- **Yellow (⚠️)**: Warnings
+- **Red (✗)**: Errors
+- **Bold Red (🛑)**: Fatal errors
+
+### Verbosity Levels
+
+**Default Mode**: Shows standard operational messages
+```bash
+npm start -- -i lastfm.csv -h alice.bsky.social -p pass
+```
+
+**Verbose Mode** (`-v`): Shows detailed debug information including batch timing, API calls, etc.
+```bash
+npm start -- -i lastfm.csv -h alice.bsky.social -p pass -v
+```
+
+**Quiet Mode** (`-q`): Only shows warnings and errors
+```bash
+npm start -- -i lastfm.csv -h alice.bsky.social -p pass -q
+```
+
 ## Getting Your Data
 
 ### Last.fm Export
···
 - **trackName**: The name of the track
 - **artists**: Array of artist objects (requires `artistName`, optional `artistMbId` for Last.fm)
 - **playedTime**: ISO 8601 timestamp of when you listened
-- **submissionClientAgent**: Identifies this importer (`lastfm-importer/v0.3.0`)
+- **submissionClientAgent**: Identifies this importer (`lastfm-importer/v0.4.0`)
 - **musicServiceBaseDomain**: Set to `last.fm` or `spotify.com` depending on source
 
 ### Optional Fields (when available)
···
   "recordingMbId": "3a390ad3-fe56-45f2-a073-bebc45d6bde1",
   "playedTime": "2025-11-13T23:49:36Z",
   "originUrl": "https://www.last.fm/music/Cjbeards/_/Paint+My+Masterpiece",
-  "submissionClientAgent": "lastfm-importer/v0.3.0",
+  "submissionClientAgent": "lastfm-importer/v0.4.0",
   "musicServiceBaseDomain": "last.fm"
 }
 ```
···
   "releaseName": "Twenty",
   "playedTime": "2021-09-09T10:34:08Z",
   "originUrl": "https://open.spotify.com/track/3gZqDJkMZipOYCRjlHWgOV",
-  "submissionClientAgent": "lastfm-importer/v0.3.0",
+  "submissionClientAgent": "lastfm-importer/v0.4.0",
   "musicServiceBaseDomain": "spotify.com"
 }
 ```
···
 
 By default, records are processed **oldest first** (chronological order). This means your earliest scrobbles will appear first in your ATProto feed.
 
-Use the `--reverse-chronological` or `-r` flag to process **newest first** instead.
+Use the `--reverse` or `-r` flag to process **newest first** instead.
 
 ## Multi-Day Imports
 
···
 Preview what will be imported without actually publishing:
 
 ```bash
-npm start -- -f lastfm.csv --dry-run
+npm start -- -i lastfm.csv --dry-run
 ```
 
 Dry run shows:
···
 ├── src/
 │   ├── lib/
 │   │   ├── auth.ts         # Authentication & identity resolution
-│   │   ├── cli.ts          # Command line argument parsing
+│   │   ├── cli.ts          # Command line interface & argument parsing
 │   │   ├── csv.ts          # CSV parsing & record conversion
-│   │   └── publisher.ts    # Batch publishing with rate limiting
+│   │   ├── publisher.ts    # Batch publishing with rate limiting
+│   │   ├── spotify.ts      # Spotify JSON parsing
+│   │   ├── merge.ts        # Combined import deduplication
+│   │   └── sync.ts         # Re-sync mode & duplicate detection
 │   ├── utils/
+│   │   ├── logger.ts       # Structured logging system (NEW!)
 │   │   ├── helpers.ts      # Utility functions (timing, formatting)
 │   │   ├── input.ts        # User input handling (prompts, passwords)
-│   │   └── rate-limiter.ts # Rate limiting calculations
+│   │   ├── rate-limiter.ts # Rate limiting calculations
+│   │   ├── killswitch.ts   # Graceful shutdown handling
+│   │   ├── tid.ts          # TID generation from timestamps
+│   │   └── ui.ts           # UI elements (spinners, progress bars)
 │   ├── config.ts           # Configuration constants
 │   └── types.ts            # TypeScript type definitions
 ├── lexicons/               # fm.teal.alpha lexicon definitions
···
 │           └── play.json   # Play record schema
 ├── package.json
 ├── tsconfig.json
+├── CLI_IMPROVEMENTS.md     # Detailed CLI documentation
 └── README.md
 ```
 
···
 1. Calculates safe daily limit (90% of 1K = 900 records/day)
 2. Determines how many days needed for your import
 3. Calculates optimal batch size and delay to spread records evenly
-4. Enforces minimum 1 second delay between batches
+4. Enforces minimum 500ms delay between batches
 5. Shows clear schedule before starting
 
 ### Record Processing
···
 - Check progress messages - large imports take time
 - Multi-day imports pause for 24 hours between days
 - You can safely stop (Ctrl+C) and resume later
+- Use `--verbose` flag to see detailed progress
+
+### Too much output
+- Use `--quiet` flag to suppress non-essential messages
+- Only warnings and errors will be shown
+
+### Need more details
+- Use `--verbose` flag to see debug-level information
+- Shows batch timing, API calls, and detailed progress
 
 ## Contributing
 
···
 3. Make your changes with tests
 4. Submit a pull request
 
+See `CLI_IMPROVEMENTS.md` for developer documentation on the logging system and CLI structure.
+
 ## License
 
-MIT License - See LICENSE file for details
+AGPL-3.0-only - See LICENCE file for details
 
 ## Credits
 
···
 - CSV parsing via [csv-parse](https://www.npmjs.com/package/csv-parse)
 - Identity resolution via [Slingshot](https://slingshot.danner.cloud)
 - Follows the `fm.teal.alpha` lexicon standard
+- Colored output via [chalk](https://www.npmjs.com/package/chalk)
 
 ---
 
-**Note**: This tool is for personal use. Respect the terms of service and rate limits when exporting your data.
+**Note**: This tool is for personal use. Respect the terms of service and rate limits when exporting your data.

package-lock.json

···
 {
   "name": "lastfm-importer",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "lastfm-importer",
-      "version": "0.3.0",
+      "version": "0.4.0",
       "license": "AGPL-3.0-only",
       "dependencies": {
         "@atproto/api": "^0.13.35",
···
       "integrity": "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==",
       "license": "MIT",
       "dependencies": {
-        "emoji-regex": "^10.3.0",
-        "get-east-asian-width": "^1.0.0",
+        "emoji-regex": "^10.4.0",
+        "get-east-asian-width": "^0.4.0",
         "strip-ansi": "^7.1.0"
       },
       "engines": {

package.json

···
 {
   "name": "lastfm-importer",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Import Last.fm scrobbles to ATProto with rate limiting",
   "type": "module",
   "main": "./dist/index.js",

src/config.ts

···
 // Record type
 export const RECORD_TYPE = 'fm.teal.alpha.feed.play';
 
-// Client agent
-export const CLIENT_AGENT = `lastfm-importer/v0.3.0 (${process.platform}; Node/${process.version})`;
+// Build client agent string
+export function buildClientAgent() {
+  const PLATFORM_LABELS: Record<string, string> = {
+    darwin: 'macOS',
+    linux: 'Linux',
+    win32: 'Windows',
+  };
+
+  const platform =
+    PLATFORM_LABELS[process.platform] ?? process.platform;
+
+  return `lastfm-importer/v0.4.0 (${platform}; Node/${process.version})`;
+}
+
+ const CLIENT_AGENT = buildClientAgent();
 
 // Default batch configuration - aggressive defaults for maximum speed
 // Will dynamically adjust based on success/failure

src/lib/cli.ts

···
+#!/usr/bin/env node
+
 import { parseArgs } from 'node:util';
-import { AtpAgent } from '@atproto/api'; // Use AtpAgent for consistency
-import type { PlayRecord, Config, CommandLineArgs, PublishResult } from '../types.js'; 
-import { login } from './auth.js'; 
+import { AtpAgent } from '@atproto/api';
+import type { PlayRecord, Config, CommandLineArgs, PublishResult } from '../types.js';
+import { login } from './auth.js';
 import { parseLastFmCsv, convertToPlayRecord, sortRecords } from '../lib/csv.js';
-import { parseSpotifyJson, convertSpotifyToPlayRecord, sortSpotifyRecords } from '../lib/spotify.js'; 
-import { publishRecordsWithApplyWrites } from './publisher.js'; 
-import { prompt } from '../utils/input.js'; 
-import config from '../config.js'; 
-import { calculateOptimalBatchSize, showRateLimitInfo } from '../utils/helpers.js';
-import { fetchExistingRecords, filterNewRecords, displaySyncStats, removeDuplicates } from './sync.js'; 
+import { parseSpotifyJson, convertSpotifyToPlayRecord, sortSpotifyRecords } from '../lib/spotify.js';
+import { parseCombinedExports } from '../lib/merge.js';
+import { publishRecordsWithApplyWrites } from './publisher.js';
+import { prompt } from '../utils/input.js';
+import config from '../config.js';
+import { calculateOptimalBatchSize } from '../utils/helpers.js';
+import { fetchExistingRecords, filterNewRecords, displaySyncStats, removeDuplicates } from './sync.js';
+import { Logger, LogLevel, setGlobalLogger, log } from '../utils/logger.js';
 
 /**
  * Show help message
  */
 export function showHelp(): void {
-    console.log(`
-Last.fm to ATProto Importer v0.3.0
+  console.log(`
+${'\x1b[1m'}Last.fm to ATProto Importer v0.4.0${'\x1b[0m'}
+
+${'\x1b[1m'}USAGE:${'\x1b[0m'}
+  npm start [options]
+  lastfm-import [options]
+
+${'\x1b[1m'}AUTHENTICATION:${'\x1b[0m'}
+  -h, --handle <handle>          ATProto handle or DID (e.g., user.bsky.social)
+  -p, --password <password>      ATProto app password
+
+${'\x1b[1m'}INPUT:${'\x1b[0m'}
+  -i, --input <path>             Path to Last.fm CSV or Spotify JSON export
+  --spotify-input <path>         Path to Spotify export (for combined mode)
 
-Usage: npm start [options]
+${'\x1b[1m'}MODE:${'\x1b[0m'}
+  -m, --mode <mode>              Import mode (default: lastfm)
+                                 lastfm          Import Last.fm export only
+                                 spotify         Import Spotify export only
+                                 combined        Merge Last.fm + Spotify exports
+                                 sync            Skip existing records (sync mode)
+                                 deduplicate     Remove duplicate records
 
-Options:
-  -h, --help                     Show this help message
-  -f, --file <path>              Path to Last.fm CSV or Spotify JSON export file/directory
-  -i, --identifier <id>          ATProto handle or DID
-  -p, --password <pass>          ATProto app password
-  -b, --batch-size <num>         Number of records per batch (auto-calculated if not set)
+${'\x1b[1m'}BATCH CONFIGURATION:${'\x1b[0m'}
+  -b, --batch-size <number>      Records per batch (default: auto-calculated)
   -d, --batch-delay <ms>         Delay between batches in ms (default: 500, min: 500)
-  -y, --yes                      Skip confirmation prompt
-  -n, --dry-run                  Preview records without publishing
-  -r, --reverse-chronological    Process newest first (default: oldest first)
-  -s, --sync                     Re-sync mode: check existing Teal records and only import new ones
-  --spotify                      Import from Spotify JSON export instead of Last.fm CSV
-  --remove-duplicates            Remove duplicate records from Teal (keeps first occurrence)
+
+${'\x1b[1m'}IMPORT OPTIONS:${'\x1b[0m'}
+  -r, --reverse                  Process newest records first (default: oldest first)
+  -y, --yes                      Skip confirmation prompts
+  --dry-run                      Preview without importing
+
+${'\x1b[1m'}OUTPUT:${'\x1b[0m'}
+  -v, --verbose                  Enable verbose logging (debug level)
+  -q, --quiet                    Suppress non-essential output
+  --help                         Show this help message
+
+${'\x1b[1m'}EXAMPLES:${'\x1b[0m'}
+
+  ${'\x1b[2m'}# Import Last.fm export${'\x1b[0m'}
+  npm start -- -i lastfm-export.csv -h user.bsky.social -p app-password
+
+  ${'\x1b[2m'}# Import Spotify export${'\x1b[0m'}
+  npm start -- -i spotify-export/ -m spotify -h user.bsky.social -p app-password
+
+  ${'\x1b[2m'}# Combined import (merge both sources)${'\x1b[0m'}
+  npm start -- -i lastfm.csv --spotify-input spotify/ -m combined -h user.bsky.social -p pass
+
+  ${'\x1b[2m'}# Sync mode (only import new records)${'\x1b[0m'}
+  npm start -- -i lastfm.csv -m sync -h user.bsky.social -p app-password
+
+  ${'\x1b[2m'}# Dry run with verbose logging${'\x1b[0m'}
+  npm start -- -i lastfm.csv --dry-run -v
+
+  ${'\x1b[2m'}# Remove duplicate records${'\x1b[0m'}
+  npm start -- -m deduplicate -h user.bsky.social -p app-password
+
+${'\x1b[1m'}NOTES:${'\x1b[0m'}
+  • Rate limits: Max 10,000 records/day to avoid PDS rate limiting
+  • Import will auto-pause between days for large datasets
+  • Press Ctrl+C during import to stop gracefully after current batch
+  • Sync mode requires authentication even with --dry-run
+
+${'\x1b[1m'}MORE INFO:${'\x1b[0m'}
+  Repository: https://github.com/yourusername/atproto-lastfm-importer
+  Issues: https://github.com/yourusername/atproto-lastfm-importer/issues
 `);
 }
 
···
  * Parse command line arguments
  */
 export function parseCommandLineArgs(): CommandLineArgs {
-    // The options definition is identical to the CommandLineArgs keys
-    const options = {
-        help: { type: 'boolean', short: 'h', default: false },
-        file: { type: 'string', short: 'f' },
-        identifier: { type: 'string', short: 'i' },
-        password: { type: 'string', short: 'p' },
-        'batch-size': { type: 'string', short: 'b' },
-        'batch-delay': { type: 'string', short: 'd' },
-        yes: { type: 'boolean', short: 'y', default: false },
-        'dry-run': { type: 'boolean', short: 'n', default: false },
-        'reverse-chronological': { type: 'boolean', short: 'r', default: false },
-        sync: { type: 'boolean', short: 's', default: false },
-        spotify: { type: 'boolean', default: false },
-        'remove-duplicates': { type: 'boolean', default: false },
-    } as const; 
+  const options = {
+    // Help
+    help: { type: 'boolean', default: false },
+    
+    // Authentication
+    handle: { type: 'string', short: 'h' },
+    password: { type: 'string', short: 'p' },
+    
+    // Input
+    input: { type: 'string', short: 'i' },
+    'spotify-input': { type: 'string' },
+    
+    // Mode
+    mode: { type: 'string', short: 'm' },
+    
+    // Batch configuration
+    'batch-size': { type: 'string', short: 'b' },
+    'batch-delay': { type: 'string', short: 'd' },
+    
+    // Import options
+    reverse: { type: 'boolean', short: 'r', default: false },
+    yes: { type: 'boolean', short: 'y', default: false },
+    'dry-run': { type: 'boolean', default: false },
+    
+    // Output
+    verbose: { type: 'boolean', short: 'v', default: false },
+    quiet: { type: 'boolean', short: 'q', default: false },
     
-    try {
-        const { values } = parseArgs({ options, allowPositionals: false });
-        return values as CommandLineArgs; 
-    } catch (error) {
-        const err = error as Error;
-        console.error('Error parsing arguments:', err.message);
-        showHelp();
-        process.exit(1);
+    // Legacy flags for backwards compatibility (hidden from help)
+    file: { type: 'string', short: 'f' },  // Maps to --input
+    'spotify-file': { type: 'string' },    // Maps to --spotify-input
+    identifier: { type: 'string' },        // Maps to --handle
+    'reverse-chronological': { type: 'boolean' },  // Maps to --reverse
+    sync: { type: 'boolean', short: 's' },  // Maps to --mode sync
+    spotify: { type: 'boolean' },           // Maps to --mode spotify
+    combined: { type: 'boolean' },          // Maps to --mode combined
+    'remove-duplicates': { type: 'boolean' }, // Maps to --mode deduplicate
+  } as const;
+
+  try {
+    const { values } = parseArgs({ options, allowPositionals: false });
+    
+    // Handle legacy flag mappings
+    const normalizedArgs: CommandLineArgs = {
+      help: values.help,
+      handle: values.handle || values.identifier,
+      password: values.password,
+      input: values.input || values.file,
+      'spotify-input': values['spotify-input'] || values['spotify-file'],
+      'batch-size': values['batch-size'],
+      'batch-delay': values['batch-delay'],
+      reverse: values.reverse || values['reverse-chronological'],
+      yes: values.yes,
+      'dry-run': values['dry-run'],
+      verbose: values.verbose,
+      quiet: values.quiet,
+    };
+    
+    // Determine mode from new --mode flag or legacy flags
+    if (values.mode) {
+      normalizedArgs.mode = values.mode;
+    } else if (values['remove-duplicates']) {
+      normalizedArgs.mode = 'deduplicate';
+    } else if (values.combined) {
+      normalizedArgs.mode = 'combined';
+    } else if (values.sync) {
+      normalizedArgs.mode = 'sync';
+    } else if (values.spotify) {
+      normalizedArgs.mode = 'spotify';
+    } else {
+      normalizedArgs.mode = 'lastfm'; // default
     }
+    
+    return normalizedArgs;
+  } catch (error) {
+    const err = error as Error;
+    console.error('Error parsing arguments:', err.message);
+    showHelp();
+    process.exit(1);
+  }
+}
+
+/**
+ * Validate and normalize mode
+ */
+function validateMode(mode: string): 'lastfm' | 'spotify' | 'combined' | 'sync' | 'deduplicate' {
+  const validModes = ['lastfm', 'spotify', 'combined', 'sync', 'deduplicate'];
+  const normalized = mode.toLowerCase();
+  
+  if (!validModes.includes(normalized)) {
+    throw new Error(
+      `Invalid mode: ${mode}. Must be one of: ${validModes.join(', ')}`
+    );
+  }
+  
+  return normalized as 'lastfm' | 'spotify' | 'combined' | 'sync' | 'deduplicate';
 }
 
 /**
  * The full, real implementation of the CLI
  */
 export async function runCLI(): Promise<void> {
-    try {
-        const args = parseCommandLineArgs();
-        const cfg = config as Config; // Use a constant for the typed config
+  try {
+    const args = parseCommandLineArgs();
+    const cfg = config as Config;
 
-        if (args.help) {
-            showHelp();
-            return;
-        }
+    // Setup logging
+    const logger = new Logger(
+      args.quiet ? LogLevel.WARN :
+      args.verbose ? LogLevel.DEBUG :
+      LogLevel.INFO
+    );
+    setGlobalLogger(logger);
 
-        if (!args.file) {
-            throw new Error('Missing required argument: -f, --file <path>');
-        }
+    if (args.help) {
+      showHelp();
+      return;
+    }
 
-        const dryRun = args['dry-run'] ?? false;
-        const syncMode = args.sync ?? false;
-        const removeDuplicatesMode = args['remove-duplicates'] ?? false;
-        let agent: AtpAgent | null = null;
+    // Validate and normalize mode
+    const mode = validateMode(args.mode || 'lastfm');
+    const dryRun = args['dry-run'] ?? false;
+    let agent: AtpAgent | null = null;
 
-        // Remove duplicates mode - requires authentication but not file
-        if (removeDuplicatesMode) {
-            if (!args.identifier || !args.password) {
-                throw new Error('Missing required arguments for login: -i (identifier) and -p (password)');
-            }
-            
-            agent = await login(args.identifier, args.password, cfg.SLINGSHOT_RESOLVER) as AtpAgent;
-            
-            // Check for duplicates first
-            const result = await removeDuplicates(agent, cfg, true); // Always dry-run first to show info
-            
-            if (result.totalDuplicates === 0) {
-                return; // No duplicates, exit early
-            }
-            
-            // Ask for confirmation if not in dry-run mode
-            if (!dryRun && !(args.yes ?? false)) {
-                console.log(`⚠️  WARNING: This will permanently delete ${result.totalDuplicates} duplicate records from Teal.`);
-                console.log('   The first occurrence of each duplicate will be kept.\n');
-                const answer = await prompt('Are you sure you want to continue? (y/N) ');
-                if (answer.toLowerCase() !== 'y') {
-                    console.log('Duplicate removal cancelled by user.');
-                    process.exit(0);
-                }
-                
-                // Actually remove duplicates
-                await removeDuplicates(agent, cfg, false);
-                console.log('🎉 Duplicate removal complete!\n');
-            } else if (dryRun) {
-                console.log('DRY RUN: No records were actually removed.\n');
-                console.log('Remove --dry-run flag to actually delete duplicates.\n');
-            }
-            
-            return;
-        }
+    log.debug(`Mode: ${mode}`);
+    log.debug(`Dry run: ${dryRun}`);
+    log.debug(`Log level: ${args.verbose ? 'DEBUG' : args.quiet ? 'WARN' : 'INFO'}`);
 
-        // 1. Get Authentication (required for sync mode, even in dry-run)
-        if (!dryRun || syncMode) {
-            if (!args.identifier || !args.password) {
-                throw new Error('Missing required arguments for login: -i (identifier) and -p (password)');
-            }
-            // Assume login returns AtpAgent, as per the type fix
-            agent = await login(args.identifier, args.password, cfg.SLINGSHOT_RESOLVER) as AtpAgent; 
-        }
+    // Validate mode-specific requirements
+    if (mode === 'combined') {
+      if (!args.input || !args['spotify-input']) {
+        throw new Error('Combined mode requires both --input (Last.fm) and --spotify-input (Spotify)');
+      }
+    } else if (mode !== 'deduplicate' && !args.input) {
+      throw new Error('Missing required argument: --input <path>');
+    }
 
-        // 2. Parse and Prepare Records
-        const useSpotify = args.spotify ?? false;
-        let records: PlayRecord[];
-        let rawRecordCount: number;
-        
-        if (useSpotify) {
-            console.log('📀 Importing from Spotify export...\n');
-            const spotifyRecords = parseSpotifyJson(args.file);
-            rawRecordCount = spotifyRecords.length;
-            records = spotifyRecords.map(record => convertSpotifyToPlayRecord(record, cfg));
-        } else {
-            console.log('📀 Importing from Last.fm CSV export...\n');
-            const csvRecords = parseLastFmCsv(args.file);
-            rawRecordCount = csvRecords.length;
-            records = csvRecords.map(record => convertToPlayRecord(record, cfg));
-        }
-        
-        // 2.5. Sync Mode: Fetch existing records and filter duplicates
-        if (syncMode && agent) {
-            const originalRecords = [...records]; // Save before filtering
-            const existingRecords = await fetchExistingRecords(agent, cfg);
-            records = filterNewRecords(records, existingRecords);
-            
-            if (records.length === 0) {
-                console.log('✓ All records already exist in Teal. Nothing to import!');
-                process.exit(0);
-            }
-            
-            displaySyncStats(originalRecords, existingRecords, records);
-        }
-        
-        const totalRecords = records.length;
-        
-        const reverseChronological = args['reverse-chronological'] ?? false;
-        const sortedRecords = useSpotify 
-            ? sortSpotifyRecords(records, reverseChronological)
-            : sortRecords(records, reverseChronological); 
-        
-        // 3. Determine Batching parameters
-        let batchDelay = cfg.DEFAULT_BATCH_DELAY;
-        if (args['batch-delay']) {
-            const delay = parseInt(args['batch-delay'], 10);
-            if (isNaN(delay)) {
-                 throw new Error(`Invalid batch delay value: ${args['batch-delay']}`);
-            }
-            // Enforce minimum delay
-            batchDelay = Math.max(delay, cfg.MIN_BATCH_DELAY); 
-        }
-        
-        let batchSize: number;
-        if (args['batch-size']) {
-            batchSize = parseInt(args['batch-size'], 10);
-            if (isNaN(batchSize) || batchSize <= 0) {
-                 throw new Error(`Invalid batch size value: ${args['batch-size']}`);
-            }
-        } else {
-            // Calculate optimal batch size if not provided
-            batchSize = calculateOptimalBatchSize(totalRecords, batchDelay, cfg);
-        }
+    // Deduplicate mode
+    if (mode === 'deduplicate') {
+      if (!args.handle || !args.password) {
+        throw new Error('Deduplicate mode requires --handle and --password');
+      }
 
-        // 4. Show Rate Limiting Information
-        const recordsPerDay = cfg.RECORDS_PER_DAY_LIMIT * cfg.SAFETY_MARGIN;
-        const estimatedDays = Math.ceil(totalRecords / recordsPerDay);
+      log.section('Remove Duplicate Records');
+      agent = await login(args.handle, args.password, cfg.SLINGSHOT_RESOLVER) as AtpAgent;
 
-        // Updated call to match the expected signature in showRateLimitInfo (from previous response)
-        showRateLimitInfo(
-            totalRecords, 
-            batchSize, 
-            batchDelay, 
-            estimatedDays, 
-            cfg.RECORDS_PER_DAY_LIMIT,
-        );
+      const result = await removeDuplicates(agent, cfg, true);
 
-        // 5. Confirmation Prompt
-        if (!dryRun && !(args.yes ?? false)) {
-            if (syncMode) {
-                console.log(`\nReady to publish ${totalRecords.toLocaleString()} NEW records (${rawRecordCount - totalRecords} duplicates skipped).`);
-            } else {
-                console.log(`\nReady to publish ${totalRecords.toLocaleString()} records.`);
-            }
-            const answer = await prompt('Do you want to continue? (y/N) ');
-            if (answer.toLowerCase() !== 'y') {
-                console.log('Import cancelled by user.');
-                process.exit(0);
-            }
+      if (result.totalDuplicates === 0) {
+        return;
+      }
+
+      if (!dryRun && !args.yes) {
+        log.warn(`This will permanently delete ${result.totalDuplicates} duplicate records from Teal.`);
+        log.info('The first occurrence of each duplicate will be kept.');
+        log.blank();
+        const answer = await prompt('Are you sure you want to continue? (y/N) ');
+        if (answer.toLowerCase() !== 'y') {
+          log.info('Duplicate removal cancelled by user.');
+          process.exit(0);
         }
-        
-        // 6. Publish Records
-        const result: PublishResult = await publishRecordsWithApplyWrites(
-            agent, 
-            sortedRecords,
-            batchSize,
-            batchDelay,
-            cfg,
-            dryRun,
-            syncMode
-        );
+
+        await removeDuplicates(agent, cfg, false);
+        log.success('Duplicate removal complete!');
+      } else if (dryRun) {
+        log.info('DRY RUN: No records were actually removed.');
+        log.info('Remove --dry-run flag to actually delete duplicates.');
+      }
+
+      return;
+    }
+
+    // Authentication (required for sync mode, even in dry-run)
+    if (!dryRun || mode === 'sync') {
+      if (!args.handle || !args.password) {
+        throw new Error('Missing required arguments: --handle and --password');
+      }
+      log.debug('Authenticating...');
+      agent = await login(args.handle, args.password, cfg.SLINGSHOT_RESOLVER) as AtpAgent;
+      log.debug('Authentication successful');
+    }
 
-        // 7. Final Output
-        if (result.cancelled) {
-            console.log(`\nImport stopped gracefully. ${result.successCount} records processed.`);
-        } else if (dryRun) {
-            console.log(`\nDRY RUN COMPLETE${syncMode ? ' (SYNC MODE)' : ''}. No records were published.`);
-        } else {
-            console.log(`\n🎉 ${syncMode ? 'Sync' : 'Import'} Complete!`);
-            console.log(`Total records processed: ${result.successCount.toLocaleString()} (${result.errorCount.toLocaleString()} failed)`);
-            if (syncMode) {
-                console.log(`Duplicates skipped: ${rawRecordCount - totalRecords}`);
-            }
+    // Parse and prepare records
+    log.section('Loading Records');
+    let records: PlayRecord[];
+    let rawRecordCount: number;
+
+    if (mode === 'combined') {
+      log.info('Merging Last.fm and Spotify exports...');
+      records = parseCombinedExports(args.input!, args['spotify-input']!, cfg);
+      rawRecordCount = records.length;
+    } else if (mode === 'spotify') {
+      log.info('Importing from Spotify export...');
+      const spotifyRecords = parseSpotifyJson(args.input!);
+      rawRecordCount = spotifyRecords.length;
+      records = spotifyRecords.map(record => convertSpotifyToPlayRecord(record, cfg));
+    } else {
+      log.info('Importing from Last.fm CSV export...');
+      const csvRecords = parseLastFmCsv(args.input!);
+      rawRecordCount = csvRecords.length;
+      records = csvRecords.map(record => convertToPlayRecord(record, cfg));
+    }
+
+    log.success(`Loaded ${rawRecordCount.toLocaleString()} records`);
+
+    // Sync mode: filter existing records
+    if (mode === 'sync' && agent) {
+      log.section('Sync Mode');
+      log.info('Checking for existing records...');
+      const originalRecords = [...records];
+      const existingRecords = await fetchExistingRecords(agent, cfg);
+      records = filterNewRecords(records, existingRecords);
+
+      if (records.length === 0) {
+        log.success('All records already exist in Teal. Nothing to import!');
+        process.exit(0);
+      }
+
+      displaySyncStats(originalRecords, existingRecords, records);
+    }
+
+    const totalRecords = records.length;
+
+    // Sort records (skip for combined mode as it already sorts)
+    if (mode !== 'combined') {
+      log.debug(`Sorting records (reverse: ${args.reverse})...`);
+      records = mode === 'spotify'
+        ? sortSpotifyRecords(records, args.reverse ?? false)
+        : sortRecords(records, args.reverse ?? false);
+    }
+
+    // Determine batch parameters
+    log.section('Batch Configuration');
+    
+    let batchDelay = cfg.DEFAULT_BATCH_DELAY;
+    if (args['batch-delay']) {
+      const delay = parseInt(args['batch-delay'], 10);
+      if (isNaN(delay)) {
+        throw new Error(`Invalid batch delay: ${args['batch-delay']}`);
+      }
+      batchDelay = Math.max(delay, cfg.MIN_BATCH_DELAY);
+      if (delay < cfg.MIN_BATCH_DELAY) {
+        log.warn(`Batch delay increased to minimum: ${cfg.MIN_BATCH_DELAY}ms`);
+      }
+    }
+
+    let batchSize: number;
+    if (args['batch-size']) {
+      batchSize = parseInt(args['batch-size'], 10);
+      if (isNaN(batchSize) || batchSize <= 0) {
+        throw new Error(`Invalid batch size: ${args['batch-size']}`);
+      }
+      log.info(`Using manual batch size: ${batchSize} records`);
+    } else {
+      batchSize = calculateOptimalBatchSize(totalRecords, batchDelay, cfg);
+      log.info(`Using auto-calculated batch size: ${batchSize} records`);
+    }
+
+    log.info(`Batch delay: ${batchDelay}ms`);
+
+    // Show rate limiting information
+    log.section('Import Configuration');
+    log.info(`Total records: ${totalRecords.toLocaleString()}`);
+    log.info(`Batch size: ${batchSize} records`);
+    log.info(`Batch delay: ${batchDelay}ms`);
+    
+    const recordsPerDay = cfg.RECORDS_PER_DAY_LIMIT * cfg.SAFETY_MARGIN;
+    const estimatedDays = Math.ceil(totalRecords / recordsPerDay);
+    
+    if (estimatedDays > 1) {
+      log.info(`Duration: ${estimatedDays} days (${recordsPerDay.toLocaleString()} records/day limit)`);
+      log.warn('Large import will span multiple days with automatic pauses');
+    }
+    
+    log.blank();
+
+    // Confirmation prompt
+    if (!dryRun && !args.yes) {
+      const modeLabel = mode === 'combined' ? 'merged' : mode === 'sync' ? 'new' : '';
+      const skippedInfo = mode === 'sync' ? ` (${rawRecordCount - totalRecords} skipped)` : '';
+      log.raw(`Ready to publish ${totalRecords.toLocaleString()} ${modeLabel} records${skippedInfo}`);
+      const answer = await prompt('Continue? (y/N) ');
+      if (answer.toLowerCase() !== 'y') {
+        log.info('Cancelled by user.');
+        process.exit(0);
+      }
+      log.blank();
+    }
+
+    // Publish records
+    log.section('Publishing Records');
+    const result: PublishResult = await publishRecordsWithApplyWrites(
+      agent,
+      records,
+      batchSize,
+      batchDelay,
+      cfg,
+      dryRun,
+      mode === 'sync' || mode === 'combined'
+    );
+
+    // Final output
+    log.blank();
+    if (result.cancelled) {
+      log.warn(`Stopped: ${result.successCount.toLocaleString()} processed`);
+    } else if (dryRun) {
+      const modeLabel = mode === 'combined' ? 'COMBINED' : mode === 'sync' ? 'SYNC' : '';
+      log.success(`Dry run complete${modeLabel ? ` (${modeLabel})` : ''}`);
+    } else {
+      const modeLabel = mode === 'combined' ? 'Combined' : mode === 'sync' ? 'Sync' : 'Import';
+      log.success(`${modeLabel} complete!`);
+      log.info(`Processed: ${result.successCount.toLocaleString()} (${result.errorCount.toLocaleString()} failed)`);
+      if (mode === 'sync' || mode === 'combined') {
+        const skipped = rawRecordCount - totalRecords;
+        if (skipped > 0) {
+          log.info(`Skipped: ${skipped.toLocaleString()} duplicates`);
         }
+      }
+    }
 
-    } catch (error) {
-        // Handle fatal errors
-        const err = error as Error;
-        console.error('\n🛑 A fatal error occurred:');
-        console.error(err.message);
-        process.exit(1);
+  } catch (error) {
+    const err = error as Error;
+    log.blank();
+    log.fatal('A fatal error occurred:');
+    log.error(err.message);
+    if (log.getLevel() <= LogLevel.DEBUG) {
+      console.error(err.stack);
     }
-}
+    process.exit(1);
+  }
+}

src/lib/merge.ts

···
+import type { PlayRecord, Config } from '../types.js';
+import { parseLastFmCsv, convertToPlayRecord } from './csv.js';
+import { parseSpotifyJson, convertSpotifyToPlayRecord } from './spotify.js';
+import { formatDate } from '../utils/helpers.js';
+import { log } from '../utils/logger.js';
+
+/**
+ * Normalized record for comparison
+ */
+interface NormalizedRecord {
+  original: PlayRecord;
+  normalizedTrack: string;
+  normalizedArtist: string;
+  timestamp: number;
+  source: 'lastfm' | 'spotify';
+}
+
+/**
+ * Normalize a string for comparison (lowercase, remove extra spaces, punctuation)
+ */
+function normalizeString(str: string): string {
+  return str
+    .toLowerCase()
+    .replace(/[^\w\s]/g, '') // Remove punctuation
+    .replace(/\s+/g, ' ')     // Normalize whitespace
+    .trim();
+}
+
+/**
+ * Check if two records represent the same play
+ * They match if they have:
+ * 1. The same timestamp (within 5 minutes)
+ * 2. The same normalized track name
+ * 3. The same normalized artist name
+ */
+function areRecordsDuplicates(a: NormalizedRecord, b: NormalizedRecord): boolean {
+  // Check timestamp within 5 minutes (300000 ms)
+  const timeDiff = Math.abs(a.timestamp - b.timestamp);
+  if (timeDiff > 300000) {
+    return false;
+  }
+
+  // Check normalized track and artist
+  return (
+    a.normalizedTrack === b.normalizedTrack &&
+    a.normalizedArtist === b.normalizedArtist
+  );
+}
+
+/**
+ * Choose the better record between two duplicates
+ * Prefer Last.fm if it has MusicBrainz IDs, otherwise prefer Spotify
+ */
+function chooseBetterRecord(a: NormalizedRecord, b: NormalizedRecord): PlayRecord {
+  // Prefer Last.fm if it has any MusicBrainz IDs
+  const aHasMbIds = a.source === 'lastfm' && (
+    a.original.recordingMbId ||
+    a.original.releaseMbId ||
+    (a.original.artists[0]?.artistMbId)
+  );
+
+  const bHasMbIds = b.source === 'lastfm' && (
+    b.original.recordingMbId ||
+    b.original.releaseMbId ||
+    (b.original.artists[0]?.artistMbId)
+  );
+
+  if (aHasMbIds && !bHasMbIds) return a.original;
+  if (bHasMbIds && !aHasMbIds) return b.original;
+
+  // Otherwise prefer Spotify for its better metadata quality
+  if (a.source === 'spotify') return a.original;
+  if (b.source === 'spotify') return b.original;
+
+  // Default to first record
+  return a.original;
+}
+
+/**
+ * Merge and deduplicate records from multiple sources
+ */
+function mergeRecords(
+  lastfmRecords: PlayRecord[],
+  spotifyRecords: PlayRecord[]
+): { merged: PlayRecord[]; stats: MergeStats } {
+  log.info('Merging Last.fm and Spotify exports...');
+  log.blank();
+  
+  const stats: MergeStats = {
+    lastfmTotal: lastfmRecords.length,
+    spotifyTotal: spotifyRecords.length,
+    duplicatesRemoved: 0,
+    lastfmUnique: 0,
+    spotifyUnique: 0,
+    mergedTotal: 0,
+  };
+
+  // Normalize all records
+  const normalizedLastFm: NormalizedRecord[] = lastfmRecords.map(record => ({
+    original: record,
+    normalizedTrack: normalizeString(record.trackName),
+    normalizedArtist: normalizeString(record.artists[0]?.artistName || ''),
+    timestamp: new Date(record.playedTime).getTime(),
+    source: 'lastfm' as const,
+  }));
+
+  const normalizedSpotify: NormalizedRecord[] = spotifyRecords.map(record => ({
+    original: record,
+    normalizedTrack: normalizeString(record.trackName),
+    normalizedArtist: normalizeString(record.artists[0]?.artistName || ''),
+    timestamp: new Date(record.playedTime).getTime(),
+    source: 'spotify' as const,
+  }));
+
+  // Combine all records
+  const allRecords = [...normalizedLastFm, ...normalizedSpotify];
+
+  // Sort by timestamp
+  allRecords.sort((a, b) => a.timestamp - b.timestamp);
+
+  // Deduplicate
+  const uniqueRecords: PlayRecord[] = [];
+  const seen = new Set<string>();
+
+  for (const record of allRecords) {
+    // Create a key for duplicate detection
+    const key = `${record.normalizedTrack}|${record.normalizedArtist}|${Math.floor(record.timestamp / 60000)}`; // Round to minute
+
+    if (seen.has(key)) {
+      // Find the existing record to compare
+      const existingIndex = uniqueRecords.findIndex(r => {
+        const normalized: NormalizedRecord = {
+          original: r,
+          normalizedTrack: normalizeString(r.trackName),
+          normalizedArtist: normalizeString(r.artists[0]?.artistName || ''),
+          timestamp: new Date(r.playedTime).getTime(),
+          source: r.musicServiceBaseDomain === 'last.fm' ? 'lastfm' : 'spotify',
+        };
+        return areRecordsDuplicates(record, normalized);
+      });
+
+      if (existingIndex !== -1) {
+        // This is a duplicate - choose the better one
+        const existing: NormalizedRecord = {
+          original: uniqueRecords[existingIndex],
+          normalizedTrack: normalizeString(uniqueRecords[existingIndex].trackName),
+          normalizedArtist: normalizeString(uniqueRecords[existingIndex].artists[0]?.artistName || ''),
+          timestamp: new Date(uniqueRecords[existingIndex].playedTime).getTime(),
+          source: uniqueRecords[existingIndex].musicServiceBaseDomain === 'last.fm' ? 'lastfm' : 'spotify',
+        };
+
+        uniqueRecords[existingIndex] = chooseBetterRecord(existing, record);
+        stats.duplicatesRemoved++;
+        continue;
+      }
+    }
+
+    seen.add(key);
+    uniqueRecords.push(record.original);
+
+    // Track source statistics
+    if (record.source === 'lastfm') {
+      stats.lastfmUnique++;
+    } else {
+      stats.spotifyUnique++;
+    }
+  }
+
+  stats.mergedTotal = uniqueRecords.length;
+
+  // Sort final records chronologically
+  uniqueRecords.sort((a, b) => {
+    const timeA = new Date(a.playedTime).getTime();
+    const timeB = new Date(b.playedTime).getTime();
+    return timeA - timeB;
+  });
+
+  return { merged: uniqueRecords, stats };
+}
+
+/**
+ * Statistics about the merge operation
+ */
+export interface MergeStats {
+  lastfmTotal: number;
+  spotifyTotal: number;
+  duplicatesRemoved: number;
+  lastfmUnique: number;
+  spotifyUnique: number;
+  mergedTotal: number;
+}
+
+/**
+ * Display merge statistics
+ */
+function displayMergeStats(stats: MergeStats, merged: PlayRecord[]): void {
+  log.blank();
+  log.section('Merge Statistics');
+  log.info(`Last.fm: ${stats.lastfmTotal.toLocaleString()} records`);
+  log.info(`Spotify: ${stats.spotifyTotal.toLocaleString()} records`);
+  log.info(`Duplicates: ${stats.duplicatesRemoved.toLocaleString()} removed`);
+  log.info(`Result: ${stats.mergedTotal.toLocaleString()} unique records`);
+
+  if (merged.length > 0) {
+    const firstPlay = formatDate(merged[0].playedTime);
+    const lastPlay = formatDate(merged[merged.length - 1].playedTime);
+    log.info(`Range: ${firstPlay} to ${lastPlay}`);
+  }
+  log.blank();
+}
+
+/**
+ * Parse and merge Last.fm and Spotify exports
+ */
+export function parseCombinedExports(
+  lastfmPath: string,
+  spotifyPath: string,
+  config: Config
+): PlayRecord[] {
+  log.section('Combined Import Mode');
+  log.blank();
+
+  // Parse Last.fm
+  log.info('Parsing Last.fm export...');
+  const lastfmCsvRecords = parseLastFmCsv(lastfmPath);
+  const lastfmRecords = lastfmCsvRecords.map(r => convertToPlayRecord(r, config));
+
+  // Parse Spotify
+  log.info('Parsing Spotify export...');
+  const spotifyJsonRecords = parseSpotifyJson(spotifyPath);
+  const spotifyRecords = spotifyJsonRecords.map(r => convertSpotifyToPlayRecord(r, config));
+
+  // Merge and deduplicate
+  const { merged, stats } = mergeRecords(lastfmRecords, spotifyRecords);
+
+  // Display statistics
+  displayMergeStats(stats, merged);
+
+  return merged;
+}

src/lib/publisher.ts

···
 } from '../utils/rate-limiter.js';
 import { generateTIDFromISO } from '../utils/tid.js';
 import type { PlayRecord, Config, PublishResult } from '../types.js';
+import { log } from '../utils/logger.js';
 
 /**
  * Maximum operations allowed per applyWrites call
···
   let consecutiveFailures = 0;
   const MAX_CONSECUTIVE_FAILURES = 3;
 
-  console.log(`\n🚀 Starting adaptive import with aggressive settings...`);
-  console.log(`   Initial batch size: ${currentBatchSize} records`);
-  console.log(`   Initial delay: ${currentBatchDelay}ms`);
-  console.log(`   Will automatically adjust based on server response\n`);
+  log.section('Adaptive Import');
+  log.info(`Initial batch size: ${currentBatchSize} records`);
+  log.info(`Initial delay: ${currentBatchDelay}ms`);
+  log.info(`Will automatically adjust based on server response`);
+  log.blank();
+  log.info(`Publishing ${totalRecords.toLocaleString()} records using adaptive batching...`);
+  log.warn('Press Ctrl+C to stop gracefully after current batch');
+  log.blank();
 
   let successCount = 0;
   let errorCount = 0;
   const startTime = Date.now();
-
-  console.log(`Publishing ${totalRecords} records using adaptive batching...`);
-  console.log(`\n🚨 Press Ctrl+C to stop gracefully after current batch\n`);
 
   let i = 0;
   while (i < totalRecords) {
···
     const batchNum = Math.floor(i / currentBatchSize) + 1;
     const progress = ((i / totalRecords) * 100).toFixed(1);
 
-    console.log(
+    log.progress(
       `[${progress}%] Batch ${batchNum} (records ${i + 1}-${Math.min(i + currentBatchSize, totalRecords)}) [size: ${currentBatchSize}, delay: ${currentBatchDelay}ms]`
     );
 
···
       consecutiveFailures = 0;
 
       const batchDuration = Date.now() - batchStartTime;
-      console.log(
-        `  ✓ Complete in ${batchDuration}ms (${batchSuccessCount} successful)`
-      );
+      log.debug(`Batch complete in ${batchDuration}ms (${batchSuccessCount} successful)`);
 
       // Speed up if we're doing well (after 5 consecutive successes)
       if (consecutiveSuccesses >= 5 && currentBatchDelay > config.MIN_BATCH_DELAY) {
···
           Math.floor(currentBatchDelay * 0.8)
         );
         if (oldDelay !== currentBatchDelay) {
-          console.log(`  ⚡ Speeding up! Delay: ${oldDelay}ms → ${currentBatchDelay}ms`);
+          log.info(`⚡ Speeding up! Delay: ${oldDelay}ms → ${currentBatchDelay}ms`);
         }
         consecutiveSuccesses = 0;
       }
···
       consecutiveSuccesses = 0;
 
       if (isRateLimitError) {
-        console.error(`  ⚠️  Rate limit hit! Backing off...`);
+        log.warn('Rate limit hit! Backing off...');
         
         // Exponential backoff
         const backoffMultiplier = Math.pow(2, consecutiveFailures);
···
           10 // Minimum 10 records
         );
 
-        console.log(`  📉 Adjusted: batch size → ${currentBatchSize}, delay → ${currentBatchDelay}ms`);
-        console.log(`  ⏳ Waiting ${currentBatchDelay}ms before retry...`);
+        log.info(`📉 Adjusted: batch size → ${currentBatchSize}, delay → ${currentBatchDelay}ms`);
+        log.info(`⏳ Waiting ${currentBatchDelay}ms before retry...`);
         
         await new Promise((resolve) => setTimeout(resolve, currentBatchDelay));
         
···
       } else {
         // Other error - log and continue
         errorCount += batch.length;
-        console.error(`  ✗ Batch failed: ${err.message}`);
+        log.error(`Batch failed: ${err.message}`);
         
         // Log failed records
         batch.slice(0, 3).forEach((record) => {
-          console.error(`     - ${record.trackName} by ${record.artists[0]?.artistName}`);
+          log.debug(`Failed: ${record.trackName} by ${record.artists[0]?.artistName}`);
         });
         if (batch.length > 3) {
-          console.error(`     ... and ${batch.length - 3} more`);
+          log.debug(`... and ${batch.length - 3} more failed`);
         }
 
         // If too many consecutive failures, slow down
         if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
           currentBatchDelay = Math.min(currentBatchDelay * 2, 10000);
           currentBatchSize = Math.max(Math.floor(currentBatchSize / 2), 10);
-          console.log(`  📉 Multiple failures: adjusted to ${currentBatchSize} records, ${currentBatchDelay}ms delay`);
+          log.warn(`📉 Multiple failures: adjusted to ${currentBatchSize} records, ${currentBatchDelay}ms delay`);
         }
         
         i += batch.length; // Skip failed batch
···
     const remainingRecords = totalRecords - i;
     const estimatedRemaining = remainingRecords / Math.max(recordsPerSecond, 1);
     
-    console.log(
-      `  ⏱  Elapsed: ${elapsed} | Speed: ${recordsPerSecond.toFixed(1)} rec/s | Remaining: ~${formatDuration(estimatedRemaining * 1000)}\n`
+    log.debug(
+      `Elapsed: ${elapsed} | Speed: ${recordsPerSecond.toFixed(1)} rec/s | Remaining: ~${formatDuration(estimatedRemaining * 1000)}`
     );
+    log.blank();
 
     // Check again before waiting
     if (isImportCancelled()) {
···
     );
 
     if (rateLimitParams.estimatedDays > 1) {
-      const dailySchedule = calculateDailySchedule(
-        totalRecords,
-        batchSize,
-        batchDelay,
-        rateLimitParams.recordsPerDay
-      );
+      // Only show daily schedule in verbose/debug mode
+      if (log.getLevel() <= 0) { // DEBUG level
+        const dailySchedule = calculateDailySchedule(
+          totalRecords,
+          batchSize,
+          batchDelay,
+          rateLimitParams.recordsPerDay
+        );
 
-      console.log('📅 Multi-Day Import Schedule:\n');
-      dailySchedule.forEach((day) => {
-        console.log(`   Day ${day.day}:`);
-        console.log(`     Records ${day.recordsStart + 1}-${day.recordsEnd} (${day.recordsCount} total)`);
-        if (day.pauseAfter) {
-          console.log(`     → Pause 24h after completion`);
-        }
-      });
-      console.log('');
+        console.log('📅 Multi-Day Import Schedule:\n');
+        dailySchedule.forEach((day) => {
+          console.log(`   Day ${day.day}:`);
+          console.log(`     Records ${day.recordsStart + 1}-${day.recordsEnd} (${day.recordsCount} total)`);
+          if (day.pauseAfter) {
+            console.log(`     → Pause 24h after completion`);
+          }
+        });
+        console.log('');
+      }
     }
   }
 
-  console.log(`\n=== DRY RUN MODE ${syncMode ? '(SYNC)' : ''} ===`);
+  log.section(`DRY RUN MODE ${syncMode ? '(SYNC)' : ''}`);
   if (syncMode) {
-    console.log(`Sync mode enabled: Only new records will be published`);
+    log.info('Sync mode: Only new records will be published');
   }
-  console.log(`Would publish ${totalRecords} records using applyWrites`);
-  console.log(`Batch size: ${Math.min(batchSize, MAX_APPLY_WRITES_OPS)} records per applyWrites call`);
-
+  log.info(`Total: ${totalRecords.toLocaleString()} records`);
+  log.info(`Batch: ${Math.min(batchSize, MAX_APPLY_WRITES_OPS)} records per call`);
+  
   if (rateLimitParams.estimatedDays > 1) {
-    console.log(
-      `Import would span ${rateLimitParams.estimatedDays} days with automatic pauses\n`
-    );
+    log.info(`Duration: ${rateLimitParams.estimatedDays} days with automatic pauses`);
   } else {
-    console.log(`Estimated time: ${formatDuration(Math.ceil(totalRecords / batchSize) * batchDelay)}\n`);
+    log.info(`Time: ~${formatDuration(Math.ceil(totalRecords / batchSize) * batchDelay)}`);
   }
+  log.blank();
 
   // Show first 5 records as preview
   const previewCount = Math.min(5, totalRecords);
-  console.log(`Preview of first ${previewCount} records (in processing order):\n`);
+  log.info(`Preview (first ${previewCount} records):`);
+  log.blank();
 
   for (let i = 0; i < previewCount; i++) {
     const record = records[i];
-    console.log(`${i + 1}. ${record.artists[0]?.artistName} - ${record.trackName}`);
-    console.log(`   Album: ${record.releaseName || 'N/A'}`);
-    console.log(`   Played: ${formatDate(record.playedTime, true)}`);
-    console.log(`   URL: ${record.originUrl}`);
-
-    // Show MusicBrainz IDs if available
-    const mbids = [];
-    if (record.artists[0]?.artistMbId)
-      mbids.push(`Artist: ${record.artists[0].artistMbId}`);
-    if (record.recordingMbId) mbids.push(`Recording: ${record.recordingMbId}`);
-    if (record.releaseMbId) mbids.push(`Release: ${record.releaseMbId}`);
-
+    const artistName = record.artists[0]?.artistName || 'Unknown Artist';
+    
+    log.raw(`${i + 1}. ${artistName} - ${record.trackName}`);
+    
+    // Album/Release
+    if (record.releaseName) {
+      log.raw(`   Album: ${record.releaseName}`);
+    }
+    
+    // Timestamp
+    log.raw(`   Played: ${formatDate(record.playedTime, true)}`);
+    
+    // Source and URL
+    log.raw(`   Source: ${record.musicServiceBaseDomain}`);
+    log.raw(`   URL: ${record.originUrl}`);
+    
+    // MusicBrainz IDs (if available)
+    const mbids: string[] = [];
+    if (record.artists[0]?.artistMbId) mbids.push(`Artist: ${record.artists[0].artistMbId}`);
+    if (record.recordingMbId) mbids.push(`Track: ${record.recordingMbId}`);
+    if (record.releaseMbId) mbids.push(`Album: ${record.releaseMbId}`);
+    
     if (mbids.length > 0) {
-      console.log(`   MBIDs: ${mbids.join(', ')}`);
+      log.raw(`   MusicBrainz IDs: ${mbids.join(', ')}`);
     }
-    console.log('');
+    
+    // Record metadata
+    log.raw(`   Record Type: ${record.$type}`);
+    log.raw(`   Client: ${record.submissionClientAgent}`);
+    
+    log.blank();
   }
 
   if (totalRecords > previewCount) {
-    console.log(`... and ${totalRecords - previewCount} more records\n`);
+    log.info(`... and ${(totalRecords - previewCount).toLocaleString()} more records`);
+    log.blank();
   }
 
-  console.log('=== DRY RUN COMPLETE ===');
-  console.log('No records were actually published.');
-  console.log('Remove --dry-run flag to publish for real.\n');
+  log.section('DRY RUN COMPLETE');
+  log.info('No records were published.');
+  log.info('Remove --dry-run to publish for real.');
 
   return { successCount: totalRecords, errorCount: 0, cancelled: false };
 }
···
   errorCount: number,
   totalRecords: number
 ): PublishResult {
-  console.log(`\n🛑 Import cancelled by user`);
-  console.log(`   Processed: ${successCount}/${totalRecords} records`);
-  console.log(`   Remaining: ${totalRecords - successCount} records\n`);
+  log.blank();
+  log.warn('Import cancelled by user');
+  log.info(`Processed: ${successCount.toLocaleString()}/${totalRecords.toLocaleString()} records`);
+  log.info(`Remaining: ${(totalRecords - successCount).toLocaleString()} records`);
   return { successCount, errorCount, cancelled: true };
 }

src/lib/sync.ts

···
 import type { PlayRecord, Config } from '../types.js';
 import { formatDate, formatDateRange } from '../utils/helpers.js';
 import * as ui from '../utils/ui.js';
+import { log } from '../utils/logger.js';
 
 interface ExistingRecord {
   uri: string;
···
   agent: AtpAgent,
   config: Config
 ): Promise<Map<string, ExistingRecord>> {
-  console.log('\n=== Fetching Existing Teal Records ===');
+  log.section('Fetching Existing Teal Records');
   const { RECORD_TYPE } = config;
   const did = agent.session?.did;
 
···
 
       // Show progress
       if (totalFetched % 500 === 0 && totalFetched > 0) {
-        console.log(`  Fetched ${totalFetched} records...`);
+        log.progress(`Fetched ${totalFetched.toLocaleString()} records...`);
       }
     } while (cursor);
 
-    console.log(`✓ Found ${existingRecords.size} existing records\n`);
+    log.success(`Found ${existingRecords.size.toLocaleString()} existing records`);
+    log.blank();
     return existingRecords;
   } catch (error) {
     const err = error as Error;
-    console.error('✗ Failed to fetch existing records:', err.message);
+    log.error(`Failed to fetch existing records: ${err.message}`);
     throw error;
   }
 }
···
   lastfmRecords: PlayRecord[],
   existingRecords: Map<string, ExistingRecord>
 ): PlayRecord[] {
-  console.log('\n=== Identifying New Records ===');
+  log.section('Identifying New Records');
 
   const newRecords: PlayRecord[] = [];
   const duplicates: PlayRecord[] = [];
···
     }
   }
 
-  console.log(`  Total Last.fm records: ${lastfmRecords.length}`);
-  console.log(`  Already in Teal: ${duplicates.length}`);
-  console.log(`  New records to import: ${newRecords.length}\n`);
+  log.info(`Total: ${lastfmRecords.length.toLocaleString()} records`);
+  log.info(`Existing: ${duplicates.length.toLocaleString()} already in Teal`);
+  log.info(`New: ${newRecords.length.toLocaleString()} to import`);
+  log.blank();
 
-  // Show some examples of duplicates if any
-  if (duplicates.length > 0 && duplicates.length <= 5) {
-    console.log('Examples of existing records (skipped):');
-    duplicates.slice(0, 5).forEach((record, i) => {
-      console.log(`  ${i + 1}. ${record.artists[0]?.artistName} - ${record.trackName}`);
-      console.log(`     Played: ${formatDate(record.playedTime, true)}`);
+  // Show some examples of duplicates if any (only in verbose mode)
+  if (log.getLevel() <= 0 && duplicates.length > 0) { // DEBUG level
+    const exampleCount = Math.min(3, duplicates.length);
+    log.debug('Examples of existing records (skipped):');
+    duplicates.slice(0, exampleCount).forEach((record, i) => {
+      log.debug(`  ${i + 1}. ${record.artists[0]?.artistName} - ${record.trackName}`);
+      log.debug(`     ${formatDate(record.playedTime, true)}`);
     });
-    console.log('');
-  } else if (duplicates.length > 5) {
-    console.log('Examples of existing records (skipped):');
-    duplicates.slice(0, 5).forEach((record, i) => {
-      console.log(`  ${i + 1}. ${record.artists[0]?.artistName} - ${record.trackName}`);
-      console.log(`     Played: ${formatDate(record.playedTime, true)}`);
-    });
-    console.log(`  ... and ${duplicates.length - 5} more duplicates\n`);
+    if (duplicates.length > exampleCount) {
+      log.debug(`  ... and ${(duplicates.length - exampleCount).toLocaleString()} more`);
+    }
+    log.blank();
   }
 
   return newRecords;
···
   const existingArray = Array.from(existingRecords.values()).map(r => r.value);
   const existingRange = getRecordTimeRange(existingArray);
 
-  console.log('=== Sync Statistics ===');
-  console.log(`Last.fm Export:`);
-  console.log(`  Total records: ${lastfmRecords.length}`);
+  log.section('Sync Statistics');
+  log.info(`Last.fm export: ${lastfmRecords.length.toLocaleString()} records`);
   if (lastfmRange) {
-    console.log(`  Date range: ${formatDateRange(lastfmRange.earliest, lastfmRange.latest)}`);
+    log.info(`  Range: ${formatDateRange(lastfmRange.earliest, lastfmRange.latest)}`);
   }
-  console.log('');
+  log.blank();
 
-  console.log(`Teal (Current):`);
-  console.log(`  Total records: ${existingRecords.size}`);
+  log.info(`Teal current: ${existingRecords.size.toLocaleString()} records`);
   if (existingRange) {
-    console.log(`  Date range: ${formatDateRange(existingRange.earliest, existingRange.latest)}`);
+    log.info(`  Range: ${formatDateRange(existingRange.earliest, existingRange.latest)}`);
   }
-  console.log('');
+  log.blank();
 
-  console.log(`Sync Result:`);
-  console.log(`  Records to import: ${newRecords.length}`);
-  console.log(`  Duplicates skipped: ${lastfmRecords.length - newRecords.length}`);
-  console.log(`  Match rate: ${((1 - newRecords.length / lastfmRecords.length) * 100).toFixed(1)}%`);
-  console.log('');
+  log.info(`New to import: ${newRecords.length.toLocaleString()}`);
+  log.info(`Duplicates: ${(lastfmRecords.length - newRecords.length).toLocaleString()} skipped`);
+  log.info(`Match rate: ${((1 - newRecords.length / lastfmRecords.length) * 100).toFixed(1)}%`);
+  log.blank();
 }
 
 /**

src/types.ts

···
 }
 
 export interface CommandLineArgs {
+  // Help
   help?: boolean;
-  file?: string;
-  identifier?: string;
+  
+  // Authentication
+  handle?: string;
   password?: string;
+  
+  // Input
+  input?: string;
+  'spotify-input'?: string;
+  
+  // Mode
+  mode?: string;
+  
+  // Batch configuration
   'batch-size'?: string;
   'batch-delay'?: string;
+  
+  // Import options
+  reverse?: boolean;
   yes?: boolean;
   'dry-run'?: boolean;
+  
+  // Output
+  verbose?: boolean;
+  quiet?: boolean;
+  
+  // Legacy flags (for backwards compatibility)
+  file?: string;
+  'spotify-file'?: string;
+  identifier?: string;
   'reverse-chronological'?: boolean;
   sync?: boolean;
   spotify?: boolean;
+  combined?: boolean;
   'remove-duplicates'?: boolean;
 }
 
···
   SLINGSHOT_RESOLVER: string;
 
   RECORD_TYPE: string;
-}
+}

src/utils/helpers.ts

···
 
 /**
  * Logs rate limiting and batching information to the console.
+ * Note: This function cannot import log from logger.ts to avoid circular dependencies,
+ * so it uses console.log directly. The CLI controls the log level, so this output
+ * is appropriately controlled.
  */
 export function showRateLimitInfo(
   totalRecords: number,

src/utils/logger.ts

···
+/**
+ * Structured logging utility with log levels, formatting, and file logging
+ */
+import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
+
+export enum LogLevel {
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+  SILENT = 4,
+}
+
+export class Logger {
+  private level: LogLevel;
+  private prefix: string;
+  private logFile: string | null = null;
+  private logStream: fs.WriteStream | null = null;
+
+  constructor(level: LogLevel = LogLevel.INFO, prefix: string = '') {
+    this.level = level;
+    this.prefix = prefix;
+  }
+
+  setLevel(level: LogLevel): void {
+    this.level = level;
+  }
+
+  getLevel(): LogLevel {
+    return this.level;
+  }
+
+  /**
+   * Enable logging to file
+   */
+  enableFileLogging(logDir: string = 'logs'): void {
+    try {
+      // Create logs directory if it doesn't exist
+      const logsPath = path.resolve(process.cwd(), logDir);
+      if (!fs.existsSync(logsPath)) {
+        fs.mkdirSync(logsPath, { recursive: true });
+      }
+
+      // Create log filename with timestamp
+      const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
+      this.logFile = path.join(logsPath, `import-${timestamp}.log`);
+
+      // Create write stream
+      this.logStream = fs.createWriteStream(this.logFile, { flags: 'a' });
+
+      this.writeToFile(`Log started at ${new Date().toISOString()}`);
+      this.writeToFile(`Log file: ${this.logFile}`);
+      this.writeToFile('='.repeat(80));
+    } catch (error) {
+      console.error('Failed to enable file logging:', error);
+    }
+  }
+
+  /**
+   * Get the current log file path
+   */
+  getLogFile(): string | null {
+    return this.logFile;
+  }
+
+  /**
+   * Close the log file stream
+   */
+  closeLogFile(): void {
+    if (this.logStream) {
+      this.writeToFile('='.repeat(80));
+      this.writeToFile(`Log ended at ${new Date().toISOString()}`);
+      this.logStream.end();
+      this.logStream = null;
+    }
+  }
+
+  /**
+   * Write to log file (without formatting)
+   */
+  private writeToFile(message: string): void {
+    if (this.logStream) {
+      const timestamp = new Date().toISOString();
+      this.logStream.write(`[${timestamp}] ${message}\n`);
+    }
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    return level >= this.level;
+  }
+
+  private formatMessage(message: string, prefix?: string): string {
+    const finalPrefix = prefix || this.prefix;
+    return finalPrefix ? `${finalPrefix} ${message}` : message;
+  }
+
+  private logToFile(level: string, message: string): void {
+    if (this.logStream) {
+      const cleanMessage = message.replace(/\x1b\[[0-9;]*m/g, ''); // Remove ANSI codes
+      this.writeToFile(`[${level}] ${cleanMessage}`);
+    }
+  }
+
+  debug(message: string, ...args: any[]): void {
+    if (this.shouldLog(LogLevel.DEBUG)) {
+      const formatted = chalk.gray(`[DEBUG] ${this.formatMessage(message)}`);
+      console.log(formatted, ...args);
+      this.logToFile('DEBUG', this.formatMessage(message));
+    }
+  }
+
+  info(message: string, ...args: any[]): void {
+    if (this.shouldLog(LogLevel.INFO)) {
+      const formatted = this.formatMessage(message);
+      console.log(formatted, ...args);
+      this.logToFile('INFO', formatted);
+    }
+  }
+
+  success(message: string, ...args: any[]): void {
+    if (this.shouldLog(LogLevel.INFO)) {
+      const formatted = chalk.green(`✓ ${this.formatMessage(message)}`);
+      console.log(formatted, ...args);
+      this.logToFile('SUCCESS', this.formatMessage(message));
+    }
+  }
+
+  warn(message: string, ...args: any[]): void {
+    if (this.shouldLog(LogLevel.WARN)) {
+      const formatted = chalk.yellow(`⚠️  ${this.formatMessage(message)}`);
+      console.warn(formatted, ...args);
+      this.logToFile('WARN', this.formatMessage(message));
+    }
+  }
+
+  error(message: string, ...args: any[]): void {
+    if (this.shouldLog(LogLevel.ERROR)) {
+      const formatted = chalk.red(`✗ ${this.formatMessage(message)}`);
+      console.error(formatted, ...args);
+      this.logToFile('ERROR', this.formatMessage(message));
+    }
+  }
+
+  fatal(message: string, ...args: any[]): void {
+    if (this.shouldLog(LogLevel.ERROR)) {
+      const formatted = chalk.red.bold(`🛑 ${this.formatMessage(message)}`);
+      console.error(formatted, ...args);
+      this.logToFile('FATAL', this.formatMessage(message));
+    }
+  }
+
+  // Progress and status messages (always shown unless SILENT)
+  progress(message: string, ...args: any[]): void {
+    if (this.level < LogLevel.SILENT) {
+      const formatted = chalk.cyan(`→ ${this.formatMessage(message)}`);
+      console.log(formatted, ...args);
+      this.logToFile('PROGRESS', this.formatMessage(message));
+    }
+  }
+
+  // Section headers
+  section(title: string): void {
+    if (this.shouldLog(LogLevel.INFO)) {
+      const formatted = chalk.bold(`\n=== ${title} ===`);
+      console.log(formatted);
+      this.logToFile('SECTION', title);
+    }
+  }
+
+  // Blank line
+  blank(): void {
+    if (this.level < LogLevel.SILENT) {
+      console.log('');
+    }
+  }
+
+  // Raw output (bypasses log level for important user-facing info)
+  raw(message: string, ...args: any[]): void {
+    if (this.level < LogLevel.SILENT) {
+      console.log(message, ...args);
+      this.logToFile('INFO', message);
+    }
+  }
+}
+
+// Global logger instance
+let globalLogger: Logger = new Logger(LogLevel.INFO);
+
+export function setGlobalLogger(logger: Logger): void {
+  globalLogger = logger;
+}
+
+export function getLogger(): Logger {
+  return globalLogger;
+}
+
+// Convenience exports
+export const log = {
+  debug: (msg: string, ...args: any[]) => globalLogger.debug(msg, ...args),
+  info: (msg: string, ...args: any[]) => globalLogger.info(msg, ...args),
+  success: (msg: string, ...args: any[]) => globalLogger.success(msg, ...args),
+  warn: (msg: string, ...args: any[]) => globalLogger.warn(msg, ...args),
+  error: (msg: string, ...args: any[]) => globalLogger.error(msg, ...args),
+  fatal: (msg: string, ...args: any[]) => globalLogger.fatal(msg, ...args),
+  progress: (msg: string, ...args: any[]) => globalLogger.progress(msg, ...args),
+  section: (title: string) => globalLogger.section(title),
+  blank: () => globalLogger.blank(),
+  raw: (msg: string, ...args: any[]) => globalLogger.raw(msg, ...args),
+  setLevel: (level: LogLevel) => globalLogger.setLevel(level),
+  getLevel: () => globalLogger.getLevel(),
+  enableFileLogging: (logDir?: string) => globalLogger.enableFileLogging(logDir),
+  getLogFile: () => globalLogger.getLogFile(),
+  closeLogFile: () => globalLogger.closeLogFile(),
+};

src/utils/rate-limiter.ts

···
  * Display rate limit warning
  */
 export function displayRateLimitWarning(): void {
-  console.log('\n⚠️  ═══════════════════════════════════════════════════════════════════════════════');
-  console.log('⚠️  IMPORTANT: Bluesky AppView Rate Limits');
-  console.log('⚠️  ═══════════════════════════════════════════════════════════════════════════════');
-  console.log('⚠️');
-  console.log('⚠️  Exceeding 10K records per day can rate limit your ENTIRE PDS on Bluesky\'s');
-  console.log('⚠️  AppView. This affects ALL users on your PDS, not just your account!');
-  console.log('⚠️');
-  console.log('⚠️  This importer automatically limits imports to 1K records per day by default');
-  console.log('⚠️  with automatic batching and pauses to stay within safe limits.');
-  console.log('⚠️');
-  console.log('⚠️  See: https://docs.bsky.app/blog/rate-limits-pds-v3');
-  console.log('⚠️  ═══════════════════════════════════════════════════════════════════════════════\n');
+  console.log('');
+  console.log('⚠️  IMPORTANT: Rate Limits');
+  console.log('   Exceeding 10K records/day can rate limit your ENTIRE PDS.');
+  console.log('   This affects ALL users on your PDS, not just your account.');
+  console.log('   Import automatically limits to 10K records/day with pauses.');
+  console.log('   See: https://docs.bsky.app/blog/rate-limits-pds-v3');
+  console.log('');
 }
 
 /**