feat: Implement Folio CLI Phase 1 - Interactive Shell

This commit adds a new interactive command-line interface for Folio portfolio management.
The CLI provides an interactive shell environment for running portfolio simulations,
analyzing positions, and exploring investment scenarios.

Key features:
- Interactive shell with command history and auto-completion
- Portfolio loading and viewing capabilities
- SPY simulation with customizable parameters
- Position-specific analysis with detailed breakdowns
- Comprehensive help system

Technical details:
- Uses prompt_toolkit for the interactive shell
- Leverages existing code from src/folio modules
- Maintains the same output formatting using Rich
- Follows project coding conventions and passes linting

The CLI provides at least the same functionality as scripts/folio-simulator.py
but in an interactive shell environment where users can run multiple commands
without restarting the application.

This is Phase 1 of the planned implementation, focusing on core functionality.
Future phases will add enhanced interactivity, additional commands, and more
sophisticated analysis capabilities.

docs/ai-rules.md

@@ -8,6 +8,8 @@ alwaysApply: true
   - Read [project-design.md](docs/project-design.md) to understand the codebase
   - Read [project-conventions.md](docs/project-conventions.md) to understand _how_ to write code for the codebase
 - Run `make lint` and `make test` after every change. `lint` in particular can be run very frequently.
+- When user starts a prompt with `QQ:` or `Question:`, just answer the question or prompt without producing code.
+- Prefer small testable steps, after each step give a summary to the user and summarize the next step
 
 ## Prohibited actions
 

docs/focli-mvp-v2.md

@@ -0,0 +1,770 @@
+# Folio CLI MVP Plan (v2)
+
+## Project Checklist
+
+### Phase 1: Basic Interactive Shell
+- [x] Set up project structure
+- [x] Install dependencies (prompt_toolkit, rich)
+- [x] Create basic REPL shell with command history
+- [x] Implement portfolio loading functionality
+- [x] Port basic SPY simulation command
+- [x] Add help and exit commands
+
+### Phase 2: Enhanced Interactivity
+- [ ] Implement position-specific analysis
+- [ ] Add ticker filtering capability
+- [ ] Create state management between commands
+- [ ] Implement parameter customization
+- [ ] Add detailed position breakdowns
+
+### Phase 3: Additional Commands and Polish
+- [ ] Add portfolio summary command
+- [ ] Implement "what-if" scenario analysis
+- [ ] Add comprehensive help text
+- [ ] Improve error handling
+- [ ] Add command auto-completion
+- [ ] Create tests for core functionality
+
+## Overview
+
+The Folio CLI MVP will create an interactive shell-like environment that leverages the existing portfolio simulation and analysis capabilities in the Folio codebase. This approach will allow users to run simulations, explore different options, and analyze portfolio data through an interactive command-line interface.
+
+## Goals
+
+1. Create an interactive shell for portfolio simulation and analysis
+2. Reuse existing code from `src/folio` modules
+3. Provide at least the same functionality as `scripts/folio-simulator.py`
+4. Allow users to run multiple commands without restarting the application
+5. Support detailed analysis of specific position groups
+
+## Technology Selection
+
+After analyzing the codebase and evaluating different options, we recommend:
+
+### Primary Framework: Prompt Toolkit + Typer
+
+**[Python Prompt Toolkit](https://python-prompt-toolkit.readthedocs.io/)** is ideal for our interactive shell requirements:
+- Designed specifically for building interactive command-line applications
+- Built-in support for REPL (Read-Eval-Print Loop) interfaces
+- Excellent auto-completion capabilities
+- History navigation and search
+- Customizable key bindings
+
+**[Typer](https://typer.tiangolo.com/)** will be used for command parsing within the shell:
+- Modern API with type hints
+- Built on Click, inheriting its stability
+- Excellent documentation and growing community
+
+**[Rich](https://rich.readthedocs.io/)** will continue to be used for output formatting:
+- Already used in the existing simulator
+- Excellent for tables, charts, and formatted text
+- Good integration with both Prompt Toolkit and Typer
+
+## Implementation Plan
+
+### Phase 1: Basic Interactive Shell (1 week)
+
+#### Tasks
+- [ ] **1.1 Set up project structure**
+  - Create directory structure
+  - Set up package files
+  - Configure dependencies
+
+- [ ] **1.2 Create Shell Framework**
+  - Set up a basic REPL using Prompt Toolkit
+  - Implement command history and navigation
+  - Add basic auto-completion for commands
+
+- [ ] **1.3 Implement Portfolio Loading**
+  - Create portfolio loading function
+  - Add error handling for missing files
+  - Implement portfolio reloading command
+
+- [ ] **1.4 Port Core Simulator Commands**
+  - Directly use `simulate_portfolio_with_spy_changes` from `src/folio/simulator.py`
+  - Reuse the portfolio loading code from `src/folio/portfolio.py`
+  - Maintain the same output formatting using Rich
+
+- [ ] **1.5 Add Basic Help System**
+  - Implement help command
+  - Add command documentation
+  - Create exit command with confirmation
+
+#### Deliverables
+- Working REPL shell
+- Basic simulation command
+- Portfolio loading functionality
+- Help and exit commands
+
+### Phase 2: Enhanced Interactivity (1 week)
+
+#### Tasks
+- [ ] **2.1 Add Position-Specific Analysis**
+  - Implement commands to analyze specific position groups
+  - Create detailed position view
+  - Add option chain visualization
+
+- [ ] **2.2 Implement Filtering Capabilities**
+  - Allow filtering by ticker
+  - Add sorting options
+  - Implement focus mode for specific tickers
+
+- [ ] **2.3 Create State Management**
+  - Allow referencing previous simulation results
+  - Maintain portfolio state between commands
+  - Implement session history
+
+- [ ] **2.4 Add Parameter Customization**
+  - Add ability to modify simulation parameters incrementally
+  - Create parameter presets
+  - Implement parameter validation
+
+#### Deliverables
+- Position analysis commands
+- Filtering and sorting capabilities
+- State management between commands
+- Parameter customization options
+
+### Phase 3: Additional Commands and Polish (1 week)
+
+#### Tasks
+- [ ] **3.1 Add Supplementary Commands**
+  - Portfolio viewing and basic analysis
+  - "What-if" scenario analysis
+  - Portfolio comparison tools
+
+- [ ] **3.2 Enhance Command Completion**
+  - Add context-aware command completion
+  - Implement parameter suggestions
+  - Create command aliases
+
+- [ ] **3.3 Improve Error Handling**
+  - Add comprehensive error messages
+  - Implement error recovery
+  - Create debugging commands
+
+- [ ] **3.4 Add Testing and Documentation**
+  - Write unit tests for core functionality
+  - Create integration tests
+  - Add comprehensive help text
+  - Create user documentation
+
+#### Deliverables
+- Additional analysis commands
+- Enhanced command completion
+- Robust error handling
+- Comprehensive tests and documentation
+
+## Implementation Details
+
+### Project Structure
+
+```
+src/
+└── focli/
+    ├── __init__.py         # Package initialization
+    ├── shell.py            # Interactive shell implementation
+    ├── commands/           # Command implementations
+    │   ├── __init__.py     # Command registration
+    │   ├── simulate.py     # Simulation commands
+    │   ├── position.py     # Position analysis commands
+    │   └── portfolio.py    # Portfolio management commands
+    ├── formatters.py       # Output formatting utilities
+    └── utils.py            # Utility functions
+```
+
+#### Key Files and Their Responsibilities
+
+- **`shell.py`**: Main entry point, REPL implementation, command routing
+- **`commands/__init__.py`**: Command registration and discovery
+- **`commands/simulate.py`**: Portfolio simulation commands
+- **`commands/position.py`**: Position-specific analysis
+- **`commands/portfolio.py`**: Portfolio management and overview
+- **`formatters.py`**: Rich formatting for tables, charts, and text
+- **`utils.py`**: Helper functions and utilities
+
+### Code Reuse Strategy
+
+The implementation will directly leverage the following existing modules:
+
+1. **`src/folio/simulator.py`**
+   - `simulate_portfolio_with_spy_changes`: Core simulation function
+   - `calculate_percentage_changes`: Utility for calculating changes
+
+2. **`src/folio/portfolio.py`**
+   - `process_portfolio_data`: Load and process portfolio data
+   - `recalculate_portfolio_with_prices`: Recalculate with price changes
+   - `calculate_portfolio_summary`: Generate portfolio summaries
+
+3. **`src/folio/data_model.py`**
+   - Data classes for portfolio representation
+   - Conversion methods between objects and dictionaries
+
+4. **`src/folio/formatting.py`**
+   - Formatting utilities for currency and percentages
+
+### Implementation Approach
+
+#### 1. Interactive Shell Implementation
+
+The interactive shell will be implemented using Prompt Toolkit's REPL capabilities:
+
+```python
+# src/focli/shell.py
+from prompt_toolkit import PromptSession
+from prompt_toolkit.completion import NestedCompleter
+from rich.console import Console
+
+from src.folio.portfolio import process_portfolio_data
+from src.focli.commands import get_command_registry, execute_command
+
+console = Console()
+
+def create_completer():
+    """Create a nested completer for command auto-completion."""
+    # Build a nested completer from the command registry
+    commands = get_command_registry()
+
+    # Create completion dictionary with subcommands and parameters
+    completion_dict = {}
+    for cmd_name, cmd_info in commands.items():
+        if cmd_info.get("subcommands"):
+            completion_dict[cmd_name] = {
+                subcmd: None for subcmd in cmd_info["subcommands"]
+            }
+        else:
+            completion_dict[cmd_name] = None
+
+    return NestedCompleter.from_nested_dict(completion_dict)
+
+def main():
+    """Main entry point for the Folio CLI."""
+    console.print("[bold]Folio Interactive Shell[/bold]")
+    console.print("Type 'help' for available commands.")
+
+    # Create session with auto-completion
+    session = PromptSession(completer=create_completer())
+
+    # Initialize application state
+    state = {
+        "portfolio_groups": None,
+        "portfolio_summary": None,
+        "last_simulation": None,
+        "loaded_portfolio": None,
+    }
+
+    # Try to load default portfolio
+    try:
+        load_portfolio("private-data/portfolio-private.csv", state)
+    except Exception as e:
+        console.print(f"[yellow]Could not load default portfolio: {e}[/yellow]")
+        console.print("[yellow]Use 'load <path>' to load a portfolio.[/yellow]")
+
+    # Main REPL loop
+    while True:
+        try:
+            # Get user input
+            text = session.prompt("folio> ")
+
+            if not text.strip():
+                continue
+
+            # Handle exit command directly
+            if text.strip().lower() == "exit":
+                if confirm_exit():
+                    break
+                continue
+
+            # Process the command
+            execute_command(text, state, console)
+
+        except KeyboardInterrupt:
+            # Handle Ctrl+C
+            console.print("\n[yellow]Use 'exit' to exit the application.[/yellow]")
+            continue
+        except EOFError:
+            # Handle Ctrl+D
+            console.print("\nGoodbye!")
+            break
+        except Exception as e:
+            # Handle unexpected errors
+            console.print(f"[bold red]Error:[/bold red] {str(e)}")
+
+    console.print("Goodbye!")
+
+def load_portfolio(path, state):
+    """Load a portfolio from a CSV file."""
+    import pandas as pd
+    from src.folio.portfolio import process_portfolio_data
+
+    df = pd.read_csv(path)
+    groups, summary, _ = process_portfolio_data(df, update_prices=True)
+
+    state["portfolio_groups"] = groups
+    state["portfolio_summary"] = summary
+    state["loaded_portfolio"] = path
+
+    return groups, summary
+
+def confirm_exit():
+    """Confirm exit with the user."""
+    from prompt_toolkit.shortcuts import confirm
+
+    return confirm("Are you sure you want to exit?")
+
+if __name__ == "__main__":
+    main()
+```
+
+#### 2. Command Registration and Execution
+
+Commands will be registered and executed through a central registry:
+
+```python
+# src/focli/commands/__init__.py
+from typing import Dict, Any, Callable, List
+
+# Command registry
+_COMMANDS = {}
+
+def register_command(name: str, handler: Callable, help_text: str, subcommands: List[str] = None):
+    """Register a command with the command registry."""
+    _COMMANDS[name] = {
+        "handler": handler,
+        "help": help_text,
+        "subcommands": subcommands,
+    }
+
+def get_command_registry():
+    """Get the command registry."""
+    return _COMMANDS
+
+def execute_command(command_line: str, state: Dict[str, Any], console):
+    """Execute a command from the command line."""
+    # Parse the command line
+    parts = command_line.strip().split()
+    if not parts:
+        return
+
+    command = parts[0].lower()
+    args = parts[1:]
+
+    # Check if the command exists
+    if command not in _COMMANDS:
+        console.print(f"[bold red]Unknown command:[/bold red] {command}")
+        console.print("Type 'help' to see available commands.")
+        return
+
+    # Execute the command
+    try:
+        _COMMANDS[command]["handler"](args, state, console)
+    except Exception as e:
+        console.print(f"[bold red]Error executing command '{command}':[/bold red] {str(e)}")
+
+# Import and register commands
+from .simulate import simulate_command
+from .position import position_command
+from .portfolio import portfolio_command
+from .help import help_command
+
+# Register commands
+register_command("simulate", simulate_command, "Simulate portfolio performance with SPY changes",
+                ["spy", "scenario"])
+register_command("position", position_command, "Analyze a specific position group")
+register_command("portfolio", portfolio_command, "View and analyze portfolio",
+                ["list", "summary", "load"])
+register_command("help", help_command, "Show help information")
+```
+
+#### 3. Simulation Command Implementation
+
+The simulation command will directly use the existing simulator functionality:
+
+```python
+# src/focli/commands/simulate.py
+from typing import Dict, Any, List
+import numpy as np
+
+from src.folio.simulator import simulate_portfolio_with_spy_changes
+from src.focli.formatters import display_simulation_results
+
+def simulate_command(args: List[str], state: Dict[str, Any], console):
+    """Simulate portfolio performance with SPY changes."""
+    # Check if a portfolio is loaded
+    if not state.get("portfolio_groups"):
+        console.print("[bold red]Error:[/bold red] No portfolio loaded.")
+        console.print("Use 'portfolio load <path>' to load a portfolio.")
+        return
+
+    # Default parameters
+    range_pct = 20.0
+    steps = 13
+    focus_tickers = None
+    detailed = False
+
+    # Parse arguments
+    i = 0
+    while i < len(args):
+        arg = args[i]
+
+        if arg == "spy":
+            # This is the default simulation type
+            i += 1
+            continue
+
+        elif arg == "--range" or arg == "-r":
+            if i + 1 < len(args):
+                try:
+                    range_pct = float(args[i + 1])
+                    i += 2
+                    continue
+                except ValueError:
+                    console.print(f"[bold red]Invalid range value:[/bold red] {args[i + 1]}")
+                    return
+            else:
+                console.print("[bold red]Missing value for --range[/bold red]")
+                return
+
+        elif arg == "--steps" or arg == "-s":
+            if i + 1 < len(args):
+                try:
+                    steps = int(args[i + 1])
+                    i += 2
+                    continue
+                except ValueError:
+                    console.print(f"[bold red]Invalid steps value:[/bold red] {args[i + 1]}")
+                    return
+            else:
+                console.print("[bold red]Missing value for --steps[/bold red]")
+                return
+
+        elif arg == "--focus" or arg == "-f":
+            if i + 1 < len(args):
+                focus_tickers = [t.strip().upper() for t in args[i + 1].split(",")]
+                i += 2
+                continue
+            else:
+                console.print("[bold red]Missing value for --focus[/bold red]")
+                return
+
+        elif arg == "--detailed" or arg == "-d":
+            detailed = True
+            i += 1
+            continue
+
+        else:
+            console.print(f"[bold red]Unknown argument:[/bold red] {arg}")
+            return
+
+    # Calculate the step size
+    step_size = (2 * range_pct) / (steps - 1) if steps > 1 else 0
+
+    # Generate the SPY changes
+    spy_changes = [-range_pct + i * step_size for i in range(steps)]
+
+    # Ensure we have a zero point
+    if 0.0 not in spy_changes and steps > 2:
+        # Find the closest point to zero and replace it with zero
+        closest_to_zero = min(spy_changes, key=lambda x: abs(x))
+        zero_index = spy_changes.index(closest_to_zero)
+        spy_changes[zero_index] = 0.0
+
+    # Convert to percentages
+    spy_changes = [change / 100.0 for change in spy_changes]
+
+    # Run the simulation
+    console.print(f"[bold]Running simulation with range ±{range_pct}% and {steps} steps...[/bold]")
+
+    results = simulate_portfolio_with_spy_changes(
+        portfolio_groups=state["portfolio_groups"],
+        spy_changes=spy_changes,
+        cash_like_positions=state["portfolio_summary"].cash_like_positions,
+        pending_activity_value=state["portfolio_summary"].pending_activity_value,
+    )
+
+    # Store results for future reference
+    state["last_simulation"] = results
+
+    # Display the results
+    display_simulation_results(results, detailed, focus_tickers, console)
+```
+
+#### 4. Formatters Implementation
+
+The display functions will reuse the formatting from the existing simulator script:
+
+```python
+# src/focli/formatters.py
+from rich.console import Console
+from rich.table import Table
+from rich.panel import Panel
+from rich.box import ROUNDED
+
+from src.folio.formatting import format_currency
+
+def display_simulation_results(results, detailed=False, focus_tickers=None, console=None):
+    """Display simulation results using Rich."""
+    if console is None:
+        console = Console()
+
+    # Get the current value (at 0% SPY change)
+    current_value = results["current_value"]
+
+    # Get min and max values
+    min_value = min(results["portfolio_values"])
+    max_value = max(results["portfolio_values"])
+    min_index = results["portfolio_values"].index(min_value)
+    max_index = results["portfolio_values"].index(max_value)
+    min_spy_change = results["spy_changes"][min_index] * 100  # Convert to percentage
+    max_spy_change = results["spy_changes"][max_index] * 100  # Convert to percentage
+
+    # Create a summary table
+    console.print("\n[bold cyan]Portfolio Simulation Results[/bold cyan]")
+
+    summary_table = Table(title="Portfolio Summary", box=ROUNDED)
+    summary_table.add_column("Metric", style="cyan")
+    summary_table.add_column("Value", style="green")
+    summary_table.add_column("SPY Change", style="yellow")
+
+    summary_table.add_row("Current Value", f"${current_value:,.2f}", "0.0%")
+    summary_table.add_row("Minimum Value", f"${min_value:,.2f}", f"{min_spy_change:.1f}%")
+    summary_table.add_row("Maximum Value", f"${max_value:,.2f}", f"{max_spy_change:.1f}%")
+
+    console.print(summary_table)
+
+    # Create a detailed table with all values
+    value_table = Table(title="Portfolio Values at Different SPY Changes", box=ROUNDED)
+    value_table.add_column("SPY Change", style="yellow")
+    value_table.add_column("Portfolio Value", style="green")
+    value_table.add_column("Change", style="cyan")
+    value_table.add_column("% Change", style="magenta")
+
+    for i, spy_change in enumerate(results["spy_changes"]):
+        portfolio_value = results["portfolio_values"][i]
+        value_change = portfolio_value - current_value
+        pct_change = (value_change / current_value) * 100 if current_value != 0 else 0
+
+        # Format the change with color based on positive/negative
+        change_str = f"${value_change:+,.2f}"
+        pct_change_str = f"{pct_change:+.2f}%"
+
+        value_table.add_row(
+            f"{spy_change * 100:.1f}%",
+            f"${portfolio_value:,.2f}",
+            change_str,
+            pct_change_str,
+        )
+
+    console.print(value_table)
+
+    # If detailed is True, show position-level analysis
+    if detailed:
+        display_position_analysis(results, focus_tickers, console)
+
+def display_position_analysis(results, focus_tickers=None, console=None):
+    """Display position-level analysis."""
+    if console is None:
+        console = Console()
+
+    # Get position details
+    position_details = results.get("position_details", {})
+    position_changes = results.get("position_changes", {})
+
+    # Filter positions if focus_tickers is provided
+    if focus_tickers:
+        filtered_details = {}
+        filtered_changes = {}
+        for ticker in focus_tickers:
+            if ticker in position_details:
+                filtered_details[ticker] = position_details[ticker]
+            if ticker in position_changes:
+                filtered_changes[ticker] = position_changes[ticker]
+        position_details = filtered_details
+        position_changes = filtered_changes
+
+    # Display position details
+    console.print("\n[bold cyan]Position Analysis[/bold cyan]")
+
+    for ticker, details in position_details.items():
+        # Create a panel for each position
+        position_table = Table(title=f"{ticker} Details", box=ROUNDED)
+        position_table.add_column("Metric", style="cyan")
+        position_table.add_column("Value", style="green")
+
+        # Add basic position details
+        position_table.add_row("Beta", f"{details.get('beta', 0):.2f}")
+        position_table.add_row("Current Value", format_currency(details.get('current_value', 0)))
+        position_table.add_row("Stock Value", format_currency(details.get('stock_value', 0)))
+        position_table.add_row("Option Value", format_currency(details.get('option_value', 0)))
+
+        # Add stock details if available
+        if details.get('has_stock'):
+            position_table.add_row("Stock Quantity", f"{details.get('stock_quantity', 0)}")
+            position_table.add_row("Stock Price", format_currency(details.get('stock_price', 0)))
+
+        # Add option details if available
+        if details.get('has_options'):
+            position_table.add_row("Option Count", f"{details.get('option_count', 0)}")
+
+        console.print(position_table)
+
+        # If we have change data, show it
+        if ticker in position_changes:
+            changes = position_changes[ticker]
+
+            # Create a table for position changes
+            changes_table = Table(title=f"{ticker} Changes with SPY", box=ROUNDED)
+            changes_table.add_column("SPY Change", style="yellow")
+            changes_table.add_column("Position Value", style="green")
+            changes_table.add_column("Change", style="cyan")
+            changes_table.add_column("% Change", style="magenta")
+
+            for i, spy_change in enumerate(results["spy_changes"]):
+                if i < len(changes["values"]):
+                    value = changes["values"][i]
+                    change = changes["changes"][i]
+                    pct_change = changes["pct_changes"][i]
+
+                    changes_table.add_row(
+                        f"{spy_change * 100:.1f}%",
+                        format_currency(value),
+                        f"{format_currency(change, include_sign=True)}",
+                        f"{pct_change:+.2f}%",
+                    )
+
+            console.print(changes_table)
+
+def display_position_details(group, detailed=True, console=None):
+    """Display detailed information about a position group."""
+    if console is None:
+        console = Console()
+
+    ticker = group.ticker
+    console.print(f"\n[bold cyan]Position Details: {ticker}[/bold cyan]")
+
+    # Create a summary table
+    summary_table = Table(title=f"{ticker} Summary", box=ROUNDED)
+    summary_table.add_column("Metric", style="cyan")
+    summary_table.add_column("Value", style="green")
+
+    # Add basic position details
+    summary_table.add_row("Beta", f"{group.beta:.2f}")
+    summary_table.add_row("Net Exposure", format_currency(group.net_exposure))
+    summary_table.add_row("Beta-Adjusted Exposure", format_currency(group.beta_adjusted_exposure))
+
+    # Add stock details if available
+    if group.stock_position:
+        stock = group.stock_position
+        summary_table.add_row("Stock Quantity", f"{stock.quantity}")
+        summary_table.add_row("Stock Price", format_currency(stock.price))
+        summary_table.add_row("Stock Market Value", format_currency(stock.market_value))
+
+    # Add option summary if available
+    if group.option_positions:
+        summary_table.add_row("Option Count", f"{len(group.option_positions)}")
+        summary_table.add_row("Call Options", f"{group.call_count}")
+        summary_table.add_row("Put Options", f"{group.put_count}")
+        summary_table.add_row("Total Delta Exposure", format_currency(group.total_delta_exposure))
+
+    console.print(summary_table)
+
+    # If detailed and we have options, show option details
+    if detailed and group.option_positions:
+        options_table = Table(title=f"{ticker} Option Positions", box=ROUNDED)
+        options_table.add_column("Type", style="cyan")
+        options_table.add_column("Strike", style="green", justify="right")
+        options_table.add_column("Expiry", style="yellow")
+        options_table.add_column("Quantity", style="green", justify="right")
+        options_table.add_column("Delta", style="magenta", justify="right")
+        options_table.add_column("Value", style="green", justify="right")
+
+        for option in group.option_positions:
+            options_table.add_row(
+                option.option_type,
+                format_currency(option.strike),
+                option.expiry,
+                f"{option.quantity}",
+                f"{option.delta:.2f}",
+                format_currency(option.market_value),
+            )
+
+        console.print(options_table)
+```
+
+## Future Extensibility
+
+While keeping the MVP simple, we'll ensure future extensibility by:
+
+1. **Modular Design**
+   - Separate command processing from execution
+   - Use clear interfaces between components
+
+2. **Extensible Command Structure**
+   - Design for easy addition of new commands
+   - Allow for command hierarchies in the future
+
+3. **State Management**
+   - Implement a simple state manager that can be expanded
+   - Allow for saving and loading state
+
+4. **Documentation**
+   - Document extension points
+   - Create clear examples for adding new commands
+
+## Implementation Roadmap
+
+### Week 1: Basic Interactive Shell
+1. **Day 1-2**: Set up project structure and implement shell framework
+   - Create directory structure
+   - Implement basic REPL with command history
+   - Set up command registration system
+
+2. **Day 3-4**: Implement portfolio loading and basic commands
+   - Create portfolio loading functionality
+   - Implement help command
+   - Add exit command with confirmation
+
+3. **Day 5**: Port core simulator command
+   - Implement SPY simulation command
+   - Create basic formatters for simulation results
+   - Test with sample portfolio
+
+### Week 2: Enhanced Interactivity
+1. **Day 1-2**: Implement position-specific analysis
+   - Create position command
+   - Implement detailed position view
+   - Add option chain visualization
+
+2. **Day 3-4**: Add filtering and state management
+   - Implement ticker filtering
+   - Create state management between commands
+   - Add parameter customization
+
+3. **Day 5**: Testing and refinement
+   - Test with various portfolios
+   - Refine error handling
+   - Improve user feedback
+
+### Week 3: Additional Commands and Polish
+1. **Day 1-2**: Add supplementary commands
+   - Implement portfolio summary command
+   - Add "what-if" scenario analysis
+   - Create portfolio comparison tools
+
+2. **Day 3-4**: Enhance command completion and documentation
+   - Implement context-aware command completion
+   - Add comprehensive help text
+   - Create user documentation
+
+3. **Day 5**: Final testing and packaging
+   - Write unit tests
+   - Create integration tests
+   - Package for distribution
+
+## Conclusion
+
+This MVP approach focuses on creating a simple but effective interactive shell for Folio portfolio analysis. By directly leveraging the existing codebase, we can quickly create a working product that provides immediate value while setting the foundation for future enhancements.
+
+The interactive shell will allow users to run multiple simulations, explore different options, and analyze portfolio data without restarting the application, significantly improving the user experience compared to the current script-based approach.
+
+By following the phased implementation plan and detailed roadmap, we can ensure a systematic approach to development, with clear milestones and deliverables at each stage. The modular design will facilitate future extensions and enhancements as user needs evolve.

scripts/focli.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+"""
+Folio CLI - Interactive command-line interface for Folio portfolio management.
+
+This script provides an interactive shell for running portfolio simulations,
+analyzing positions, and exploring investment scenarios.
+
+Usage:
+    python scripts/focli.py
+
+Commands:
+    help                Show help information
+    simulate spy        Simulate portfolio performance with SPY changes
+    position <ticker>   Analyze a specific position group
+    portfolio list      List all positions in the portfolio
+    portfolio summary   Show a summary of the portfolio
+    portfolio load      Load a portfolio from a CSV file
+    exit                Exit the application
+"""
+
+import sys
+from pathlib import Path
+
+# Add the src directory to the Python path
+sys.path.append(str(Path(__file__).parent.parent))
+
+from src.focli.shell import main
+
+if __name__ == "__main__":
+    main()

src/focli/__init__.py

@@ -0,0 +1,8 @@
+"""
+Folio CLI - Interactive command-line interface for Folio portfolio management.
+
+This package provides an interactive shell for running portfolio simulations,
+analyzing positions, and exploring investment scenarios.
+"""
+
+__version__ = "0.1.0"

src/focli/commands/__init__.py

@@ -0,0 +1,95 @@
+"""
+Command registry and execution for the Folio CLI.
+
+This module provides a central registry for all commands and handles command execution.
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+# Import command modules
+from .help import help_command
+from .portfolio import portfolio_command
+from .position import position_command
+from .simulate import simulate_command
+
+# Command registry
+_COMMANDS = {}
+
+
+def register_command(
+    name: str, handler: Callable, help_text: str, subcommands: list[str] | None = None
+):
+    """Register a command with the command registry.
+
+    Args:
+        name: Command name
+        handler: Function that handles the command
+        help_text: Help text for the command
+        subcommands: List of subcommands (if any)
+    """
+    _COMMANDS[name] = {
+        "handler": handler,
+        "help": help_text,
+        "subcommands": subcommands,
+    }
+
+
+def get_command_registry():
+    """Get the command registry.
+
+    Returns:
+        Dictionary of registered commands
+    """
+    return _COMMANDS
+
+
+def execute_command(command_line: str, state: dict[str, Any], console):
+    """Execute a command from the command line.
+
+    Args:
+        command_line: Full command line to execute
+        state: Application state dictionary
+        console: Rich console for output
+    """
+    # Parse the command line
+    parts = command_line.strip().split()
+    if not parts:
+        return
+
+    command = parts[0].lower()
+    args = parts[1:]
+
+    # Check if the command exists
+    if command not in _COMMANDS:
+        console.print(f"[bold red]Unknown command:[/bold red] {command}")
+        console.print("Type 'help' to see available commands.")
+        return
+
+    # Execute the command
+    try:
+        _COMMANDS[command]["handler"](args, state, console)
+    except Exception as e:
+        console.print(
+            f"[bold red]Error executing command '{command}':[/bold red] {e!s}"
+        )
+
+
+# Import command modules
+
+# Register commands
+register_command("help", help_command, "Show help information")
+register_command(
+    "simulate",
+    simulate_command,
+    "Simulate portfolio performance with SPY changes",
+    ["spy", "scenario"],
+)
+register_command("position", position_command, "Analyze a specific position group")
+register_command(
+    "portfolio",
+    portfolio_command,
+    "View and analyze portfolio",
+    ["list", "summary", "load"],
+)
+register_command("exit", lambda *args: None, "Exit the application")

src/focli/commands/help.py

@@ -0,0 +1,117 @@
+"""
+Help command for the Folio CLI.
+
+This module provides the help command for displaying information about available commands.
+"""
+
+from typing import Any
+
+from rich.box import ROUNDED
+from rich.table import Table
+
+
+def help_command(args: list[str], state: dict[str, Any], console):  # noqa: ARG001
+    """Show help information.
+
+    Args:
+        args: Command arguments
+        state: Application state
+        console: Rich console for output
+    """
+    from src.focli.commands import get_command_registry
+
+    # Get the command registry
+    commands = get_command_registry()
+
+    # Check if we're showing help for a specific command
+    if args and args[0] in commands:
+        command = args[0]
+        command_info = commands[command]
+
+        console.print(f"\n[bold]Help for command:[/bold] [cyan]{command}[/cyan]")
+        console.print(f"\n{command_info['help']}\n")
+
+        # Show subcommands if available
+        if command_info.get("subcommands"):
+            console.print("[bold]Subcommands:[/bold]")
+            for subcommand in command_info["subcommands"]:
+                console.print(f"  [cyan]{subcommand}[/cyan]")
+            console.print("")
+
+        # Show usage examples based on the command
+        console.print("[bold]Usage examples:[/bold]")
+
+        if command == "simulate":
+            console.print(
+                "  [green]simulate spy[/green] - Run a simulation with default parameters"
+            )
+            console.print(
+                "  [green]simulate spy --range 10 --steps 21[/green] - Run a simulation with ±10% range and 21 steps"
+            )
+            console.print(
+                "  [green]simulate spy --focus SPY,AAPL[/green] - Run a simulation focusing on specific tickers"
+            )
+            console.print(
+                "  [green]simulate spy --detailed[/green] - Run a simulation with detailed position analysis"
+            )
+
+        elif command == "position":
+            console.print(
+                "  [green]position SPY[/green] - Show details for the SPY position"
+            )
+            console.print(
+                "  [green]position AAPL --detailed[/green] - Show detailed information for the AAPL position"
+            )
+
+        elif command == "portfolio":
+            console.print(
+                "  [green]portfolio summary[/green] - Show a summary of the portfolio"
+            )
+            console.print(
+                "  [green]portfolio load path/to/portfolio.csv[/green] - Load a portfolio from a CSV file"
+            )
+            console.print(
+                "  [green]portfolio list[/green] - List all positions in the portfolio"
+            )
+
+        elif command == "help":
+            console.print("  [green]help[/green] - Show this help message")
+            console.print(
+                "  [green]help simulate[/green] - Show help for the simulate command"
+            )
+
+        elif command == "exit":
+            console.print("  [green]exit[/green] - Exit the application")
+
+        console.print("")
+
+    else:
+        # Show general help
+        console.print("\n[bold cyan]Folio CLI Help[/bold cyan]")
+        console.print("\nAvailable commands:\n")
+
+        # Create a table of commands
+        table = Table(box=ROUNDED)
+        table.add_column("Command", style="cyan")
+        table.add_column("Description", style="green")
+        table.add_column("Subcommands", style="yellow")
+
+        # Add rows for each command
+        for name, info in commands.items():
+            subcommands = (
+                ", ".join(info.get("subcommands", []))
+                if info.get("subcommands")
+                else ""
+            )
+            table.add_row(name, info["help"], subcommands)
+
+        console.print(table)
+
+        # Show general usage
+        console.print("\n[bold]General usage:[/bold]")
+        console.print("  Type a command followed by any arguments or options.")
+        console.print(
+            "  Use [cyan]help <command>[/cyan] to get help for a specific command."
+        )
+        console.print("  Use [cyan]exit[/cyan] to exit the application.")
+        console.print("")

src/focli/commands/portfolio.py

@@ -0,0 +1,137 @@
+"""
+Portfolio management commands for the Folio CLI.
+
+This module provides commands for managing and analyzing portfolios.
+"""
+
+from typing import Any
+
+from rich.box import ROUNDED
+from rich.table import Table
+
+from src.focli.formatters import display_portfolio_summary, format_currency
+from src.focli.utils import load_portfolio
+
+
+def portfolio_command(args: list[str], state: dict[str, Any], console):
+    """View and analyze portfolio.
+
+    Args:
+        args: Command arguments
+        state: Application state
+        console: Rich console for output
+    """
+    # Check if we have a subcommand
+    if not args:
+        console.print(
+            "[bold yellow]Usage:[/bold yellow] portfolio <subcommand> [options]"
+        )
+        console.print("Available subcommands: list, summary, load")
+        console.print("Type 'help portfolio' for more information.")
+        return
+
+    subcommand = args[0].lower()
+    subcommand_args = args[1:]
+
+    if subcommand == "list":
+        portfolio_list(subcommand_args, state, console)
+    elif subcommand == "summary":
+        portfolio_summary(subcommand_args, state, console)
+    elif subcommand == "load":
+        portfolio_load(subcommand_args, state, console)
+    else:
+        console.print(f"[bold red]Unknown subcommand:[/bold red] {subcommand}")
+        console.print("Available subcommands: list, summary, load")
+
+
+def portfolio_list(args: list[str], state: dict[str, Any], console):  # noqa: ARG001
+    """List all positions in the portfolio.
+
+    Args:
+        args: Command arguments
+        state: Application state
+        console: Rich console for output
+    """
+    # Check if a portfolio is loaded
+    if not state.get("portfolio_groups"):
+        console.print("[bold red]Error:[/bold red] No portfolio loaded.")
+        console.print("Use 'portfolio load <path>' to load a portfolio.")
+        return
+
+    # Create a table of positions
+    table = Table(title="Portfolio Positions", box=ROUNDED)
+    table.add_column("Ticker", style="cyan")
+    table.add_column("Beta", style="yellow", justify="right")
+    table.add_column("Net Exposure", style="green", justify="right")
+    table.add_column("Stock Value", style="green", justify="right")
+    table.add_column("Option Value", style="green", justify="right")
+    table.add_column("Options", style="magenta", justify="right")
+
+    # Add rows for each position
+    for group in state["portfolio_groups"]:
+        stock_value = group.stock_position.market_value if group.stock_position else 0
+        option_value = (
+            sum(op.market_value for op in group.option_positions)
+            if group.option_positions
+            else 0
+        )
+        option_count = len(group.option_positions) if group.option_positions else 0
+
+        table.add_row(
+            group.ticker,
+            f"{group.beta:.2f}",
+            format_currency(group.net_exposure),
+            format_currency(stock_value),
+            format_currency(option_value),
+            f"{option_count}",
+        )
+
+    console.print(table)
+
+
+def portfolio_summary(args: list[str], state: dict[str, Any], console):  # noqa: ARG001
+    """Show a summary of the portfolio.
+
+    Args:
+        args: Command arguments
+        state: Application state
+        console: Rich console for output
+    """
+    # Check if a portfolio is loaded
+    if not state.get("portfolio_summary"):
+        console.print("[bold red]Error:[/bold red] No portfolio loaded.")
+        console.print("Use 'portfolio load <path>' to load a portfolio.")
+        return
+
+    # Display the portfolio summary
+    display_portfolio_summary(state["portfolio_summary"], console)
+
+
+def portfolio_load(args: list[str], state: dict[str, Any], console):
+    """Load a portfolio from a CSV file.
+
+    Args:
+        args: Command arguments
+        state: Application state
+        console: Rich console for output
+    """
+    # Check if we have a path
+    if not args:
+        console.print("[bold yellow]Usage:[/bold yellow] portfolio load <path>")
+        console.print("Type 'help portfolio load' for more information.")
+        return
+
+    # Get the path
+    path = args[0]
+
+    try:
+        # Load the portfolio
+        load_portfolio(path, state, console)
+
+    except FileNotFoundError as e:
+        console.print(f"[bold red]Error:[/bold red] {e!s}")
+    except Exception as e:
+        console.print(f"[bold red]Error loading portfolio:[/bold red] {e!s}")
+        import traceback
+
+        console.print(traceback.format_exc())

src/focli/commands/position.py

@@ -0,0 +1,68 @@
+"""
+Position analysis commands for the Folio CLI.
+
+This module provides commands for analyzing specific position groups.
+"""
+
+from typing import Any
+
+from src.focli.formatters import display_position_details
+from src.focli.utils import find_position_group, parse_args
+
+
+def position_command(args: list[str], state: dict[str, Any], console):
+    """Analyze a specific position group.
+
+    Args:
+        args: Command arguments
+        state: Application state
+        console: Rich console for output
+    """
+    # Check if a portfolio is loaded
+    if not state.get("portfolio_groups"):
+        console.print("[bold red]Error:[/bold red] No portfolio loaded.")
+        console.print("Use 'portfolio load <path>' to load a portfolio.")
+        return
+
+    # Check if we have a ticker
+    if not args:
+        console.print("[bold yellow]Usage:[/bold yellow] position <ticker> [options]")
+        console.print("Type 'help position' for more information.")
+        return
+
+    # Get the ticker
+    ticker = args[0].upper()
+    position_args = args[1:]
+
+    # Define argument specifications
+    arg_specs = {
+        'detailed': {
+            'type': bool,
+            'default': True,
+            'help': 'Show detailed information',
+            'aliases': ['-d', '--detailed', '--no-detailed']
+        }
+    }
+
+    try:
+        # Parse arguments
+        parsed_args = parse_args(position_args, arg_specs)
+
+        detailed = parsed_args['detailed']
+
+        # Find the position group
+        group = find_position_group(ticker, state["portfolio_groups"])
+
+        if not group:
+            console.print(f"[bold red]Position not found:[/bold red] {ticker}")
+            return
+
+        # Display detailed position information
+        display_position_details(group, detailed, console)
+
+    except ValueError as e:
+        console.print(f"[bold red]Error:[/bold red] {e!s}")
+    except Exception as e:
+        console.print(f"[bold red]Error analyzing position:[/bold red] {e!s}")
+        import traceback
+        console.print(traceback.format_exc())

src/focli/commands/simulate.py

@@ -0,0 +1,120 @@
+"""
+Simulation commands for the Folio CLI.
+
+This module provides commands for simulating portfolio performance under different scenarios.
+"""
+
+from typing import Any
+
+from src.focli.formatters import display_simulation_results
+from src.focli.utils import generate_spy_changes, parse_args
+from src.folio.simulator import simulate_portfolio_with_spy_changes
+
+
+def simulate_command(args: list[str], state: dict[str, Any], console):
+    """Simulate portfolio performance with SPY changes.
+
+    Args:
+        args: Command arguments
+        state: Application state
+        console: Rich console for output
+    """
+    # Check if a portfolio is loaded
+    if not state.get("portfolio_groups"):
+        console.print("[bold red]Error:[/bold red] No portfolio loaded.")
+        console.print("Use 'portfolio load <path>' to load a portfolio.")
+        return
+
+    # Check if we have a subcommand
+    if not args:
+        console.print("[bold yellow]Usage:[/bold yellow] simulate <subcommand> [options]")
+        console.print("Available subcommands: spy, scenario")
+        console.print("Type 'help simulate' for more information.")
+        return
+
+    subcommand = args[0].lower()
+    subcommand_args = args[1:]
+
+    if subcommand == "spy":
+        simulate_spy(subcommand_args, state, console)
+    elif subcommand == "scenario":
+        console.print("[bold yellow]Note:[/bold yellow] Scenario simulation is not yet implemented.")
+    else:
+        console.print(f"[bold red]Unknown subcommand:[/bold red] {subcommand}")
+        console.print("Available subcommands: spy, scenario")
+
+def simulate_spy(args: list[str], state: dict[str, Any], console):
+    """Simulate portfolio performance with SPY changes.
+
+    Args:
+        args: Command arguments
+        state: Application state
+        console: Rich console for output
+    """
+    # Define argument specifications
+    arg_specs = {
+        'range': {
+            'type': float,
+            'default': 20.0,
+            'help': 'SPY change range in percent',
+            'aliases': ['-r', '--range']
+        },
+        'steps': {
+            'type': int,
+            'default': 13,
+            'help': 'Number of steps in the simulation',
+            'aliases': ['-s', '--steps']
+        },
+        'focus': {
+            'type': str,
+            'default': None,
+            'help': 'Comma-separated list of tickers to focus on',
+            'aliases': ['-f', '--focus']
+        },
+        'detailed': {
+            'type': bool,
+            'default': False,
+            'help': 'Show detailed analysis for all positions',
+            'aliases': ['-d', '--detailed']
+        }
+    }
+
+    try:
+        # Parse arguments
+        parsed_args = parse_args(args, arg_specs)
+
+        range_pct = parsed_args['range']
+        steps = parsed_args['steps']
+        focus = parsed_args['focus']
+        detailed = parsed_args['detailed']
+
+        # Parse focus tickers if provided
+        focus_tickers = None
+        if focus:
+            focus_tickers = [ticker.strip().upper() for ticker in focus.split(",")]
+
+        # Generate SPY changes
+        spy_changes = generate_spy_changes(range_pct, steps)
+
+        # Run the simulation
+        console.print(f"[bold]Running simulation with range ±{range_pct}% and {steps} steps...[/bold]")
+
+        results = simulate_portfolio_with_spy_changes(
+            portfolio_groups=state["portfolio_groups"],
+            spy_changes=spy_changes,
+            cash_like_positions=state["portfolio_summary"].cash_like_positions,
+            pending_activity_value=state["portfolio_summary"].pending_activity_value,
+        )
+
+        # Store results for future reference
+        state["last_simulation"] = results
+
+        # Display the results
+        display_simulation_results(results, detailed, focus_tickers, console)
+
+    except ValueError as e:
+        console.print(f"[bold red]Error:[/bold red] {e!s}")
+    except Exception as e:
+        console.print(f"[bold red]Error running simulation:[/bold red] {e!s}")
+        import traceback
+        console.print(traceback.format_exc())

src/focli/formatters.py

@@ -0,0 +1,278 @@
+"""
+Output formatting utilities for the Folio CLI.
+
+This module provides functions for formatting CLI output using Rich.
+"""
+
+from rich.box import ROUNDED
+from rich.console import Console
+from rich.table import Table
+
+from src.folio.formatting import format_currency
+
+
+def display_simulation_results(results, detailed=False, focus_tickers=None, console=None):
+    """Display simulation results using Rich.
+
+    Args:
+        results: Simulation results from simulate_portfolio_with_spy_changes
+        detailed: Whether to show detailed position analysis
+        focus_tickers: List of tickers to focus on
+        console: Rich console for output
+    """
+    if console is None:
+        console = Console()
+
+    # Get the current value (at 0% SPY change)
+    current_value = results["current_value"]
+
+    # Get min and max values
+    min_value = min(results["portfolio_values"])
+    max_value = max(results["portfolio_values"])
+    min_index = results["portfolio_values"].index(min_value)
+    max_index = results["portfolio_values"].index(max_value)
+    min_spy_change = results["spy_changes"][min_index] * 100  # Convert to percentage
+    max_spy_change = results["spy_changes"][max_index] * 100  # Convert to percentage
+
+    # Create a summary table
+    console.print("\n[bold cyan]Portfolio Simulation Results[/bold cyan]")
+
+    summary_table = Table(title="Portfolio Summary", box=ROUNDED)
+    summary_table.add_column("Metric", style="cyan")
+    summary_table.add_column("Value", style="green")
+    summary_table.add_column("SPY Change", style="yellow")
+
+    summary_table.add_row("Current Value", f"${current_value:,.2f}", "0.0%")
+    summary_table.add_row("Minimum Value", f"${min_value:,.2f}", f"{min_spy_change:.1f}%")
+    summary_table.add_row("Maximum Value", f"${max_value:,.2f}", f"{max_spy_change:.1f}%")
+
+    console.print(summary_table)
+
+    # Create a detailed table with all values
+    value_table = Table(title="Portfolio Values at Different SPY Changes", box=ROUNDED)
+    value_table.add_column("SPY Change", style="yellow")
+    value_table.add_column("Portfolio Value", style="green")
+    value_table.add_column("Change", style="cyan")
+    value_table.add_column("% Change", style="magenta")
+
+    for i, spy_change in enumerate(results["spy_changes"]):
+        portfolio_value = results["portfolio_values"][i]
+        value_change = portfolio_value - current_value
+        pct_change = (value_change / current_value) * 100 if current_value != 0 else 0
+
+        # Format the change with color based on positive/negative
+        change_str = f"${value_change:+,.2f}"
+        pct_change_str = f"{pct_change:+.2f}%"
+
+        value_table.add_row(
+            f"{spy_change * 100:.1f}%",
+            f"${portfolio_value:,.2f}",
+            change_str,
+            pct_change_str,
+        )
+
+    console.print(value_table)
+
+    # If detailed is True, show position-level analysis
+    if detailed:
+        display_position_analysis(results, focus_tickers, console)
+
+def display_position_analysis(results, focus_tickers=None, console=None):
+    """Display position-level analysis.
+
+    Args:
+        results: Simulation results from simulate_portfolio_with_spy_changes
+        focus_tickers: List of tickers to focus on
+        console: Rich console for output
+    """
+    if console is None:
+        console = Console()
+
+    # Get position details
+    position_details = results.get("position_details", {})
+    position_changes = results.get("position_changes", {})
+
+    # Filter positions if focus_tickers is provided
+    if focus_tickers:
+        filtered_details = {}
+        filtered_changes = {}
+        for ticker in focus_tickers:
+            if ticker in position_details:
+                filtered_details[ticker] = position_details[ticker]
+            if ticker in position_changes:
+                filtered_changes[ticker] = position_changes[ticker]
+        position_details = filtered_details
+        position_changes = filtered_changes
+
+    # Display position details
+    console.print("\n[bold cyan]Position Analysis[/bold cyan]")
+
+    for ticker, details in position_details.items():
+        # Create a panel for each position
+        position_table = Table(title=f"{ticker} Details", box=ROUNDED)
+        position_table.add_column("Metric", style="cyan")
+        position_table.add_column("Value", style="green")
+
+        # Add basic position details
+        position_table.add_row("Beta", f"{details.get('beta', 0):.2f}")
+        position_table.add_row("Current Value", format_currency(details.get('current_value', 0)))
+        position_table.add_row("Stock Value", format_currency(details.get('stock_value', 0)))
+        position_table.add_row("Option Value", format_currency(details.get('option_value', 0)))
+
+        # Add stock details if available
+        if details.get('has_stock'):
+            position_table.add_row("Stock Quantity", f"{details.get('stock_quantity', 0)}")
+            position_table.add_row("Stock Price", format_currency(details.get('stock_price', 0)))
+
+        # Add option details if available
+        if details.get('has_options'):
+            position_table.add_row("Option Count", f"{details.get('option_count', 0)}")
+
+        console.print(position_table)
+
+        # If we have change data, show it
+        if ticker in position_changes:
+            changes = position_changes[ticker]
+
+            # Create a table for position changes
+            changes_table = Table(title=f"{ticker} Changes with SPY", box=ROUNDED)
+            changes_table.add_column("SPY Change", style="yellow")
+            changes_table.add_column("Position Value", style="green")
+            changes_table.add_column("Change", style="cyan")
+            changes_table.add_column("% Change", style="magenta")
+
+            for i, spy_change in enumerate(results["spy_changes"]):
+                if i < len(changes["values"]):
+                    value = changes["values"][i]
+                    change = changes["changes"][i]
+                    pct_change = changes["pct_changes"][i]
+
+                    changes_table.add_row(
+                        f"{spy_change * 100:.1f}%",
+                        format_currency(value),
+                        f"{format_currency(change, include_sign=True)}",
+                        f"{pct_change:+.2f}%",
+                    )
+
+            console.print(changes_table)
+
+def display_position_details(group, detailed=True, console=None):
+    """Display detailed information about a position group.
+
+    Args:
+        group: PortfolioGroup to display
+        detailed: Whether to show detailed option information
+        console: Rich console for output
+    """
+    if console is None:
+        console = Console()
+
+    ticker = group.ticker
+    console.print(f"\n[bold cyan]Position Details: {ticker}[/bold cyan]")
+
+    # Create a summary table
+    summary_table = Table(title=f"{ticker} Summary", box=ROUNDED)
+    summary_table.add_column("Metric", style="cyan")
+    summary_table.add_column("Value", style="green")
+
+    # Add basic position details
+    summary_table.add_row("Beta", f"{group.beta:.2f}")
+    summary_table.add_row("Net Exposure", format_currency(group.net_exposure))
+    summary_table.add_row("Beta-Adjusted Exposure", format_currency(group.beta_adjusted_exposure))
+
+    # Add stock details if available
+    if group.stock_position:
+        stock = group.stock_position
+        summary_table.add_row("Stock Quantity", f"{stock.quantity}")
+        summary_table.add_row("Stock Price", format_currency(stock.price))
+        summary_table.add_row("Stock Market Value", format_currency(stock.market_value))
+
+    # Add option summary if available
+    if group.option_positions:
+        summary_table.add_row("Option Count", f"{len(group.option_positions)}")
+        summary_table.add_row("Call Options", f"{group.call_count}")
+        summary_table.add_row("Put Options", f"{group.put_count}")
+        summary_table.add_row("Total Delta Exposure", format_currency(group.total_delta_exposure))
+
+    console.print(summary_table)
+
+    # If detailed and we have options, show option details
+    if detailed and group.option_positions:
+        options_table = Table(title=f"{ticker} Option Positions", box=ROUNDED)
+        options_table.add_column("Type", style="cyan")
+        options_table.add_column("Strike", style="green", justify="right")
+        options_table.add_column("Expiry", style="yellow")
+        options_table.add_column("Quantity", style="green", justify="right")
+        options_table.add_column("Delta", style="magenta", justify="right")
+        options_table.add_column("Value", style="green", justify="right")
+
+        for option in group.option_positions:
+            options_table.add_row(
+                option.option_type,
+                format_currency(option.strike),
+                option.expiry,
+                f"{option.quantity}",
+                f"{option.delta:.2f}",
+                format_currency(option.market_value),
+            )
+
+        console.print(options_table)
+
+def display_portfolio_summary(summary, console=None):
+    """Display a summary of the portfolio.
+
+    Args:
+        summary: PortfolioSummary object
+        console: Rich console for output
+    """
+    if console is None:
+        console = Console()
+
+    console.print("\n[bold cyan]Portfolio Summary[/bold cyan]")
+
+    # Create a summary table
+    summary_table = Table(title="Portfolio Overview", box=ROUNDED)
+    summary_table.add_column("Metric", style="cyan")
+    summary_table.add_column("Value", style="green")
+
+    # Add portfolio metrics
+    summary_table.add_row("Total Value", format_currency(summary.portfolio_estimate_value))
+    summary_table.add_row("Stock Value", format_currency(summary.stock_value))
+    summary_table.add_row("Option Value", format_currency(summary.option_value))
+    summary_table.add_row("Cash Value", format_currency(summary.cash_like_value))
+    summary_table.add_row("Portfolio Beta", f"{summary.portfolio_beta:.2f}")
+    summary_table.add_row("Net Market Exposure", format_currency(summary.net_market_exposure))
+
+    console.print(summary_table)
+
+    # Create an exposure table
+    exposure_table = Table(title="Exposure Breakdown", box=ROUNDED)
+    exposure_table.add_column("Category", style="cyan")
+    exposure_table.add_column("Value", style="green")
+    exposure_table.add_column("% of Portfolio", style="magenta")
+
+    # Add exposure metrics
+    total_value = summary.portfolio_estimate_value
+    if total_value > 0:
+        exposure_table.add_row(
+            "Long Exposure",
+            format_currency(summary.long_exposure.total_value),
+            f"{summary.long_exposure.total_value / total_value * 100:.1f}%"
+        )
+        exposure_table.add_row(
+            "Short Exposure",
+            format_currency(summary.short_exposure.total_value),
+            f"{summary.short_exposure.total_value / total_value * 100:.1f}%"
+        )
+        exposure_table.add_row(
+            "Options Exposure",
+            format_currency(summary.options_exposure.total_value),
+            f"{summary.options_exposure.total_value / total_value * 100:.1f}%"
+        )
+        exposure_table.add_row(
+            "Cash",
+            format_currency(summary.cash_like_value),
+            f"{summary.cash_percentage * 100:.1f}%"
+        )
+
+    console.print(exposure_table)

src/focli/shell.py

@@ -0,0 +1,112 @@
+"""
+Interactive shell for the Folio CLI.
+
+This module provides the main entry point for the Folio CLI interactive shell.
+"""
+
+import os
+
+from prompt_toolkit import PromptSession
+from prompt_toolkit.completion import NestedCompleter
+from prompt_toolkit.history import FileHistory
+from prompt_toolkit.shortcuts import confirm
+from rich.console import Console
+
+from src.focli.commands import execute_command, get_command_registry
+from src.focli.utils import load_portfolio
+
+
+def create_completer():
+    """Create a nested completer for command auto-completion.
+
+    Returns:
+        NestedCompleter for command auto-completion
+    """
+    # Build a nested completer from the command registry
+    commands = get_command_registry()
+
+    # Create completion dictionary with subcommands and parameters
+    completion_dict = {}
+    for cmd_name, cmd_info in commands.items():
+        if cmd_info.get("subcommands"):
+            completion_dict[cmd_name] = {
+                subcmd: None for subcmd in cmd_info["subcommands"]
+            }
+        else:
+            completion_dict[cmd_name] = None
+
+    return NestedCompleter.from_nested_dict(completion_dict)
+
+def main():
+    """Main entry point for the Folio CLI."""
+    console = Console()
+    console.print("[bold cyan]Folio Interactive Shell[/bold cyan]")
+    console.print("Type 'help' for available commands.")
+
+    # Create history file in user's home directory
+    history_file = os.path.expanduser("~/.folio_history")
+
+    # Create session with auto-completion and history
+    session = PromptSession(
+        completer=create_completer(),
+        history=FileHistory(history_file)
+    )
+
+    # Initialize application state
+    state = {
+        "portfolio_groups": None,
+        "portfolio_summary": None,
+        "last_simulation": None,
+        "loaded_portfolio": None,
+    }
+
+    # Try to load default portfolio
+    default_portfolio = "private-data/portfolio-private.csv"
+    try:
+        load_portfolio(default_portfolio, state, console)
+    except Exception as e:
+        console.print(f"[yellow]Could not load default portfolio: {e}[/yellow]")
+        console.print("[yellow]Use 'portfolio load <path>' to load a portfolio.[/yellow]")
+
+    # Main REPL loop
+    while True:
+        try:
+            # Get user input
+            text = session.prompt("folio> ")
+
+            if not text.strip():
+                continue
+
+            # Handle exit command directly
+            if text.strip().lower() == "exit":
+                if confirm_exit():
+                    break
+                continue
+
+            # Process the command
+            execute_command(text, state, console)
+
+        except KeyboardInterrupt:
+            # Handle Ctrl+C
+            console.print("\n[yellow]Use 'exit' to exit the application.[/yellow]")
+            continue
+        except EOFError:
+            # Handle Ctrl+D
+            console.print("\nGoodbye!")
+            break
+        except Exception as e:
+            # Handle unexpected errors
+            console.print(f"[bold red]Error:[/bold red] {e!s}")
+
+    console.print("Goodbye!")
+
+def confirm_exit():
+    """Confirm exit with the user.
+
+    Returns:
+        True if the user confirms, False otherwise
+    """
+    return confirm("Are you sure you want to exit?")
+
+if __name__ == "__main__":
+    main()

src/focli/utils.py

@@ -0,0 +1,185 @@
+"""
+Utility functions for the Folio CLI.
+
+This module provides helper functions used across the CLI.
+"""
+
+import os
+from pathlib import Path
+
+import pandas as pd
+
+from src.folio.portfolio import process_portfolio_data
+
+
+def load_portfolio(path, state, console=None):
+    """Load a portfolio from a CSV file.
+
+    Args:
+        path: Path to the portfolio CSV file
+        state: Application state dictionary
+        console: Rich console for output
+
+    Returns:
+        Tuple of (groups, summary)
+    """
+    from rich.console import Console
+
+    if console is None:
+        console = Console()
+
+    # Resolve the path
+    if not os.path.isabs(path):
+        # Try relative to current directory
+        resolved_path = Path(os.getcwd()) / path
+        if not resolved_path.exists():
+            # Try relative to project root
+            project_root = Path(__file__).parent.parent.parent
+            resolved_path = project_root / path
+    else:
+        resolved_path = Path(path)
+
+    # Check if the file exists
+    if not resolved_path.exists():
+        raise FileNotFoundError(f"Portfolio file not found: {path}")
+
+    # Load the portfolio
+    console.print(f"Loading portfolio from [cyan]{resolved_path}[/cyan]...")
+
+    try:
+        df = pd.read_csv(resolved_path)
+        groups, summary, _ = process_portfolio_data(df, update_prices=True)
+
+        # Update the state
+        state["portfolio_groups"] = groups
+        state["portfolio_summary"] = summary
+        state["loaded_portfolio"] = str(resolved_path)
+
+        console.print(
+            f"Loaded portfolio with [green]{len(groups)}[/green] position groups."
+        )
+        return groups, summary
+    except Exception as e:
+        raise RuntimeError(f"Error loading portfolio: {e!s}") from e
+
+
+def generate_spy_changes(range_pct, steps):
+    """Generate a list of SPY changes for simulation.
+
+    Args:
+        range_pct: Range of SPY changes in percent (e.g., 20.0 for ±20%)
+        steps: Number of steps in the simulation
+
+    Returns:
+        List of SPY changes as decimals (e.g., [-0.2, -0.1, 0.0, 0.1, 0.2])
+    """
+    # Calculate the step size
+    step_size = (2 * range_pct) / (steps - 1) if steps > 1 else 0
+
+    # Generate the SPY changes
+    spy_changes = [-range_pct + i * step_size for i in range(steps)]
+
+    # Ensure we have a zero point
+    if 0.0 not in spy_changes and steps > 2:
+        # Find the closest point to zero and replace it with zero
+        closest_to_zero = min(spy_changes, key=lambda x: abs(x))
+        zero_index = spy_changes.index(closest_to_zero)
+        spy_changes[zero_index] = 0.0
+
+    # Convert to percentages
+    spy_changes = [change / 100.0 for change in spy_changes]
+
+    return spy_changes
+
+
+def find_position_group(ticker, portfolio_groups):
+    """Find a position group by ticker.
+
+    Args:
+        ticker: Ticker symbol to find
+        portfolio_groups: List of portfolio groups
+
+    Returns:
+        PortfolioGroup if found, None otherwise
+    """
+    if not portfolio_groups:
+        return None
+
+    # Normalize the ticker
+    ticker = ticker.upper()
+
+    # Find the group
+    for group in portfolio_groups:
+        if group.ticker == ticker:
+            return group
+
+    return None
+
+
+def parse_args(args, arg_specs):
+    """Parse command arguments according to specifications.
+
+    Args:
+        args: List of argument strings
+        arg_specs: Dictionary mapping argument names to specifications
+            Each specification is a dictionary with:
+                - type: Type to convert to (float, int, str, bool)
+                - default: Default value
+                - help: Help text
+                - aliases: List of aliases (e.g., ['-r', '--range'])
+
+    Returns:
+        Dictionary of parsed arguments
+    """
+    # Initialize with default values
+    result = {name: spec.get("default") for name, spec in arg_specs.items()}
+
+    # Parse arguments
+    i = 0
+    while i < len(args):
+        arg = args[i]
+
+        # Check if this is a flag/option
+        if arg.startswith("-"):
+            # Find the matching argument
+            found = False
+            for name, spec in arg_specs.items():
+                aliases = spec.get("aliases", [])
+                if arg in aliases:
+                    # This is a match
+                    found = True
+
+                    # Handle boolean flags
+                    if spec.get("type") is bool:
+                        result[name] = True
+                        i += 1
+                        break
+
+                    # Handle value arguments
+                    if i + 1 < len(args):
+                        try:
+                            # Convert to the specified type
+                            value = args[i + 1]
+                            if spec.get("type") is float:
+                                result[name] = float(value)
+                            elif spec.get("type") is int:
+                                result[name] = int(value)
+                            else:
+                                result[name] = value
+                            i += 2
+                            break
+                        except ValueError as ve:
+                            raise ValueError(
+                                f"Invalid value for {arg}: {args[i + 1]}"
+                            ) from ve
+                    else:
+                        raise ValueError(f"Missing value for {arg}")
+
+            if not found:
+                raise ValueError(f"Unknown argument: {arg}")
+        else:
+            # This is a positional argument
+            # For now, we'll just skip it
+            i += 1
+
+    return result