User Guide - Rebalancly Portfolio Rebalancer

Getting Started

The fastest path to your report is the wizard. No CSV manipulation, no manual file editing required.

1. Run the wizard

Go to the Import Wizard. Upload a CSV position export from your brokerage (Fidelity, Schwab, Vanguard, and more). The wizard reads your holdings, asks a few questions about your targets and report type, and generates a PDF rebalancing report in under two minutes.

No account connection needed. Just export a positions CSV from your broker's website and bring it here. Nothing is stored on our servers.

2. Save your config file (optional but recommended)

Before downloading your PDF, the wizard gives you the option to download your portfolio config file (.yaml). This file is a side product of the report. It captures your holdings, target allocation, and report settings in a simple text format.

Save it. You'll use it next time to skip the wizard entirely.

3. Re-use next time — skip the wizard

When your holdings haven't changed much, upload your saved config file directly from the home page. The engine reads it and generates your report instantly — no CSV, no wizard, no re-entering your settings.

When your holdings do change (new purchases, account changes), either run the wizard again with a fresh CSV or update the config file manually. The Advanced section below explains every field.

Advanced — Editing Your Config File

This section is for users who want to customize their config file beyond what the wizard produces: changing target allocations, adding real estate, adjusting drift bands, or building a config from scratch. The wizard generates a valid starting point; the sections below explain every field.

File Structure Overview

A portfolio file has this top-level shape:

target_equity_debt_ratio: 70/30     # e.g. 80/20, 70/30, 60/40
taxable_sales_allowed: true         # true or false
annual_income: 180000               # for STCG / LTCG tax estimates

target_equity:
  VTI:
    pct: 50

target_debt:
  AGG:
    pct: 20

accounts:
  - name: Individual
    ...

Fields Reference

Field	Description
target_equity_debt_ratio	Target split between equity and bonds, written as `equity%/debt%`. Example: `70/30`. Both sides must sum to 100.
taxable_sales_allowed	`true` or `false`. Whether the engine can recommend selling in taxable accounts. Set to `false` to avoid triggering capital gains — the engine will only suggest buys and tax-free trades.
annual_income	Your gross annual income. Used to calculate your federal tax bracket for STCG and LTCG estimates in the Tax Notes section. Without it, tax cost columns show `??`. Accepts commas and `$`: `$180,000`. Required for `report_type: full`.
target_equity	Map of equity tickers to their target percentage of the total investable portfolio. See target_equity / target_debt.
target_debt	Map of bond tickers to target percentages. Same structure as `target_equity`. Omit only if you hold no bonds.
accounts	List of brokerage accounts with holdings. At least one account required. See accounts.
drift_band_taxfree	Optional. Minimum drift % before the engine trades in tax-advantaged (Roth / deferred) accounts. Default: `2`. Minimum: `0.5`. See Drift Bands.
drift_band_taxable	Optional. Minimum drift % before the engine sells in taxable accounts. Default: `5`. Minimum: `0.5`. See Drift Bands.
report_type	Optional. `rebalance` (default) or `full`. See Report Types for what each includes and which extra fields are required.
dob_year	Your birth year as a 4-digit number. Example: `1985`. Used for age-based risk scoring. Required for `report_type: full`.
retirement_age	Optional. Your planned retirement age. Defaults to `67` if not set — the report will show a notice when the default is assumed. Used for risk capacity scoring.
name_initials	Optional. Your initials, shown on the report cover. Example: `NC`.

target_equity / target_debt

Both maps have identical structure: a ticker symbol key and a pct value.

Field	Type	Description
pct	number	Target percentage of the total investable portfolio this ticker should represent. All equity pcts + all debt pcts must sum to 100 (or match the ratio in `target_equity_debt_ratio`).

target_equity:
  VTI:   pct: 50    # 50% total portfolio in VTI
  VEA:   pct: 15
  VWO:   pct: 5
  QQQ:   pct: 10

target_debt:
  AGG:   pct: 15
  SCHR:  pct: 5

The equity percentages (50+15+5+10 = 80) plus debt percentages (15+5 = 20) equal 100, matching target_equity_debt_ratio: 80/20.

accounts

A list of all your brokerage and investment accounts. Each account must have at minimum: name, type, company, and either holdings or cash_holding.

Field	Required	Description
name	required	Display name shown in the report. e.g. `Roth IRA`, `Individual Taxable`.
type	required	Account tax type. One of: `taxable`, `roth`, `deferred`. See Account Types.
company	required	Broker name for display. e.g. `Fidelity`, `Schwab`, `Vanguard`.
holdings	optional*	List of ticker holdings in this account. Required unless `cash_holding` is used instead.
cash_holding	optional	Dollar amount of cash or cash-equivalent in this account. Use for CD or cash-only accounts. Can be combined with `holdings`.
cash_to_deploy	optional	Amount of cash within this account to deploy into investments. The engine will recommend buys for this amount. Must be ≤ available cash in the account.

accounts:
  - name: Individual Taxable
    type: taxable
    company: Fidelity
    cash_to_deploy: 5000
    holdings:
      - ticker: VTI
        shares: 200
      - ticker: SPAXX
        shares: 12000

other_assets

Use other_assets for assets you want tracked in net worth but that are not part of rebalancing — CDs, 529 education funds, I-bonds, and similar cash-equivalent holdings.

Field	Required	Description
name	required	Display name. e.g. `529 Education Fund`, `18-Month CD`.
description	optional	Free-text note shown in the net worth table. e.g. `Fidelity CD, matures 2026-12`.
cash_holding	required	Current dollar value. Accepts commas: `85,000`.

other_assets:
  - name: 529 Education Fund
    description: College savings plan (Fidelity)
    cash_holding: 85000

  - name: 18-Month CD
    description: Certificate of Deposit (Marcus), matures 2026-12
    cash_holding: 50000

other_assets appear as individual line items in the Net Worth table (Full Report only). They do not affect debt/equity allocation calculations.

holdings

Each entry in a holdings list represents one ticker position within the account.

Field	Required	Description
ticker	required	Ticker symbol. e.g. `VTI`, `SPAXX`, `QQQ`. Money market tickers (SPAXX, VMFXX, FDRXX, FZFXX, FMPXX, CORE, FCASH) are automatically treated as cash at $1.00.
shares	required	Number of shares held. Decimals are accepted for fractional shares.

holdings:
  - ticker: VTI
    shares: 200
  - ticker: QQQ
    shares: 50.5    # decimals OK for fractional shares
  - ticker: SPAXX   # money market — always $1.00, treated as cash
    shares: 12000

Account Types

The type field on each account controls how the engine treats it for tax purposes and asset placement rules.

type value	Account Examples	Behavior
taxable	Individual brokerage, joint account	Selling triggers capital gains. Buys and sells here are subject to STCG/LTCG rules. Broad equity (VTI, VEA) is ideally placed here for qualified dividend treatment.
roth	Roth IRA, Roth 401(k)	Tax-free growth. Ideal for high-growth tickers (QQQ, VUG, MGK). The engine prioritizes growth ETFs in Roth accounts.
deferred	Traditional IRA, 401(k), Rollover IRA, SEP-IRA	Tax-deferred. Ideal for bonds and fixed income (AGG, BND, SCHR). No capital gains on internal trades.

Report Types

Set report_type at the top of your YAML file. The value controls which sections appear in the PDF and which fields are mandatory.

report_type	Sections included	Required fields
`rebalance` (default)	Executive Summary · Recommended Swaps · Tax Notes · Step-by-Step Trades · Asset Location · Expense Ratio · Overlap · Concentration · Engine Philosophy · Disclaimer	`target_equity_debt_ratio` `target_equity` `accounts`
`full`	Everything in Rebalance, plus: Net Worth · Risk Deep Dive · 5-Year Performance · Monte Carlo Simulation · Compound Growth Projections	Everything above, plus: `dob_year` — birth year for age & risk scoring `annual_income` — income for tax bracket & risk scoring

Generating a Rebalance Report (minimum fields)

report_type: rebalance             # optional — this is the default
target_equity_debt_ratio: 70/30
taxable_sales_allowed: true

target_equity:
  VTI:   pct: 50
  QQQ:   pct: 20

target_debt:
  AGG:   pct: 30

accounts:
  - name: Individual
    type: taxable
    company: Fidelity
    holdings:
      - ticker: VTI
        shares: 100

Generating a Full Report (extra mandatory fields)

report_type: full                   # unlocks Net Worth, Risk, Performance
dob_year: 1985                      # REQUIRED for full — birth year
annual_income: 180000              # REQUIRED for full — gross income
retirement_age: 65                  # optional — defaults to 67 if omitted
name_initials: NC                   # optional — appears on report cover
target_equity_debt_ratio: 70/30
taxable_sales_allowed: true

target_equity:
  VTI:   pct: 50
  QQQ:   pct: 20

target_debt:
  AGG:   pct: 30

other_assets:                       # optional — shown in Net Worth only
  - name: 529 Education Fund
    cash_holding: 85000

accounts:
  - name: Individual
    type: taxable
    company: Fidelity
    holdings:
      - ticker: VTI
        shares: 100

If you set report_type: full but omit dob_year or annual_income, the engine will return an error listing exactly which fields are missing rather than generating a report with gaps.

Tips & Common Patterns

Money Market / Cash Tickers

The following tickers are automatically recognized as cash and valued at $1.00 per share:

SPAXX VMFXX FDRXX FZFXX FMPXX CORE FCASH

Dollar Formatting

Any dollar amount field accepts commas and $ signs:

annual_income: $180,000       # same as 180000
cash_holding: $50,000.00

Deploying Cash

Use cash_to_deploy on an account when you have cash sitting uninvested and want the engine to include it in buy recommendations. Do not include the cash amount separately as a holding, as it will be double-counted.

- name: Individual
  type: taxable
  company: Fidelity
  cash_to_deploy: 10000        # $10k to invest
  holdings:
    - ticker: SPAXX
      shares: 15000             # $15k total cash — $10k will be deployed

Tracking CDs, 529s, and Other Non-Investable Assets

Use the top-level other_assets list for any asset you want tracked in net worth but not included in rebalancing — CDs, education funds, I-bonds, etc.:

other_assets:
  - name: 529 Education Fund
    description: College savings plan (Fidelity)
    cash_holding: 85000

  - name: 18-Month CD
    description: Certificate of Deposit (Marcus)
    cash_holding: 50000

Blocking Taxable Sales

If you want to avoid triggering capital gains (e.g., late in the tax year), set taxable_sales_allowed: false. The engine will only recommend buys and tax-free account trades:

taxable_sales_allowed: false

Adjusting Drift Bands

The engine uses two separate drift thresholds to decide when a holding is far enough off-target to trigger a trade recommendation:

Parameter	Default	Applies to	Description
`drift_band_taxfree`	2%	Tax-advantaged accounts (Roth IRA, Traditional IRA, 401k, etc.)	Tighter band — trades in these accounts are tax-free, so the engine acts sooner.
`drift_band_taxable`	5%	Taxable brokerage accounts	Wider band — the engine waits for a larger drift before triggering a potentially taxable sale.

Add these optional fields at the top level of your YAML to override the defaults:

drift_band_taxfree: 3    # default 2 — raise to tolerate more drift in tax-advantaged accounts
drift_band_taxable: 7    # default 5 — raise to further reduce taxable trades

Minimum value for either band is 0.5%. Values below 0.5% cannot be closed by whole-share trades and will trigger false warnings.

Full Examples

Copy or download these pre-built examples as a starting point:

Minimal Valid Portfolio

The absolute minimum. Prices fetched live from Yahoo Finance.

target_equity_debt_ratio: 80/20

taxable_sales_allowed: true

annual_income: 120000

target_equity:
  VTI:
    pct: 80

target_debt:
  AGG:
    pct: 20

accounts:
  - name: Individual
    type: taxable
    company: Fidelity
    holdings:
      - ticker: VTI
        shares: 100
      - ticker: AGG
        shares: 50

Sample File — Power Users

Prefer to hand-craft your own config instead of using the wizard? Download this ready-to-edit starting point and fill in your own holdings:

📄 Download sample_full.yaml

6 accounts (Taxable, Roth IRA, Traditional IRA, Rollovers) + real estate + other assets, 90/10 target — Full Report