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 holdings with real-time prices from Yahoo Finance.
ibctl holding list --realtime
# 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 lot list |
Display individual FIFO tax lots |
ibctl category list |
Display holdings aggregated by category |
ibctl geo list |
Display holdings aggregated by geographic classification |
ibctl possible-sale list --safe |
Identify positions safe to sell from a tax perspective (loss or LTCG only) |
ibctl possible-sale list --unsafe |
Show positions with short-term capital gains exposure |
ibctl value |
Display portfolio value with estimated tax impact |
ibctl transaction list |
List all transactions (buys, sells, dividends, interest, WHT, etc.) chronologically |
ibctl realized-sale list |
List realized security sales with FIFO lot matching for tax reporting |
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. Holding commands accept --realtime to fetch current stock prices and FX rates from Yahoo Finance on-demand. For international symbols where IBKR and Yahoo symbols differ, add mappings to realtime_symbols in ibctl.yaml. Use --help on any command for detailed documentation.
Generate CSV files for your accountant:
# Realized capital gains for IRS (US tax reporting).
ibctl realized-sale list --from 20250101 --to 20251231 --base-currency USD --format csv > realized-sale-list-2025-usd.csv
# Realized capital gains for CRA (Canadian tax reporting).
ibctl realized-sale list --from 20250101 --to 20251231 --base-currency CAD --format csv > realized-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