cgt-visualiser
v0.7.2
Published
UK capital gains tax calculator for share transactions from broker CSV exports. Applies HMRC same-day, 30-day and Section 104 matching rules. Runs locally; your data never leaves your machine.
Maintainers
Readme
cgt-visualiser
UK capital gains tax on shares, calculated from your broker's CSV exports. It applies HMRC's share matching rules: same-day, 30-day ("bed and breakfast") and Section 104 pooling. It also handles foreign-currency conversion and stock splits.
It runs on your machine and never uploads your transactions. The calculation engine is the same one used by the Capital Gains Tax Visualiser web app.
npx cgt-visualiser calculate schwab.csv trading212.csv --tax-year 2025/26Requires Node.js 22 or later.
Commands
| Command | What it does |
|---|---|
| calculate <files...> | Calculate gains and losses for every tax year, or one year with --tax-year 2025/26 |
| detect <files...> | Show which broker format each file is, without calculating |
| brokers | List supported brokers and how to export the right file from each |
| normalize <files...> -o out.csv | Convert exports into one Generic CSV that you can edit (fix or add rows), then pass to calculate. It refuses files with options or short sells, which the Generic CSV format can't represent |
Run cgt-visualiser --help for all options. The main options are:
--fx hmrc-monthly|hmrc-yearly|daily-spot: the exchange rate source. The default is HMRC monthly rates.--details: for each disposal, show the matched acquisitions, the FX rate used and the Section 104 pool before and after.--format text|json|csv|pdf: the output format. The default istextin a terminal andjsonwhen the output is piped.--format pdf --tax-year 2025/26 -o report.pdf: write one tax year's PDF report, the same as the web app's Export PDF button. Add--include-transactionsto list every transaction up to the year end.--offline: make no network requests. HMRC rates for past months and years are bundled, so they work offline; newer rates and daily rates come from the cache only.--strict: exit with code 3 if there are any warnings.
Exit codes: 0 success, 1 usage error, 2 a file couldn't be read or recognised, 3 warnings with --strict.
Supported brokers
The supported brokers are Charles Schwab (including Equity Awards), Interactive Brokers, Trading 212, Freetrade, EquatePlus, Revolut, Coinbase and Coinbase Pro, plus a Generic CSV format for anything else. Run cgt-visualiser brokers for export instructions.
Privacy
The only network requests are for public reference data: HMRC or ECB exchange rates and stock split data. They never include your transactions. Fetched data is cached in ~/.cache/cgt-visualiser. Set CGT_VISUALISER_CACHE_DIR to use a different directory, or pass --no-cache to turn the cache off.
JSON output (--format json)
The output is versioned with schemaVersion: 1. New fields may be added within a version. Fields are only removed, renamed or changed in meaning with a new schemaVersion.
| Field | Contents |
|---|---|
| options, inputs | What was calculated, including each file's detected broker and transaction count |
| taxYears[] | One entry per year: disposals, proceeds, allowable costs, gains, losses (as a positive number), net gain, annual exempt amount and taxable gain, plus dividend and interest totals |
| taxYears[].sa108 | The figures the SA108 "listed shares and securities" section asks for (listed shares and funds only; proceeds are gross, with selling fees in allowable costs). Fields are named rather than numbered because box numbers change between years |
| taxYears[].sa108Sections | One entry per SA108 section with disposals (listed-shares, crypto, options), with box numbers for that year where known. Options have no section or boxes: it depends on the contract |
| taxYears[].rateChange2024 | 2024/25 only: gains and losses before and after the 30 October 2024 rate change; chargeableGainsAfterGbp, the post-change gains left after the year's losses and the annual exempt amount are set against them first (TCGA92/S4B); and adjustmentRequired, true only when that is above zero |
| disposals[] | One row per disposal: date, symbol, split-adjusted quantity, proceeds, cost, gain or loss, matching rules used, an incomplete flag, and missingFx: true when the gain uses a missing exchange rate. --details adds the full audit trail |
| section104Pools[] | Holdings remaining after the last imported transaction |
| warnings[] | Problems to resolve, each with a code and the affected transactionIds. Codes: FX_RATE_MISSING, INCOMPLETE_DISPOSAL (sales with no recorded purchase, often because the history starts too late), SPLIT_DATA_UNAVAILABLE (stock split data couldn't be fetched, so unrecorded splits weren't applied), SPLIT_DATA_REJECTED (fetched split data for a held share failed validation and wasn't applied), SPLIT_WITHOUT_RATIO (a broker file records a stock split without its ratio and no split data covers it, so it wasn't applied), SYMBOLS_MATCHED_BY_ISIN (different tickers with the same ISIN were treated as one security), TICKER_ISIN_CONFLICT (one ticker appears with different ISINs), SKIPPED_ROWS (rows that couldn't be read, such as a Generic CSV row with a missing date or an unrecognised type, were left out; rows are numbered as a spreadsheet shows them, with the header as row 1), UNKNOWN_TRANSACTION_TYPE, OVERLAPPING_ROWS_REMOVED (rows repeated in another file from the same broker were counted once), SPLIT_RATIO_CONFLICT (two records of the same stock split gave different ratios; the earliest was used), DUPLICATE_FILE, TAX_YEAR_NOT_FOUND. With --tax-year, FX_RATE_MISSING and UNKNOWN_TRANSACTION_TYPE still cover every year, because an earlier problem changes the Section 104 pool cost used later |
All amounts are in GBP and rounded to the penny.
Disclaimer
This is not tax advice. Figures are calculated from HMRC guidance and may be wrong or incomplete. Check them, for example by loading the same files in the web app, and consult HMRC helpsheet HS284 or a qualified adviser before filing.
License
MIT
