FiscalFox CLI

UK Capital Gains Tax calculator for the command line. Deterministic, HMRC-compliant, agent-friendly.

Built for individual investors filing Self Assessment. Supports direct broker file parsing — no manual data entry needed.

Install

npm install -g fiscalfox

Or run without installing:

npx fiscalfox version

Requires Node.js 20+.

Quick Start

# Validate your broker export
fiscalfox validate trading212.csv --pretty

# Calculate CGT for the 2024/25 tax year
fiscalfox run trading212.csv --tax-year 2024/25 --income 55000 --sa108 --pretty

# Multiple broker files at once
fiscalfox run trading212.csv vanguard.xlsx --tax-year 2024/25 --income 55000 --sa108 --pretty --out ./results

Example Output

Capital Gains Tax Summary — 2024/25
────────────────────────────────────
Total disposals:        12
Disposal proceeds:      £24,350.00
Allowable costs:        £18,200.00
Total gains:            £6,150.00
Total losses:           £0.00
Net gain:               £6,150.00
Annual exemption used:  £3,000.00
Taxable gain:           £3,150.00
Estimated CGT:          £567.00

Supported Brokers

| Broker | Format | Auto-detected | |--------|--------|:---:| | Trading212 | CSV | Yes | | Freetrade | CSV | Yes | | InvestEngine | CSV | Yes | | Hargreaves Lansdown | CSV | Yes | | Vanguard | XLSX | Yes | | Saxo | XLSX | Yes | | eToro | XLSX | Yes |

Files from unsupported brokers can be converted to JSON using the input schema.

Commands

fiscalfox run <file...>

Calculate capital gains tax from one or more transaction files.

| Flag | Description | Required | |------|-------------|:---:| | --tax-year | UK tax year, e.g. 2024/25 | Yes | | --income | Annual income in GBP (for correct CGT rate) | Yes | | --sa108 | Include SA108 Self Assessment box values | No | | --out <dir> | Output directory (default: ./results) | No | | --pretty | Pretty-print JSON output | No | | --json-only | Write JSON artifacts only (skip CSV/TXT/MD) | No | | --no-stock-splits | Disable automatic stock split adjustments | No | | --verbose | Debug logging to stderr | No |

Output artifacts (written to --out directory):

• cgt-calculation.json — Full structured result
• normalized-transactions.json — All input transactions after normalization
• disposals.json / disposals.csv — Individual disposal records with gain/loss
• section104-pools.json — Remaining holdings with cost basis
• sa108.json / sa108.csv — Self Assessment box values (when --sa108)
• report.md / summary.txt — Human-readable summaries

fiscalfox validate <file...>

Validate input files without running a calculation.

| Flag | Description | |------|-------------| | --pretty | Pretty-print output |

fiscalfox schema [input|output|all]

Print the JSON schema for input transactions or calculation output.

| Flag | Description | |------|-------------| | --pretty | Pretty-print output |

fiscalfox version

Print the CLI version.

JSON Input

For unsupported brokers, provide a JSON array of transactions:

[
  {
    "date": "2024-06-15",
    "type": "buy",
    "ticker": "AAPL",
    "units": 10,
    "price": 150.00,
    "total": 1500.00,
    "platform": "AJ Bell"
  }
]

Required fields: date, type (buy/sell), ticker, units, price, total, platform

Optional fields: id, name, fees, fileSource, warning, isFreeshare

Run fiscalfox schema input --pretty for the full schema.

Use with Claude Code

FiscalFox is designed to work as a tool for AI coding agents. The package includes an AGENT.md file with detailed instructions for Claude Code and other LLM agents.

When using Claude Code, the agent can:

• Parse exports from any broker (not just the 7 built-in ones)
• Convert unfamiliar file formats to JSON automatically
• Run calculations and explain results in plain English
• Answer follow-up questions about your gains, losses, and holdings

See AGENT.md for the full agent instructions.

Stock Splits

The CLI automatically adjusts historical transactions for known stock splits (AMZN, GOOGL, NVDA, AAPL, TSLA, SHOP, PANW, WMT, CMG, FAST, COKE, IBKR, ORLY). Use --no-stock-splits to disable.

Tax Years

| Tax Year | Annual Exemption | CGT Rates (Basic / Higher) | |----------|-----------------|---------------------------| | 2025/26 | £3,000 | 18% / 24% | | 2024/25 | £3,000 | 10%/20% (before 30 Oct) — 18%/24% (from 30 Oct) | | 2023/24 | £6,000 | 10% / 20% | | 2022/23 | £12,300 | 10% / 20% |

Links

• Website: fiscal-fox.com
• License: Proprietary — see LICENSE