A CLI tool for analyzing Interactive Brokers (IBKR) holdings and trades. Downloads data via the IBKR Flex Query API, computes FIFO tax lots, and displays holdings with prices, positions, and multi-currency conversions. Supports multiple IBKR accounts, non-IBKR broker additions, and tax reporting for both IRS and CRA.
For complete documentation, run make book to view the ibctl book locally, or browse the book/ directory.
- An Interactive Brokers account
- Go 1.25+
# Create an ibctl directory.
mkdir ~/ibkr && cd ~/ibkr
# Initialize configuration.
ibctl config init
# Edit the config to add your Flex Query ID and account aliases.
ibctl config edit
# Set the IBKR token.
export IBKR_FLEX_WEB_SERVICE_TOKEN="your-flex-web-service-token"
# View holdings (downloads data automatically).
ibctl holding list
# View holdings in CAD instead of USD.
ibctl holding list --base-currency CAD
# View all transactions for the year.
ibctl transaction list --from 20250101 --to 20251231 --base-currency USD| Variable | Required | Description |
|---|---|---|
IBKR_FLEX_WEB_SERVICE_TOKEN |
Yes (for download) |
IBKR Flex Web Service token. Read-only — can only retrieve reports, not make trades. Never store in config files or version control. |
| Command | Description |
|---|---|
ibctl config init |
Create a new ibctl.yaml in the ibctl directory |
ibctl config edit |
Edit ibctl.yaml in $EDITOR |
ibctl config validate |
Validate ibctl.yaml |
ibctl data zip -o <file> |
Archive the ibctl directory to a zip file |
ibctl download |
Download and cache IBKR data via Flex Query API |
ibctl holding list |
Display holdings with prices, positions, and classifications |
ibctl holding lot list |
Display individual FIFO tax lots |
ibctl holding category list |
Display holdings aggregated by category |
ibctl holding geo list |
Display holdings aggregated by geographic classification |
ibctl holding value |
Display portfolio value with estimated tax impact |
ibctl transaction list |
List all transactions (buys, sells, dividends, interest, WHT, etc.) chronologically |
ibctl transaction sale list |
List realized security sales with FIFO lot matching for tax reporting |
ibctl probe |
Probe the API and show per-account data counts |
All commands accept --dir to specify the ibctl directory (defaults to .). All holding and transaction commands accept --base-currency (default USD) to convert values to a different currency. Use --help on any command for detailed documentation.
Generate CSV files for your accountant:
# Realized capital gains for IRS (US tax reporting).
ibctl transaction sale list --from 20250101 --to 20251231 --base-currency USD --format csv > transaction-sale-list-2025-usd.csv
# Realized capital gains for CRA (Canadian tax reporting).
ibctl transaction sale list --from 20250101 --to 20251231 --base-currency CAD --format csv > transaction-sale-list-2025-cad.csv
# Complete transaction history for IRS (dividends, interest, WHT, buys, sells, etc.).
ibctl transaction list --from 20250101 --to 20251231 --base-currency USD --format csv > transaction-list-2025-usd.csv
# Complete transaction history for CRA.
ibctl transaction list --from 20250101 --to 20251231 --base-currency CAD --format csv > transaction-list-2025-cad.csvSee the Tax Reporting Guide in the ibctl book for a detailed explanation of the CSV columns and methodology, suitable for sharing with your accountant.
The full ibctl book covers configuration, IBKR setup, FIFO methodology, FX rate handling, tax reporting, and detailed command references.
# Serve the book locally with live reload.
make book