commit

Author: bufdev

README.md

@@ -1,9 +1,5 @@
 # ibctl
 
-## TODO:
-
-- other manual things other than just cash adjustments, and a list of them
-
 A CLI tool for analyzing Interactive Brokers (IBKR) holdings and trades. Downloads data via the IBKR Flex Query API, computes FIFO tax lots, and displays holdings with prices, positions, and USD conversions. Supports multiple IBKR accounts.
 
 ## Prerequisites
@@ -118,17 +114,31 @@ accounts:
   rrsp: "U1234567"
   holdco: "U2345678"
   individual: "U3456789"
-symbols:
-  - name: AAPL
+categorization:
+  - symbol: AAPL
     category: EQUITY
     type: STOCK
     sector: TECH
     geo: US
+cash:
+  CAD: "-5000.00"
+additions:
+  - account_alias: wealthsimple
+    symbol: VFV.TO
+    currency_code: CAD
+    trade_date: "20240315"
+    trade_price: "102.50"
+    trade_side: buy
+    quantity: "100"
+    last_price: "115.30"
+    tax_exempt: true
 ```
 
 - `flex_query_id` — your IBKR Flex Query ID (required)
 - `accounts` — maps user-chosen aliases to IBKR account IDs (required). Account numbers are confidential — only aliases appear in output and directory names.
-- `symbols` — optional classification metadata for holdings display (category, type, sector, geo)
+- `categorization` — optional classification metadata for holdings display (category, type, sector, geo)
+- `cash` — optional manual cash adjustments by currency code (applied to cash positions in holdings display)
+- `additions` — optional manually added trades from non-IBKR brokers. Addition accounts must not match IBKR account aliases. Trade dates use YYYYMMDD format. When `tax_exempt` is true, lots show P&L=0 and are excluded from tax calculations.
 
 ## Usage
 

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

@@ -8,6 +8,7 @@ package categorylist
 import (
 	"context"
 	"os"
+	"strings"
 
 	"buf.build/go/app/appcmd"
 	"buf.build/go/app/appext"
@@ -21,11 +22,14 @@ import (
 	"github.com/spf13/pflag"
 )
 
-// formatFlagName is the flag name for the output format.
-const formatFlagName = "format"
-
-// downloadFlagName is the flag name for downloading fresh data before displaying.
-const downloadFlagName = "download"
+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"
+	// geoFlagName is the flag name for filtering by geo.
+	geoFlagName = "geo"
+)
 
 // NewCommand returns a new category list command.
 func NewCommand(name string, builder appext.SubCommandBuilder) *appcmd.Command {
@@ -50,6 +54,8 @@ type flags struct {
 	Format string
 	// Download fetches fresh data before displaying.
 	Download bool
+	// Geo filters to only include holdings matching this geographic classification.
+	Geo string
 }
 
 func newFlags() *flags {
@@ -61,6 +67,7 @@ func (f *flags) Bind(flagSet *pflag.FlagSet) {
 	flagSet.StringVar(&f.Dir, ibctlcmd.DirFlagName, ".", "The ibctl directory containing ibctl.yaml")
 	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.Geo, geoFlagName, "", "Filter by geo (e.g., US, INTL)")
 }
 
 func run(ctx context.Context, container appext.Container, flags *flags) error {
@@ -90,6 +97,7 @@ func run(ctx context.Context, container appext.Container, flags *flags) error {
 		ibctlpath.ActivityStatementsDirPath(config.DirPath),
 		ibctlpath.SeedDirPath(config.DirPath),
 		config.AccountAliases,
+		config.Additions,
 	)
 	if err != nil {
 		return err
@@ -101,8 +109,8 @@ func run(ctx context.Context, container appext.Container, flags *flags) error {
 	if err != nil {
 		return err
 	}
-	// Aggregate holdings by category.
-	categories := ibctlholdings.GetCategoryList(result.Holdings)
+	// Aggregate holdings by category, optionally filtered by geo (case-insensitive).
+	categories := ibctlholdings.GetCategoryList(result.Holdings, strings.ToUpper(flags.Geo))
 	// Write output in the requested format.
 	writer := os.Stdout
 	switch format {

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

@@ -0,0 +1,23 @@
+// Copyright 2026 Peter Edge
+//
+// All rights reserved.
+
+// Package geo implements the "holding geo" command group.
+package geo
+
+import (
+	"buf.build/go/app/appcmd"
+	"buf.build/go/app/appext"
+	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/holding/geo/geolist"
+)
+
+// NewCommand returns a new geo command group.
+func NewCommand(name string, builder appext.SubCommandBuilder) *appcmd.Command {
+	return &appcmd.Command{
+		Use:   name,
+		Short: "Display holdings by geographic classification",
+		SubCommands: []*appcmd.Command{
+			geolist.NewCommand("list", builder),
+		},
+	}
+}

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

@@ -0,0 +1,137 @@
+// Copyright 2026 Peter Edge
+//
+// All rights reserved.
+
+// Package geolist implements the "holding geo list" command.
+package geolist
+
+import (
+	"context"
+	"os"
+	"strings"
+
+	"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/ibctlholdings"
+	"github.com/bufdev/ibctl/internal/ibctl/ibctlmerge"
+	"github.com/bufdev/ibctl/internal/ibctl/ibctlpath"
+	"github.com/bufdev/ibctl/internal/pkg/cliio"
+	"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"
+	// categoryFlagName is the flag name for filtering by category.
+	categoryFlagName = "category"
+)
+
+// NewCommand returns a new geo list command.
+func NewCommand(name string, builder appext.SubCommandBuilder) *appcmd.Command {
+	flags := newFlags()
+	return &appcmd.Command{
+		Use:   name,
+		Short: "List holdings aggregated by geographic classification",
+		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 {
+	// Dir is the base directory containing ibctl.yaml and data subdirectories.
+	Dir string
+	// Format is the output format (table, csv, json).
+	Format string
+	// Download fetches fresh data before displaying.
+	Download bool
+	// Category filters to only include holdings matching this category.
+	Category string
+}
+
+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.Dir, ibctlcmd.DirFlagName, ".", "The ibctl directory containing ibctl.yaml")
+	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.Category, categoryFlagName, "", "Filter by category (e.g., EQUITY, FIXED_INCOME)")
+}
+
+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())
+	}
+	// Read and validate the configuration file from the base directory.
+	config, err := ibctlconfig.ReadConfig(flags.Dir)
+	if err != nil {
+		return err
+	}
+	// Download fresh data if --download is set.
+	if flags.Download {
+		downloader, err := ibctlcmd.NewDownloader(container, flags.Dir)
+		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 USD conversion.
+	fxStore := ibctlfxrates.NewStore(ibctlpath.CacheFXDirPath(config.DirPath))
+	// Compute holdings via FIFO from all trade data.
+	result, err := ibctlholdings.GetHoldingsOverview(mergedData.Trades, mergedData.Positions, mergedData.CashPositions, config, fxStore)
+	if err != nil {
+		return err
+	}
+	// Aggregate holdings by geo, optionally filtered by category (case-insensitive).
+	geos := ibctlholdings.GetGeoList(result.Holdings, strings.ToUpper(flags.Category))
+	// Write output in the requested format.
+	writer := os.Stdout
+	switch format {
+	case cliio.FormatTable:
+		headers := ibctlholdings.GeoListHeaders()
+		rows := make([][]string, 0, len(geos))
+		for _, g := range geos {
+			rows = append(rows, ibctlholdings.GeoOverviewToTableRow(g))
+		}
+		return cliio.WriteTable(writer, headers, rows)
+	case cliio.FormatCSV:
+		headers := ibctlholdings.GeoListHeaders()
+		records := make([][]string, 0, len(geos)+1)
+		records = append(records, headers)
+		for _, g := range geos {
+			records = append(records, ibctlholdings.GeoOverviewToRow(g))
+		}
+		return cliio.WriteCSVRecords(writer, records)
+	case cliio.FormatJSON:
+		return cliio.WriteJSON(writer, geos...)
+	default:
+		return appcmd.NewInvalidArgumentErrorf("unsupported format: %s", format)
+	}
+}

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

@@ -9,6 +9,7 @@ import (
 	"buf.build/go/app/appcmd"
 	"buf.build/go/app/appext"
 	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/holding/category"
+	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/holding/geo"
 	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/holding/holdinglist"
 	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/holding/holdingvalue"
 	"github.com/bufdev/ibctl/cmd/ibctl/internal/command/holding/lot"
@@ -21,6 +22,7 @@ func NewCommand(name string, builder appext.SubCommandBuilder) *appcmd.Command {
 		Short: "Display holding information",
 		SubCommands: []*appcmd.Command{
 			category.NewCommand("category", builder),
+			geo.NewCommand("geo", builder),
 			holdinglist.NewCommand("list", builder),
 			lot.NewCommand("lot", builder),
 			holdingvalue.NewCommand("value", builder),

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

@@ -93,6 +93,7 @@ func run(ctx context.Context, container appext.Container, flags *flags) error {
 		ibctlpath.ActivityStatementsDirPath(config.DirPath),
 		ibctlpath.SeedDirPath(config.DirPath),
 		config.AccountAliases,
+		config.Additions,
 	)
 	if err != nil {
 		return err
@@ -144,7 +145,7 @@ func run(ctx context.Context, container appext.Container, flags *flags) error {
 		totalsRow := make([]string, len(headers))
 		totalsRow[0] = "TOTAL"
 		totalsRow[6] = totals.MarketValueUSD
-		totalsRow[7] = totals.UnrealizedPnLUSD
+		totalsRow[7] = totals.PnLUSD
 		totalsRow[8] = totals.STCGUSD
 		totalsRow[9] = totals.LTCGUSD
 		return cliio.WriteTableWithTotals(writer, headers, sections, totalsRow)

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

@@ -83,6 +83,7 @@ func run(ctx context.Context, container appext.Container, flags *flags) error {
 		ibctlpath.ActivityStatementsDirPath(config.DirPath),
 		ibctlpath.SeedDirPath(config.DirPath),
 		config.AccountAliases,
+		config.Additions,
 	)
 	if err != nil {
 		return err

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

@@ -96,6 +96,7 @@ func run(ctx context.Context, container appext.Container, flags *flags) error {
 		ibctlpath.ActivityStatementsDirPath(config.DirPath),
 		ibctlpath.SeedDirPath(config.DirPath),
 		config.AccountAliases,
+		config.Additions,
 	)
 	if err != nil {
 		return err
@@ -123,7 +124,7 @@ func run(ctx context.Context, container appext.Container, flags *flags) error {
 		totalsRow[9] = totals.PnLUSD
 		totalsRow[10] = totals.STCGUSD
 		totalsRow[11] = totals.LTCGUSD
-		totalsRow[12] = totals.ValueUSD
+		totalsRow[12] = totals.MktValUSD
 		return cliio.WriteTableWithTotals(writer, headers, rows, totalsRow)
 	case cliio.FormatCSV:
 		headers := ibctlholdings.LotListHeaders()