commit

Author: bufdev

cmd/ibctl/internal/command/holding/holding.go

@@ -16,6 +16,7 @@ import (
 	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/holding/holdingvalue"
 	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/holding/lot"
 	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/holding/projectedincome"
+	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/holding/safesell"
 )
 
 // NewCommand returns a new holding command group.
@@ -31,6 +32,7 @@ func NewCommand(name string, builder appext.SubCommandBuilder) *appcmd.Command {
 			lot.NewCommand("lot", builder),
 			holdingoverview.NewCommand("overview", builder),
 			projectedincome.NewCommand("projected-income", builder),
+			safesell.NewCommand("safe-sell", builder),
 			holdingvalue.NewCommand("value", builder),
 		},
 	}

cmd/ibctl/internal/command/holding/safesell/safesell.go

@@ -0,0 +1,23 @@
+// Copyright 2026 Peter Edge
+//
+// All rights reserved.
+
+// Package safesell implements the "holding safe-sell" command group.
+package safesell
+
+import (
+	"buf.build/go/app/appcmd"
+	"buf.build/go/app/appext"
+	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/holding/safesell/safeselllist"
+)
+
+// NewCommand returns a new safe-sell command group.
+func NewCommand(name string, builder appext.SubCommandBuilder) *appcmd.Command {
+	return &appcmd.Command{
+		Use:   name,
+		Short: "Identify positions safe to sell from a tax perspective",
+		SubCommands: []*appcmd.Command{
+			safeselllist.NewCommand("list", builder),
+		},
+	}
+}

cmd/ibctl/internal/command/holding/safesell/safeselllist/safeselllist.go

@@ -0,0 +1,274 @@
+// Copyright 2026 Peter Edge
+//
+// All rights reserved.
+
+// Package safeselllist implements the "holding safe-sell list" command.
+package safeselllist
+
+import (
+	"context"
+	"os"
+	"strings"
+	"time"
+
+	"buf.build/go/app/appcmd"
+	"buf.build/go/app/appext"
+	"github.com/bufdev/ibctl/cmd/ibctl/internal/ibctlcmd"
+	"github.com/bufdev/ibctl/internal/ibctl/ibctlconfig"
+	"github.com/bufdev/ibctl/internal/ibctl/ibctlfxrates"
+	"github.com/bufdev/ibctl/internal/ibctl/ibctlmerge"
+	"github.com/bufdev/ibctl/internal/ibctl/ibctlpath"
+	"github.com/bufdev/ibctl/internal/ibctl/ibctlrealtime"
+	"github.com/bufdev/ibctl/internal/ibctl/ibctlsafesell"
+	"github.com/bufdev/ibctl/internal/pkg/cliio"
+	"github.com/bufdev/ibctl/internal/pkg/moneypb"
+	"github.com/bufdev/ibctl/internal/pkg/yahoofinance"
+	"github.com/spf13/pflag"
+)
+
+const (
+	// formatFlagName is the flag name for the output format.
+	formatFlagName = "format"
+	// downloadFlagName is the flag name for downloading fresh data before displaying.
+	downloadFlagName = "download"
+	// baseCurrencyFlagName is the flag name for the base currency for value conversion.
+	baseCurrencyFlagName = "base-currency"
+	// realtimeFlagName is the flag name for fetching real-time quotes and FX rates.
+	realtimeFlagName = "realtime"
+	// separateAccountsFlagName is the flag name for per-account FIFO (CRA-style).
+	separateAccountsFlagName = "separate-accounts"
+)
+
+// NewCommand returns a new safe-sell list command.
+func NewCommand(name string, builder appext.SubCommandBuilder) *appcmd.Command {
+	flags := newFlags()
+	return &appcmd.Command{
+		Use:   name,
+		Short: "List positions safe to sell from a tax perspective",
+		Long: `Identify positions that can be sold without triggering significant
+short-term capital gains.
+
+Safe-sell walks each symbol's FIFO lots in date order and stops when a
+lot's unrealized short-term capital gain meets or exceeds --max-stcg.
+Lots before the stop point are sellable if they represent a capital loss
+or a long-term capital gain.
+
+This is useful for portfolio simplification: sell individual positions to
+harvest losses or realize long-term gains at favorable rates, then
+reinvest proceeds into core index fund allocations.
+
+ACCOUNT COMBINING (IRS vs CRA)
+
+By default, lots from all accounts for the same symbol are merged into a
+single FIFO queue sorted by date. This is the IRS-correct behavior for
+individuals whose accounts include disregarded entities (e.g., single-
+member LLCs) — the IRS treats all disregarded-entity holdings as the
+individual's own, so FIFO matching spans all accounts.
+
+Use --separate-accounts for CRA-style treatment where each account is an
+independent entity with its own FIFO queue. The same symbol may appear
+multiple times in the output (once per account) with different P&L. An
+ACCOUNT column is shown in this mode.
+
+EXCLUSIONS
+
+Symbols listed under safe_sell.excludes in ibctl.yaml are always omitted.
+Use this for core positions you intend to hold regardless of tax status.
+
+STCG THRESHOLD
+
+The safe_sell.max_stcg setting in ibctl.yaml controls tolerance for
+short-term capital gains per lot. At the default of 0, any lot with
+positive STCG stops the FIFO walk for that symbol. Setting max_stcg to
+3000 allows lots with up to $3000 of STCG to pass through, which prevents
+small STCG lots from blocking access to loss or LTCG lots behind them in
+the queue.
+
+COLUMNS
+
+  SYMBOL        Ticker symbol.
+  ACCOUNT       Account alias. Only shown with --separate-accounts.
+  QTY           Total quantity across all sellable lots.
+  QTY REMAINING Quantity not included because the FIFO walk was stopped.
+  CURRENCY      Native currency of cost basis and market price.
+  AVG PRICE     Weighted average cost basis per share (native currency).
+  MKT PRICE     Current market price per share (native currency).
+  MKT VAL {B}   Total current market value of sellable lots (base currency).
+  P&L {B}       Total unrealized P&L of sellable lots (base currency).
+  STCG {B}      Short-term portion of unrealized P&L (base currency).
+  LTCG {B}      Long-term portion of unrealized P&L (base currency).
+
+EXAMPLES
+
+  # Strict mode: no STCG tolerance, real-time prices
+  ibctl holding safe-sell list --realtime
+
+  # Per-account FIFO (CRA-style), JSON output
+  ibctl holding safe-sell list --realtime --separate-accounts --format json`,
+		Args: appcmd.NoArgs,
+		Run: builder.NewRunFunc(
+			func(ctx context.Context, container appext.Container) error {
+				return run(ctx, container, flags)
+			},
+		),
+		BindFlags: flags.Bind,
+	}
+}
+
+type flags struct {
+	// Format is the output format (table, csv, json).
+	Format string
+	// Download fetches fresh data before displaying.
+	Download bool
+	// BaseCurrency is the target currency for value conversion (e.g., "USD", "CAD").
+	BaseCurrency string
+	// Realtime fetches real-time quotes and FX rates from Yahoo Finance.
+	Realtime bool
+	// SeparateAccounts applies FIFO independently per account (CRA-style).
+	SeparateAccounts bool
+}
+
+func newFlags() *flags {
+	return &flags{}
+}
+
+// Bind registers the flag definitions with the given flag set.
+func (f *flags) Bind(flagSet *pflag.FlagSet) {
+	flagSet.StringVar(&f.Format, formatFlagName, "table", "Output format (table, csv, json)")
+	flagSet.BoolVar(&f.Download, downloadFlagName, false, "Download fresh data before displaying")
+	flagSet.StringVar(&f.BaseCurrency, baseCurrencyFlagName, "USD", "Base currency for value conversion (e.g., USD, CAD)")
+	flagSet.BoolVar(&f.Realtime, realtimeFlagName, false, "Fetch real-time quotes and FX rates from Yahoo Finance")
+	flagSet.BoolVar(&f.SeparateAccounts, separateAccountsFlagName, false, "Apply FIFO independently per account (CRA-style)")
+}
+
+func run(ctx context.Context, container appext.Container, flags *flags) error {
+	format, err := cliio.ParseFormat(flags.Format)
+	if err != nil {
+		return appcmd.NewInvalidArgumentError(err.Error())
+	}
+	// Normalize base currency to uppercase for case-insensitive matching.
+	baseCurrency := strings.ToUpper(flags.BaseCurrency)
+	// Select the formatting functions based on the base currency.
+	formatBase := formatBaseFunc(baseCurrency)
+	formatBaseMicros := formatBaseMicrosFunc(baseCurrency)
+	// Resolve the ibctl directory from the IBKR_DIR environment variable.
+	dirPath, err := ibctlcmd.DirPath(container)
+	if err != nil {
+		return err
+	}
+	// Read and validate the configuration file from the base directory.
+	config, err := ibctlconfig.ReadConfig(dirPath)
+	if err != nil {
+		return err
+	}
+	// Download fresh data if --download is set.
+	if flags.Download {
+		downloader, err := ibctlcmd.NewDownloader(container, dirPath)
+		if err != nil {
+			return err
+		}
+		if err := downloader.Download(ctx); err != nil {
+			return err
+		}
+	}
+	// Merge trade data from all sources.
+	mergedData, err := ibctlmerge.Merge(
+		ibctlpath.DataAccountsDirPath(config.DirPath),
+		ibctlpath.CacheAccountsDirPath(config.DirPath),
+		ibctlpath.ActivityStatementsDirPath(config.DirPath),
+		ibctlpath.SeedDirPath(config.DirPath),
+		config.AccountAliases,
+		config.Additions,
+	)
+	if err != nil {
+		return err
+	}
+	// Load FX rates for base currency conversion.
+	fxStore := ibctlfxrates.NewStore(ibctlpath.CacheFXDirPath(config.DirPath))
+	// Override market prices and FX rates with real-time data from Yahoo Finance.
+	if flags.Realtime {
+		todayDate := time.Now().Format("2006-01-02")
+		if err := ibctlrealtime.ApplyOverrides(ctx, container.Logger(), yahoofinance.NewClient(), mergedData.Positions, fxStore, config, baseCurrency, todayDate); err != nil {
+			return err
+		}
+	}
+	// Get the safe-sell list.
+	// Get the safe-sell list. The STCG threshold is read from config.SafeSellMaxSTCGMicros.
+	results, err := ibctlsafesell.GetSafeSellList(
+		mergedData.Trades,
+		mergedData.Positions,
+		config,
+		fxStore,
+		baseCurrency,
+		flags.SeparateAccounts,
+	)
+	if err != nil {
+		return err
+	}
+	// Write output in the requested format.
+	writer := os.Stdout
+	switch format {
+	case cliio.FormatTable:
+		headers := ibctlsafesell.SafeSellHeaders(baseCurrency, flags.SeparateAccounts)
+		rows := make([][]string, 0, len(results))
+		for _, r := range results {
+			rows = append(rows, ibctlsafesell.SafeSellOverviewToTableRow(r, formatBase, flags.SeparateAccounts))
+		}
+		// Build totals row.
+		totals := ibctlsafesell.ComputeSafeSellTotals(results, formatBaseMicros)
+		totalsRow := make([]string, len(headers))
+		totalsRow[0] = "TOTAL"
+		if flags.SeparateAccounts {
+			// With ACCOUNT column: SYMBOL, ACCOUNT, QTY, QTY REMAINING, CURRENCY, AVG PRICE, MKT PRICE, MKT VAL, P&L, STCG, LTCG, ...
+			totalsRow[7] = totals.MktValBase
+			totalsRow[8] = totals.PnLBase
+			totalsRow[9] = totals.STCGBase
+			totalsRow[10] = totals.LTCGBase
+		} else {
+			// Without ACCOUNT column: SYMBOL, QTY, QTY REMAINING, CURRENCY, AVG PRICE, MKT PRICE, MKT VAL, P&L, STCG, LTCG, ...
+			totalsRow[6] = totals.MktValBase
+			totalsRow[7] = totals.PnLBase
+			totalsRow[8] = totals.STCGBase
+			totalsRow[9] = totals.LTCGBase
+		}
+		return cliio.WriteTableWithTotals(writer, headers, rows, totalsRow)
+	case cliio.FormatCSV:
+		headers := ibctlsafesell.SafeSellHeaders(baseCurrency, flags.SeparateAccounts)
+		records := make([][]string, 0, len(results)+1)
+		records = append(records, headers)
+		for _, r := range results {
+			records = append(records, ibctlsafesell.SafeSellOverviewToRow(r, flags.SeparateAccounts))
+		}
+		return cliio.WriteCSVRecords(writer, records)
+	case cliio.FormatJSON:
+		return cliio.WriteJSON(writer, results...)
+	default:
+		return appcmd.NewInvalidArgumentErrorf("unsupported format: %s", format)
+	}
+}
+
+// formatBaseFunc returns a formatting function for display values in the given currency.
+func formatBaseFunc(baseCurrency string) func(string) string {
+	switch baseCurrency {
+	case "USD":
+		return cliio.FormatUSD
+	case "CAD":
+		return cliio.FormatCAD
+	default:
+		return func(v string) string { return v }
+	}
+}
+
+// formatBaseMicrosFunc returns a formatting function for micros values in the given currency.
+func formatBaseMicrosFunc(baseCurrency string) func(int64) string {
+	switch baseCurrency {
+	case "USD":
+		return cliio.FormatUSDMicros
+	case "CAD":
+		return cliio.FormatCADMicros
+	default:
+		return func(micros int64) string {
+			return moneypb.MoneyValueToString(moneypb.MoneyFromMicros(baseCurrency, micros))
+		}
+	}
+}

cmd/ibctl/internal/ibctlcmd/holdingsdata.go

@@ -369,10 +369,12 @@ func WriteHoldingListTable(writer io.Writer, holdings []*ibctlholdings.HoldingOv
 	totals := ibctlholdings.ComputeTotals(holdings, formatBaseMicros)
 	totalsRow := make([]string, len(headers))
 	totalsRow[0] = "TOTAL"
-	totalsRow[6] = totals.MarketValueBase
-	totalsRow[7] = totals.PnLBase
-	totalsRow[8] = totals.STCGBase
-	totalsRow[9] = totals.LTCGBase
+	// Column indices: SYMBOL(0), CURRENCY(1), QTY(2), LAST PRICE(3), AVG PRICE(4),
+	// LAST B(5), AVG B(6), MKT VAL B(7), P&L B(8), STCG B(9), LTCG B(10), ...
+	totalsRow[7] = totals.MarketValueBase
+	totalsRow[8] = totals.PnLBase
+	totalsRow[9] = totals.STCGBase
+	totalsRow[10] = totals.LTCGBase
 	return cliio.WriteTableWithTotals(writer, headers, sections, totalsRow)
 }