commit

Author: bufdev

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

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

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

@@ -0,0 +1,263 @@
+// Copyright 2026 Peter Edge
+//
+// All rights reserved.
+
+// Package coveredcalllist implements the "holding covered-call list" command.
+// It screens existing equity holdings for covered call opportunities by
+// fetching options chain data from a configured provider (marketdata.app
+// or Yahoo Finance) and displaying filtered, ranked suggestions.
+package coveredcalllist
+
+import (
+	"context"
+	"fmt"
+	"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/ibctlcoveredcall"
+	"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/ibctloptions"
+	"github.com/bufdev/ibctl/internal/ibctl/ibctlpath"
+	"github.com/bufdev/ibctl/internal/ibctl/ibctlrealtime"
+	"github.com/bufdev/ibctl/internal/pkg/cliio"
+	"github.com/bufdev/ibctl/internal/pkg/optionsdata"
+	"github.com/bufdev/ibctl/internal/pkg/yahoofinance"
+	"github.com/spf13/pflag"
+)
+
+// NewCommand returns a new covered call list command.
+func NewCommand(name string, builder appext.SubCommandBuilder) *appcmd.Command {
+	flags := newFlags()
+	return &appcmd.Command{
+		Use:   name,
+		Short: "List covered call opportunities on existing holdings",
+		Long: `Screen existing equity holdings for covered call opportunities.
+
+Fetches options chain data from the configured provider and displays OTM call
+options ranked by annualized premium yield. Only positions with ≥100 shares of
+USD-denominated equities are eligible.
+
+PROVIDERS
+
+Configure market_data_providers in ibctl.yaml to set the options data source:
+  - marketdata_app: Data with greeks (delta, theta). Requires
+    MARKETDATA_APP_TOKEN environment variable.
+  - polygon: Data with greeks (delta, theta). Unlimited API calls. Requires
+    POLYGON_TOKEN environment variable.
+  - yahoo: Free, no auth required. No greeks (delta, theta columns hidden).
+
+Default: ["yahoo"]. The first provider in the list is used.
+
+COLUMNS
+
+  SYMBOL       Underlying ticker
+  PRICE        Current stock price
+  STRIKE       Option strike price
+  EXPIRY       Expiration date (YYYY-MM-DD)
+  DAYS         Days to expiration
+  % OTM        Distance from current price to strike (%)
+  BID          Option bid price per share
+  ASK          Option ask price per share
+  MID          Midpoint of bid/ask
+  CONTRACTS    Number of contracts you can sell (position / 100)
+  TOTAL PREM   Total premium if all contracts sold (contracts * 100 * mid)
+  ANN YIELD    Annualized yield (mid / price * 365 / days * 100)
+  VOLUME       Option trading volume
+  OPEN INT     Open interest
+  IV           Implied volatility (%)
+  DELTA        Option delta (marketdata_app only)
+  THETA        Daily time decay per share (marketdata_app only)`,
+		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
+	// MinOTMPercent is the minimum % out of the money for the strike.
+	MinOTMPercent float64
+	// MaxOTMPercent is the maximum % out of the money for the strike.
+	MaxOTMPercent float64
+	// MinDays is the minimum days to expiration.
+	MinDays int
+	// MaxDays is the maximum days to expiration.
+	MaxDays int
+	// MinOpenInterest is the minimum open interest for liquidity filtering.
+	MinOpenInterest int64
+	// Symbol filters to a specific symbol (empty = all eligible).
+	Symbol string
+	// Sort controls the sort order (yield, premium, otm, expiry).
+	Sort 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.Format, "format", "table", "Output format (table, csv, json)")
+	flagSet.BoolVar(&f.Download, "download", false, "Download fresh data before displaying")
+	flagSet.StringVar(&f.BaseCurrency, "base-currency", "USD", "Base currency for value conversion (e.g., USD, CAD)")
+	flagSet.BoolVar(&f.Realtime, "realtime", false, "Fetch real-time quotes and FX rates from Yahoo Finance")
+	flagSet.Float64Var(&f.MinOTMPercent, "min-otm-pct", 3, "Minimum % out of the money for strike")
+	flagSet.Float64Var(&f.MaxOTMPercent, "max-otm-pct", 50, "Maximum % out of the money for strike")
+	flagSet.IntVar(&f.MinDays, "min-days", 14, "Minimum days to expiration")
+	flagSet.IntVar(&f.MaxDays, "max-days", 45, "Maximum days to expiration")
+	flagSet.Int64Var(&f.MinOpenInterest, "min-open-interest", 10, "Minimum open interest (liquidity filter)")
+	flagSet.StringVar(&f.Symbol, "symbol", "", "Filter to a specific symbol")
+	flagSet.StringVar(&f.Sort, "sort", "yield", "Sort by: yield, premium, otm, expiry")
+}
+
+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())
+	}
+	sortField, err := ibctlcoveredcall.ParseSortField(flags.Sort)
+	if err != nil {
+		return appcmd.NewInvalidArgumentError(err.Error())
+	}
+	// Validate that min/max ranges are consistent.
+	if flags.MinOTMPercent > flags.MaxOTMPercent {
+		return appcmd.NewInvalidArgumentErrorf("--min-otm-pct (%.1f) must be <= --max-otm-pct (%.1f)", flags.MinOTMPercent, flags.MaxOTMPercent)
+	}
+	if flags.MinDays > flags.MaxDays {
+		return appcmd.NewInvalidArgumentErrorf("--min-days (%d) must be <= --max-days (%d)", flags.MinDays, flags.MaxDays)
+	}
+	// Normalize base currency to uppercase for case-insensitive matching.
+	baseCurrency := strings.ToUpper(flags.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
+	}
+	// Resolve the options data provider from the configured preference list.
+	// Resolve the options data provider using the app container's env lookup.
+	provider, err := ibctloptions.ResolveProvider(config.MarketDataProviders, container.Env)
+	if err != nil {
+		return err
+	}
+	container.Logger().Info("using options provider", "provider", provider.Name(), "has_greeks", provider.HasGreeks())
+	// 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 seed lots + Activity Statement CSVs + Flex Query cached data across all accounts.
+	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
+		}
+	}
+	// Compute holdings via FIFO from all trade data.
+	result, err := ibctlholdings.GetHoldingsOverview(mergedData.Trades, mergedData.Positions, mergedData.CashPositions, config, fxStore, baseCurrency)
+	if err != nil {
+		return err
+	}
+	// Filter holdings to eligible positions for covered calls.
+	// Collect symbols for options chain fetch.
+	var eligibleSymbols []string
+	for _, h := range result.Holdings {
+		if flags.Symbol != "" && h.Symbol != flags.Symbol {
+			continue
+		}
+		if h.Currency == "USD" && h.Category == "EQUITY" {
+			eligibleSymbols = append(eligibleSymbols, h.Symbol)
+		}
+	}
+	if len(eligibleSymbols) == 0 {
+		container.Logger().Info("no eligible holdings for covered calls")
+		return nil
+	}
+	// Fetch options chains for all eligible symbols from the configured provider.
+	container.Logger().Info("fetching options chains", "symbols", len(eligibleSymbols), "provider", provider.Name())
+	optionsData, err := provider.GetOptionsChains(ctx, eligibleSymbols, optionsdata.FetchParams{
+		MinDays: flags.MinDays,
+		MaxDays: flags.MaxDays,
+	})
+	if err != nil {
+		return fmt.Errorf("fetching options chains: %w", err)
+	}
+	// Compute covered call suggestions from holdings and options data.
+	suggestions := ibctlcoveredcall.GetCoveredCallSuggestions(
+		result.Holdings,
+		optionsData,
+		ibctlcoveredcall.Params{
+			MinOTMPercent:   flags.MinOTMPercent,
+			MaxOTMPercent:   flags.MaxOTMPercent,
+			MinDays:         flags.MinDays,
+			MaxDays:         flags.MaxDays,
+			MinOpenInterest: flags.MinOpenInterest,
+			SortField:       sortField,
+			HasGreeks:       provider.HasGreeks(),
+		},
+	)
+	// Write output in the requested format.
+	writer := os.Stdout
+	switch format {
+	case cliio.FormatTable:
+		headers := ibctlcoveredcall.Headers(provider.HasGreeks())
+		rows := make([][]string, 0, len(suggestions))
+		for _, s := range suggestions {
+			rows = append(rows, ibctlcoveredcall.SuggestionToTableRow(s, provider.HasGreeks()))
+		}
+		return cliio.WriteTable(writer, headers, rows)
+	case cliio.FormatCSV:
+		headers := ibctlcoveredcall.Headers(true) // CSV always includes all columns.
+		records := make([][]string, 0, len(suggestions)+1)
+		records = append(records, headers)
+		for _, s := range suggestions {
+			records = append(records, ibctlcoveredcall.SuggestionToRow(s))
+		}
+		return cliio.WriteCSVRecords(writer, records)
+	case cliio.FormatJSON:
+		return cliio.WriteJSON(writer, suggestions...)
+	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/coveredcall"
 	"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"
@@ -23,6 +24,7 @@ func NewCommand(name string, builder appext.SubCommandBuilder) *appcmd.Command {
 		Short: "Display holding information",
 		SubCommands: []*appcmd.Command{
 			category.NewCommand("category", builder),
+			coveredcall.NewCommand("covered-call", builder),
 			geo.NewCommand("geo", builder),
 			holdinglist.NewCommand("list", builder),
 			lot.NewCommand("lot", builder),

internal/ibctl/ibctlconfig/ibctlconfig.go

@@ -95,6 +95,11 @@ type ExternalConfigV1 struct {
 	// InterestRates maps currency codes to annual interest rates on cash balances.
 	// Used by projected-income to estimate cash interest income (e.g., {"USD": 0.0312}).
 	InterestRates map[string]float64 `yaml:"interest_rates"`
+	// MarketDataProviders is an ordered list of options data providers for covered call screening.
+	// Valid values: "marketdata_app" (requires MARKETDATA_APP_TOKEN env var),
+	// "polygon" (requires POLYGON_TOKEN env var), "yahoo" (free, no greeks).
+	// Default: ["yahoo"].
+	MarketDataProviders []string `yaml:"market_data_providers"`
 }
 
 // ExternalTaxConfigV1 holds capital gains tax rate configuration.
@@ -180,6 +185,9 @@ type Config struct {
 	TaxRateInterest float64
 	// CashInterestRates maps currency codes to annual interest rates on cash balances.
 	CashInterestRates map[string]float64
+	// MarketDataProviders is the ordered list of options data providers for covered call screening.
+	// Valid values: "marketdata_app", "polygon", "yahoo". Default: ["yahoo"].
+	MarketDataProviders []string
 }
 
 // SymbolConfig holds classification metadata for a symbol.
@@ -294,21 +302,35 @@ func NewConfigV1(externalConfig ExternalConfigV1, dirPath string) (*Config, erro
 	if cashInterestRates == nil {
 		cashInterestRates = make(map[string]float64)
 	}
+	// Parse and validate market data providers, defaulting to ["yahoo"] if not configured.
+	marketDataProviders := externalConfig.MarketDataProviders
+	if len(marketDataProviders) == 0 {
+		marketDataProviders = []string{"yahoo"}
+	}
+	for _, providerName := range marketDataProviders {
+		switch providerName {
+		case "marketdata_app", "polygon", "yahoo":
+			// Valid provider name.
+		default:
+			return nil, fmt.Errorf("invalid market_data_providers value %q, must be \"marketdata_app\", \"polygon\", or \"yahoo\"", providerName)
+		}
+	}
 	return &Config{
-		DirPath:            dirPath,
-		IBKRFlexQueryID:    externalConfig.FlexQueryID,
-		AccountAliases:     accountAliases,
-		AccountIDToAlias:   accountIDToAlias,
-		SymbolConfigs:      symbolConfigs,
-		CashAdjustments:    cashAdjustments,
-		TaxRateSTCG:        taxRateSTCG,
-		TaxRateLTCG:        taxRateLTCG,
-		TaxRateDividend:    taxRateDividend,
-		TaxRateInterest:    taxRateInterest,
-		Additions:          additions,
-		AdditionLastPrices: additionLastPrices,
-		RealtimeSymbols:    realtimeSymbols,
-		CashInterestRates:  cashInterestRates,
+		DirPath:             dirPath,
+		IBKRFlexQueryID:     externalConfig.FlexQueryID,
+		AccountAliases:      accountAliases,
+		AccountIDToAlias:    accountIDToAlias,
+		SymbolConfigs:       symbolConfigs,
+		CashAdjustments:     cashAdjustments,
+		TaxRateSTCG:         taxRateSTCG,
+		TaxRateLTCG:         taxRateLTCG,
+		TaxRateDividend:     taxRateDividend,
+		TaxRateInterest:     taxRateInterest,
+		Additions:           additions,
+		AdditionLastPrices:  additionLastPrices,
+		RealtimeSymbols:     realtimeSymbols,
+		CashInterestRates:   cashInterestRates,
+		MarketDataProviders: marketDataProviders,
 	}, nil
 }