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:
pip install portfolio-toolkit
After installation, you can access the CLI directly:
# 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 Portfolio JSON Format.
Here’s a basic example of a portfolio file:
{
"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:
# 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:
# 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:
📊 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:
# Show positions for a specific date
portfolio-toolkit portfolio positions portfolio.json 2025-07-30
Position visualizations:
# 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:
📊 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:
# Compare returns over the last 4 weeks (default)
portfolio-toolkit portfolio performance portfolio.json
Customized time periods:
# 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:
# Export returns to CSV file
portfolio-toolkit portfolio performance portfolio.json --output performance.csv
Display options:
# 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:
📊 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.
# 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.
# Generate tax report for 2025
portfolio-toolkit portfolio tax-report portfolio.json 2025
Example output:
📊 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
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
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
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
Usage: portfolio-toolkit portfolio evolution [OPTIONS] FILE
Plot portfolio evolution over time
Options:
--help Show this message and exit
portfolio tax-report
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:
# 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:
# 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:
# 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:
# 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:
# 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:
# 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:
$ portfolio-toolkit portfolio positions missing.json 2025-07-30
Error: Portfolio file 'missing.json' not found.
Invalid date format:
$ portfolio-toolkit portfolio positions portfolio.json 07-30-2025
Error: Invalid date format. Use YYYY-MM-DD format.
Missing arguments:
$ 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 Portfolio JSON Format documentation.