CLI Usage Examples
==================

This section provides comprehensive examples of how to use the Portfolio Toolkit command-line interface (CLI). The CLI has been built using the Click framework for an intuitive and user-friendly experience.

Installation
------------

Install the package using pip:

.. code-block:: bash

   pip install portfolio-toolkit

After installation, you can access the CLI directly:

.. code-block:: bash

   # View available commands
   portfolio-toolkit --help

   # Check version
   portfolio-toolkit --version

Creating Your Portfolio File
----------------------------

Before using the CLI commands, you need to create a portfolio JSON file that describes your investments. For detailed information about the portfolio file format, see :doc:`../user_guide/portfolio_format`.

Here's a basic example of a portfolio file:

.. code-block:: json

   {
     "name": "My Investment Portfolio",
     "currency": "USD",
     "account": [
       {
         "date": "2023-01-15",
         "type": "deposit",
         "amount": 10000,
         "currency": "USD"
       }
     ],
     "assets": [
       {
         "ticker": "AAPL",
         "transactions": [
           {
             "date": "2023-01-20", 
             "type": "buy",
             "quantity": 50,
             "price": 150.25,
             "currency": "USD"
           }
         ]
       },
       {
         "ticker": "MSFT",
         "transactions": [
           {
             "date": "2023-02-10",
             "type": "buy", 
             "quantity": 30,
             "price": 280.50,
             "currency": "USD"
           }
         ]
       }
     ]
   }

Save this as ``portfolio.json`` to use with the examples below.

Available Commands
------------------

The CLI is organized around portfolio analysis commands. Here are the main command groups and their usage:

Portfolio Transactions
~~~~~~~~~~~~~~~~~~~~~~

List and export transaction data from your portfolio.

**List asset transactions:**

.. code-block:: bash

   # Show all asset transactions
   portfolio-toolkit portfolio transactions portfolio.json

   # Export asset transactions to CSV
   portfolio-toolkit portfolio transactions portfolio.json --output transactions.csv

**List cash transactions:**

.. code-block:: bash

   # Show cash account transactions (deposits, withdrawals)
   portfolio-toolkit portfolio transactions portfolio.json --cash

   # Export cash transactions to CSV
   portfolio-toolkit portfolio transactions portfolio.json --cash --output cash_transactions.csv

Example output:

.. code-block:: text

   📊 Portfolio asset transactions
   ============================================================
   ticker    date        type  quantity     price currency
   AAPL   2023-01-20     buy      50.0    150.25      USD
   MSFT   2023-02-10     buy      30.0    280.50      USD

Portfolio Positions
~~~~~~~~~~~~~~~~~~~

View current portfolio positions and create visualizations.

**Show current positions:**

.. code-block:: bash

   # Show positions for a specific date
   portfolio-toolkit portfolio positions portfolio.json 2025-07-30

**Position visualizations:**

.. code-block:: bash

   # Create a pie chart of current positions
   portfolio-toolkit portfolio positions portfolio.json 2025-07-30 --plot

   # Group positions by country
   portfolio-toolkit portfolio positions portfolio.json 2025-07-30 --country

   # Group positions by sector
   portfolio-toolkit portfolio positions portfolio.json 2025-07-30 --sector

Example output:

.. code-block:: text

   📊 Portfolio Positions as of 2025-07-30
   ============================================================
   Ticker  Quantity  Current Price  Market Value  % of Portfolio
   AAPL         50         208.62      10,431.00           55.2%
   MSFT         30         445.91      13,377.30           44.8%
   ============================================================
   Total Portfolio Value: $23,808.30

Performance Analysis
~~~~~~~~~~~~~~~~~~~~

Analyze portfolio performance across different time periods.

**Basic performance analysis:**

.. code-block:: bash

   # Compare returns over the last 4 weeks (default)
   portfolio-toolkit portfolio performance portfolio.json

**Customized time periods:**

.. code-block:: bash

   # Last 4 weeks (explicit)
   portfolio-toolkit portfolio performance portfolio.json --period-type weeks -n 4

   # Last 6 months
   portfolio-toolkit portfolio performance portfolio.json --period-type months -n 6

   # Last 6 quarters
   portfolio-toolkit portfolio performance portfolio.json --period-type quarters -n 6

**Export performance data:**

.. code-block:: bash

   # Export returns to CSV file
   portfolio-toolkit portfolio performance portfolio.json --output performance.csv

**Display options:**

.. code-block:: bash

   # Show percentage returns (default)
   portfolio-toolkit portfolio performance portfolio.json --display return

   # Show absolute position values
   portfolio-toolkit portfolio performance portfolio.json --display value

Example output:

.. code-block:: text

   📊 Performance Summary - Last 4 Weeks
   ============================================================
           W27 2025    W28 2025    W29 2025    W30 2025
   AAPL    -           3.33%       2.86%       1.92%
   MSFT    -           -1.25%      4.17%       2.10%
   ============================================================
   Note: Percentage returns vs previous period

Portfolio Evolution
~~~~~~~~~~~~~~~~~~~

Visualize how your portfolio has evolved over time.

.. code-block:: bash

   # Plot portfolio evolution chart
   portfolio-toolkit portfolio evolution portfolio.json

This command creates a time-series chart showing your portfolio's value evolution, including:

- Total portfolio value over time
- Individual asset performance
- Cash position changes
- Overall return trends

Tax Reporting
~~~~~~~~~~~~~

Generate tax reports for a specific year.

.. code-block:: bash

   # Generate tax report for 2025
   portfolio-toolkit portfolio tax-report portfolio.json 2025

Example output:

.. code-block:: text

   📊 Tax Report for 2025
   ============================================================
   Realized Gains/Losses:
   
   Asset    Sale Date    Quantity  Buy Price  Sale Price  Gain/Loss
   AAPL   2025-06-15         10     150.25     180.50      +302.50
   MSFT   2025-09-20          5     280.50     275.00       -27.50
   ============================================================
   Total Realized Gain: +$275.00

Command Reference
-----------------

Complete command reference with all available options:

**portfolio transactions**

.. code-block:: text

   Usage: portfolio-toolkit portfolio transactions [OPTIONS] FILE

   Show portfolio transactions

   Options:
     --output PATH  Save results to CSV file instead of printing to console
     --cash         Show cash transactions instead of asset transactions
     --help         Show this message and exit

**portfolio positions**

.. code-block:: text

   Usage: portfolio-toolkit portfolio positions [OPTIONS] FILE DATE

   Show portfolio positions for a specific date

   Options:
     --plot     Create pie chart visualization
     --country  Group positions by country
     --sector   Group positions by sector
     --help     Show this message and exit

**portfolio performance**

.. code-block:: text

   Usage: portfolio-toolkit portfolio performance [OPTIONS] FILE

   Show performance summary across multiple periods

   Options:
     --display [return|value]        Display mode: returns or values [default: return]
     -n, --periods INTEGER          Number of periods to analyze [default: 4]
     --period-type [weeks|months|quarters|years]  Period type [default: weeks]
     --output PATH                  Save results to CSV file
     --help                         Show this message and exit

**portfolio evolution**

.. code-block:: text

   Usage: portfolio-toolkit portfolio evolution [OPTIONS] FILE

   Plot portfolio evolution over time

   Options:
     --help  Show this message and exit

**portfolio tax-report**

.. code-block:: text

   Usage: portfolio-toolkit portfolio tax-report [OPTIONS] FILE YEAR

   Generate tax report for a specific year

   Options:
     --help  Show this message and exit

Development Usage
-----------------

For development purposes, you can run commands using the module directly:

.. code-block:: bash

   # Using the module directly (for development)
   python -m portfolio_toolkit.cli.cli portfolio transactions portfolio.json
   python -m portfolio_toolkit.cli.cli portfolio positions portfolio.json 2025-07-30
   python -m portfolio_toolkit.cli.cli portfolio performance portfolio.json
   python -m portfolio_toolkit.cli.cli portfolio tax-report portfolio.json 2025

Common Workflows
----------------

**Daily Portfolio Check:**

.. code-block:: bash

   # Check current positions
   portfolio-toolkit portfolio positions portfolio.json $(date +%Y-%m-%d)
   
   # Check recent performance
   portfolio-toolkit portfolio performance portfolio.json --period-type weeks -n 2

**Monthly Review:**

.. code-block:: bash

   # Monthly performance analysis
   portfolio-toolkit portfolio performance portfolio.json --period-type months -n 6
   
   # Export data for spreadsheet analysis
   portfolio-toolkit portfolio transactions portfolio.json --output monthly_transactions.csv
   portfolio-toolkit portfolio performance portfolio.json --output monthly_performance.csv

**Tax Season Preparation:**

.. code-block:: bash

   # Generate tax report
   portfolio-toolkit portfolio tax-report portfolio.json 2025
   
   # Export all transactions for tax software
   portfolio-toolkit portfolio transactions portfolio.json --output tax_transactions.csv

**Portfolio Analysis Session:**

.. code-block:: bash

   # Comprehensive analysis
   portfolio-toolkit portfolio positions portfolio.json $(date +%Y-%m-%d) --plot
   portfolio-toolkit portfolio performance portfolio.json --period-type quarters -n 4
   portfolio-toolkit portfolio evolution portfolio.json

Getting Help
------------

For more help with any command:

.. code-block:: bash

   # General help
   portfolio-toolkit --help

   # Portfolio commands help
   portfolio-toolkit portfolio --help

   # Specific command help
   portfolio-toolkit portfolio transactions --help
   portfolio-toolkit portfolio positions --help
   portfolio-toolkit portfolio performance --help

Error Handling
--------------

The CLI provides helpful error messages for common issues:

**File not found:**

.. code-block:: bash

   $ portfolio-toolkit portfolio positions missing.json 2025-07-30
   Error: Portfolio file 'missing.json' not found.

**Invalid date format:**

.. code-block:: bash

   $ portfolio-toolkit portfolio positions portfolio.json 07-30-2025
   Error: Invalid date format. Use YYYY-MM-DD format.

**Missing arguments:**

.. code-block:: bash

   $ portfolio-toolkit portfolio positions portfolio.json
   Usage: portfolio-toolkit portfolio positions [OPTIONS] FILE DATE
   Error: Missing argument 'DATE'.

For more detailed information about portfolio file formats and data structures, see the :doc:`../user_guide/portfolio_format` documentation.