refactor

Author: bufdev

README.md

@@ -53,14 +53,14 @@ ibctl transaction list --from 20250101 --to 20251231 --base-currency USD
 | `ibctl data zip -o <file>` | Archive the ibctl directory to a zip file |
 | `ibctl download` | Download and cache IBKR data via Flex Query API |
 | `ibctl holding list` | Display holdings with prices, positions, and classifications |
-| `ibctl holding lot list` | Display individual FIFO tax lots |
-| `ibctl holding category list` | Display holdings aggregated by category |
-| `ibctl holding geo list` | Display holdings aggregated by geographic classification |
-| `ibctl holding safe-sell list` | Identify positions safe to sell from a tax perspective (loss or LTCG only) |
-| `ibctl holding unsafe-sell list` | Show positions with short-term capital gains exposure |
-| `ibctl holding value` | Display portfolio value with estimated tax impact |
+| `ibctl lot list` | Display individual FIFO tax lots |
+| `ibctl category list` | Display holdings aggregated by category |
+| `ibctl geo list` | Display holdings aggregated by geographic classification |
+| `ibctl possible-sale list --safe` | Identify positions safe to sell from a tax perspective (loss or LTCG only) |
+| `ibctl possible-sale list --unsafe` | Show positions with short-term capital gains exposure |
+| `ibctl value` | Display portfolio value with estimated tax impact |
 | `ibctl transaction list` | List all transactions (buys, sells, dividends, interest, WHT, etc.) chronologically |
-| `ibctl transaction sale list` | List realized security sales with FIFO lot matching for tax reporting |
+| `ibctl realized-sale list` | List realized security sales with FIFO lot matching for tax reporting |
 
 All commands accept `--dir` to specify the ibctl directory (defaults to `.`). All holding and transaction commands accept `--base-currency` (default `USD`) to convert values to a different currency. Holding commands accept `--realtime` to fetch current stock prices and FX rates from Yahoo Finance on-demand. For international symbols where IBKR and Yahoo symbols differ, add mappings to `realtime_symbols` in `ibctl.yaml`. Use `--help` on any command for detailed documentation.
 
@@ -70,10 +70,10 @@ Generate CSV files for your accountant:
 
 ```bash
 # Realized capital gains for IRS (US tax reporting).
-ibctl transaction sale list --from 20250101 --to 20251231 --base-currency USD --format csv > transaction-sale-list-2025-usd.csv
+ibctl realized-sale list --from 20250101 --to 20251231 --base-currency USD --format csv > realized-sale-list-2025-usd.csv
 
 # Realized capital gains for CRA (Canadian tax reporting).
-ibctl transaction sale list --from 20250101 --to 20251231 --base-currency CAD --format csv > transaction-sale-list-2025-cad.csv
+ibctl realized-sale list --from 20250101 --to 20251231 --base-currency CAD --format csv > realized-sale-list-2025-cad.csv
 
 # Complete transaction history for IRS (dividends, interest, WHT, buys, sells, etc.).
 ibctl transaction list --from 20250101 --to 20251231 --base-currency USD --format csv > transaction-list-2025-usd.csv

book/src/SUMMARY.md

@@ -13,13 +13,12 @@
 - [Commands](commands/overview.md)
   - [download](commands/download.md)
   - [holding list](commands/holding-list.md)
-  - [holding lot list](commands/holding-lot-list.md)
-  - [holding category list](commands/holding-category-list.md)
-  - [holding geo list](commands/holding-geo-list.md)
-  - [holding safe-sell list](commands/holding-safe-sell-list.md)
-  - [holding unsafe-sell list](commands/holding-unsafe-sell-list.md)
-  - [holding value](commands/holding-value.md)
+  - [lot list](commands/lot-list.md)
+  - [category list](commands/category-list.md)
+  - [geo list](commands/geo-list.md)
+  - [possible-sale list](commands/possible-sale-list.md)
+  - [value](commands/value.md)
   - [transaction list](commands/transaction-list.md)
-  - [transaction sale list](commands/transaction-sale-list.md)
+  - [realized-sale list](commands/realized-sale-list.md)
 - [Tax Reporting Guide](tax-reporting.md)
 - [Glossary](glossary.md)

…ok/src/commands/holding-category-list.md book/src/commands/category-list.mdbook/src/commands/holding-category-list.md renamed to book/src/commands/category-list.md book/src/commands/holding-category-list.md renamed to book/src/commands/category-list.md

@@ -1,7 +1,7 @@
-# holding category list
+# category list
 
 ```
-ibctl holding category list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--geo GEO] [--base-currency CURRENCY]
+ibctl category list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--geo GEO] [--base-currency CURRENCY]
 ```
 
 Aggregates holdings by category and displays each category's market value, percentage of net liquidation value, and capital gains breakdown.

book/src/commands/holding-geo-list.md book/src/commands/geo-list.mdbook/src/commands/holding-geo-list.md renamed to book/src/commands/geo-list.md

@@ -1,7 +1,7 @@
-# holding geo list
+# geo list
 
 ```
-ibctl holding geo list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--category CATEGORY] [--base-currency CURRENCY]
+ibctl geo list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--category CATEGORY] [--base-currency CURRENCY]
 ```
 
 Aggregates holdings by geographic classification and displays each geo's market value, percentage of net liquidation value, and capital gains breakdown.

book/src/commands/holding-list.md

@@ -6,7 +6,7 @@ ibctl holding list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--ba
 
 Shows combined positions across all accounts. Positions are computed via FIFO tax lot matching with weighted average cost basis, then verified against IBKR-reported positions.
 
-Use `--base-currency` (default `USD`) to convert all values to a different currency. Cost basis is converted using the FX rate on the lot's open date; current market value uses today's rate. This correctly shows FX-adjusted unrealized P&L -- the same methodology used by `transaction sale list` for realized gains.
+Use `--base-currency` (default `USD`) to convert all values to a different currency. Cost basis is converted using the FX rate on the lot's open date; current market value uses today's rate. This correctly shows FX-adjusted unrealized P&L -- the same methodology used by `realized-sale list` for realized gains.
 
 Positions worth less than 0.01 in the base currency are filtered out. This removes dust positions (e.g., a JPY cash balance that rounds to -0.00 in USD).
 

book/src/commands/holding-safe-sell-list.md

@@ -1,7 +1,7 @@
-# holding lot list
+# lot list
 
 ```
-ibctl holding lot list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--symbol SYMBOL] [--base-currency CURRENCY]
+ibctl lot list [--dir DIR] [--format FORMAT] [--download] [--realtime] [--symbol SYMBOL] [--base-currency CURRENCY]
 ```
 
 Lists individual FIFO tax lots. Unlike `holding list`, which aggregates positions by symbol, this command shows each tax lot separately with its own open date, quantity, and cost basis.

book/src/commands/holding-unsafe-sell-list.md

@@ -31,19 +31,18 @@ All holding commands accept `--base-currency` (default `USD`) to convert values
 | Command | Purpose |
 |---------|---------|
 | `ibctl holding list` | List combined positions across all accounts with prices, P&L, and classifications |
-| `ibctl holding lot list` | List individual FIFO tax lots with per-lot cost basis and P&L |
-| `ibctl holding category list` | Aggregate holdings by category with market value and P&L |
-| `ibctl holding geo list` | Aggregate holdings by geographic classification with market value and P&L |
-| `ibctl holding safe-sell list` | Identify positions safe to sell from a tax perspective (loss or LTCG only) |
-| `ibctl holding unsafe-sell list` | Show positions with short-term capital gains exposure (inverse of safe-sell) |
-| `ibctl holding value` | Display portfolio value with estimated unrealized and YTD realized tax impact |
+| `ibctl lot list` | List individual FIFO tax lots with per-lot cost basis and P&L |
+| `ibctl category list` | Aggregate holdings by category with market value and P&L |
+| `ibctl geo list` | Aggregate holdings by geographic classification with market value and P&L |
+| `ibctl possible-sale list` | Screen positions for possible sales; use `--safe`, `--safe-excluded`, or `--unsafe` to filter the view |
+| `ibctl value` | Display portfolio value with estimated unrealized and YTD realized tax impact |
 
 ## Transaction commands
 
 | Command | Purpose |
 |---------|---------|
 | `ibctl transaction list` | List all transactions (buys, sells, dividends, interest, WHT, corporate actions, transfers) in chronological order |
-| `ibctl transaction sale list` | List realized security sales matched to FIFO buy lots for tax reporting |
+| `ibctl realized-sale list` | List realized security sales matched to FIFO buy lots for tax reporting |
 
 ## Diagnostic commands