Ejemplos de Uso de CLI
Esta sección proporciona ejemplos completos de cómo usar la interfaz de línea de comandos (CLI) de Portfolio Toolkit. El CLI ha sido construido usando el framework Click para una experiencia intuitiva y amigable.
Instalación
Instala el paquete usando pip:
pip install portfolio-toolkit
Después de la instalación, puedes acceder al CLI directamente:
# Ver comandos disponibles
portfolio-toolkit --help
# Verificar versión
portfolio-toolkit --version
Crear tu Archivo de Cartera
Antes de usar los comandos CLI, necesitas crear un archivo JSON de cartera que describa tus inversiones. Para información detallada sobre el formato del archivo de cartera, ve Formato JSON de Cartera.
Aquí hay un ejemplo básico de un archivo de cartera:
{
"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"
}
]
}
]
}
Guarda esto como portfolio.json para usar con los ejemplos a continuación.
Comandos Disponibles
El CLI está organizado alrededor de comandos de análisis de cartera. Aquí están los grupos principales de comandos y su uso:
Transacciones de Cartera
Listar y exportar datos de transacciones desde tu cartera.
Listar transacciones de activos:
# Mostrar todas las transacciones de activos
portfolio-toolkit portfolio transactions portfolio.json
# Exportar transacciones de activos a CSV
portfolio-toolkit portfolio transactions portfolio.json --output transactions.csv
Listar transacciones de efectivo:
# Mostrar transacciones de cuenta de efectivo (depósitos, retiros)
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 Formato JSON de Cartera documentation.