Enum WhatIf 

pub enum WhatIf {
    Sell {
        sell: String,
        wallet: Option<String>,
        at: Option<String>,
        price: Option<String>,
        method: Option<MethodLotArg>,
        filing_status: Option<FilingStatusArg>,
        income: Option<String>,
        magi: Option<String>,
        carryforward_in: Option<String>,
    },
    Harvest {
        target: String,
        wallet: Option<String>,
        at: Option<String>,
        price: Option<String>,
        filing_status: Option<FilingStatusArg>,
        income: Option<String>,
        magi: Option<String>,
        carryforward_in: Option<String>,
    },
}

what-if subcommand tree (task #43). READ-ONLY hypothetical-transaction tax planning: NOTHING is filed, appended, or persisted. Mirrors the optimize consult shape, plus an ad-hoc TaxProfile (so you can plan without tax-profile set).

Variants

Sell

Posit a hypothetical, NON-persisted SALE and see its MARGINAL federal tax: the lots it would consume, the ST/LT split, which §1(h) LTCG bracket (0/15/20) it lands in + room to the next breakpoint, the exact marginal tax (with-hypothetical minus baseline — the sale’s OWN effect, not the whole-year figure), the effective rate, the §1212(b) carryforward carried to next year, this year’s ordinary offset, and the §1411 NIIT delta. A net loss surfaces the carryforward disclosure (its value is NOT this-year tax). Writes NOTHING.

Fields

sell: String

Hypothetical sale amount (required). Accepts a satoshi integer OR a BTC decimal, e.g. 0.05 or 5000000 (a value with a . is BTC; a bare integer is satoshis).

wallet: Option<String>

Wallet to sell from, e.g. self:cold or exchange:coinbase:default (required; the per-wallet pool is mandatory post-2025).

at: Option<String>

Sale date for the what-if (YYYY-MM-DD; defaults to today UTC if omitted).

price: Option<String>

USD price per WHOLE BTC for the hypothetical sale (proceeds = price × sat / 1e8). Omit to use the bundled daily-close FMV for --at; REQUIRED for a future/off-dataset --at with no bundled price (else the what-if returns a ProceedsRequired error).

method: Option<MethodLotArg>

Lot-selection method for the hypothetical sale: fifo|lifo|hifo. Omit to consume by the STANDING method (the account’s in-force election / the default), exactly as a real disposal on that date would.

filing_status: Option<FilingStatusArg>

AD-HOC filing status (single|mfj|mfs|hoh|qss). Supplying this (with --income) builds a NON-persisted profile for the plan instead of the stored tax-profile. Omit ALL ad-hoc flags to use the stored profile for the sale year.

income: Option<String>

AD-HOC ordinary taxable income EXCLUDING crypto (the base the crypto stacks on). Required when building an ad-hoc profile.

magi: Option<String>

AD-HOC modified AGI excluding crypto, for the §1411 NIIT threshold. DEFAULTS TO --income when omitted (never $0 — a $0 MAGI would silently suppress every NIIT disclosure); a printed caveat notes the assumption. Supply the true MAGI (incl. QD + non-crypto cap gains) to avoid understating NIIT.

carryforward_in: Option<String>

AD-HOC §1212(b) LONG-TERM capital-loss carryforward INTO the sale year (optional; defaults to $0). The dominant BTC case; short-term carryforward-in is out of scope for the ad-hoc profile (set a stored tax-profile for that).

Harvest

Posit a hypothetical, NON-persisted HARVEST and find the MAX BTC to sell such that a target holds on the ENTIRE prefix [0, N]: --target zero-ltcg (sell all that fits in the §1(h) 0% bracket), fifteen-ltcg (stay at/under 15%), gain=$X (realize at most $X of gain WITH this sale), or tax=$X (add at most $X of marginal federal tax; tax=$0 is the flagship “zero-tax harvest”). Uses the STANDING lot method’s consumption order (never re-optimized). Discloses the §1212(b) carryforward burn, the §1411 NIIT kink (a 0%/15% answer can still cost +3.8%), and the plateau notes. The answer is ALWAYS engine-verified. Writes NOTHING.

Fields

target: String

The harvest target: zero-ltcg | fifteen-ltcg | gain=$X | tax=$X (X >= 0). $ and commas are optional (e.g. gain=25000, tax=$0, gain=$1,000).

wallet: Option<String>

Wallet to harvest from, e.g. self:cold or exchange:coinbase:default (required; the per-wallet pool is mandatory post-2025).

at: Option<String>

Harvest date for the what-if (YYYY-MM-DD; defaults to today UTC if omitted).

price: Option<String>

USD price per WHOLE BTC. Omit to use the bundled daily-close FMV for --at; REQUIRED for a future/off-dataset --at with no bundled price.

filing_status: Option<FilingStatusArg>

AD-HOC filing status (single|mfj|mfs|hoh|qss). Supplying this (with --income) builds a NON-persisted profile for the plan instead of the stored tax-profile. Omit ALL ad-hoc flags to use the stored profile for the harvest year.

income: Option<String>

AD-HOC ordinary taxable income EXCLUDING crypto (the base the crypto stacks on). Required when building an ad-hoc profile.

magi: Option<String>

AD-HOC modified AGI excluding crypto, for the §1411 NIIT threshold. DEFAULTS TO --income when omitted (never $0 — a $0 MAGI would silently suppress every NIIT disclosure); a printed caveat notes the assumption.

carryforward_in: Option<String>

AD-HOC §1212(b) LONG-TERM capital-loss carryforward INTO the harvest year (optional; defaults to $0) — expands the harvestable-gain room (gains are absorbed before touching the pref stack).

Trait Implementations

impl FromArgMatches for WhatIf

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut<'b>( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Subcommand for WhatIf

fn augment_subcommands<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_subcommands_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

fn has_subcommand(__clap_name: &str) -> bool

Test whether Self can parse a specific subcommand