How to Use the FiscalFox CLI with AI Agents

    Paste one command into your AI agent, point it at your broker files, and get your capital gains calculated.

    Updated 25 February 20263 min read

    The FiscalFox CLI calculates UK Capital Gains Tax using the same HMRC-compliant engine as the FiscalFox web app. It is designed to be used by AI coding agents. The process is simple: paste the npx command into your agent, point it at your broker files, and the agent handles the rest.

    No AI is involved in the tax calculation itself - the maths follows HMRC's share matching rules (TCGA 1992) exactly. The agent only handles parsing your broker file. The calculation is deterministic, auditable, and reproducible.

    Three steps. That's it.

    1. Paste this into your AI agent

    Open Claude Code, Cursor, Windsurf, GitHub Copilot - any agent that can run terminal commands. Then paste:

    npx fiscalfox --help

    No install needed. npx downloads and runs it instantly. The agent now has access to the FiscalFox CLI and knows what commands are available.

    2. Point the agent to your broker files

    Tell the agent where your transaction file is and what you want. For example:

    Example prompt

    "Use all the files in ./tax-files to calculate my capital gains for 2025/26"

    The agent reads your file, figures out the columns, normalizes the data, and runs the calculation. It handles every broker format - Trading 212, Vanguard, Hargreaves Lansdown, Freetrade, eToro, InvestEngine, Moneybox, or anything else with a CSV or XLSX export.

    3. Get your results

    The agent extracts everything you need for your tax return:

    • Every disposal with the matching rule applied (same-day, 30-day, Section 104)
    • Total gains and losses
    • Taxable gain after the annual exempt amount
    • Estimated CGT liability
    • SA108 Self Assessment box values - ready to copy into your return

    Example session

    $ claude
    > I have a Trading 212 CSV at ./t212-2024.csv.
      Calculate my capital gains for 2024/25.
      My income is £45,000. Generate SA108 values.
    
    # The agent reads your CSV, parses it, and runs:
    
    $ npx fiscalfox run trades.json \
        --tax-year 2024/25 \
        --income 45000 \
        --sa108 \
        --out ./results
    
    # Total disposals: 12
    # Total gains: £4,820.50
    # Total losses: £310.00
    # Net gain: £4,510.50
    # Annual exempt amount: £3,000.00
    # Taxable gain: £1,510.50
    # Estimated CGT: £271.89 (18% basic rate)
    # SA108 values written to ./results/sa108.json

    Deterministic and auditable

    The CLI applies the same HMRC share matching rules as the FiscalFox web app: the same-day rule (TCGA 1992 s.105), the 30-day bed and breakfast rule (s.106A), and Section 104 pooling (s.104). The same input always produces the same output - no AI randomness in the calculation. Every disposal records which matching rule was applied.

    Compatible agents

    Any AI agent that can read files and run terminal commands works with FiscalFox CLI:

    • Claude Code - Run claude in your terminal
    • Cursor - Open your folder, use the agent chat panel
    • GitHub Copilot - Copilot Chat in VS Code with terminal access
    • Windsurf - Open your folder, use Cascade

    Tips

    • Include your income - so the CLI can determine your basic or higher rate.
    • Ask for SA108 values - the exact box values you need for Self Assessment.
    • Multiple brokers? - Give the agent all your files. The CLI merges and calculates across all holdings.
    • Keep the output files - the detailed computation in disposals.json is your supporting evidence if HMRC queries your return.

    Ready to calculate your capital gains?

    Upload your broker CSV files and get HMRC-ready reports in minutes. Start free - no credit card required.