pyflexweb 0.2.3

Download IBKR Flex reports using the Interactive Brokers flex web service

PyFlexWeb

A command-line tool for downloading IBKR Flex reports using the Interactive Brokers flex web service.

Features

• Store and manage your IBKR Flex Web Service token securely
• Manage multiple query IDs with descriptive names
• Download activity reports and trade confirmations
• Automatic handling of request/response workflow
• Track download history to avoid unnecessary downloads
• Batch download all reports that need updating

Installation

Install:

# Install via uv (recommended)
uv tool install pyflexweb

# Or using pip
pip install pyflexweb

For development installation:

# Clone the repository
git clone https://github.com/grynn/pyflexweb.git
cd pyflexweb

# Install in development mode
uv tool install -e . # or pip install -e .

Usage

Basic Setup

First, set up your IBKR Flex Web Service token (see IBKR Flex Web Service token documentation for token generation):

pyflexweb token set YOUR_TOKEN_HERE

Add query IDs for your reports:

# Add a flex query
pyflexweb query add 123456 --name "Daily activity report"

# Add another query
pyflexweb query add 789012 --name "Trade confirmations"

Listing Queries

To see all your stored queries with their last download status:

pyflexweb query
# or
pyflexweb status

Downloading Reports

Download all reports that haven't been updated in the last 24 hours:

pyflexweb download

Download a specific report:

pyflexweb download --query 123456

Force download even if the report was already downloaded today:

pyflexweb download --query 123456 --force

Advanced Usage

For more control, you can use the two-step process:

# Request a report
request_id=$(pyflexweb request 123456)

# Fetch it later
pyflexweb fetch $request_id --output my_report.xml

Scripting Example

#!/bin/bash
# Daily report download script

# Request activity report
request_id=$(pyflexweb request 123456)
if [ $? -ne 0 ]; then
    echo "Failed to request report" >&2
    exit 1
fi

# Download the report
pyflexweb fetch $request_id --output "activity_$(date +%Y%m%d).xml"

Download Multiple Reports

#!/bin/bash
# Download all configured reports

# Get list of query IDs
queries=$(pyflexweb query list | tail -n +3 | awk '{print $1}')

for query in $queries; do
    echo "Downloading report for query $query..."
    pyflexweb download --query $query
done

Other Commands

Check version information:

pyflexweb --version

Get help on any command:

pyflexweb --help

License

This project is licensed under the terms of the GNU General Public License v3.0 or later. See the LICENSE file for details.

Command Reference

Token Management

• token set <token_value> - Store your IBKR token (see IBKR Flex Web Service token documentation for token generation)
• token get - Display your stored token (masked for security)
• token unset - Remove your stored token

Query Management

• query add <query_id> --name "Query Name" - Add a query
• query list - List all stored queries
• query - List all queries with last download status (shorthand for query list)
• query remove <query_id> - Remove a query
• query rename <query_id> --name "New Name" - Rename a query

Report Operations

• status - Show status of all stored queries (alias for query list)
• request <query_id> - Request a report
• fetch <request_id> [--output filename.xml] [--poll-interval SECONDS] [--max-attempts NUM] - Fetch a requested report
• download [--query QUERY_ID|all] [--output filename.xml] [--force] [--poll-interval SECONDS] [--max-attempts NUM] - Download reports

Prerequisites

Before using PyFlexWeb, you need to:

1. Create a Flex Query in your IBKR Account Management portal
2. Generate a Flex Web Service token

For detailed instructions, see IBKR Flex Web Service token documentation.

Report Types

IBKR Flex reports provide data including:

• Total equity
• Open positions
• Trades
• Cash transactions
• Account statement information

The specific content depends on how you've configured your Flex Query in the IBKR Account Management portal.

Data Storage

PyFlexWeb stores its data in a SQLite database located in your user data directory:

• Windows: C:\Users\<username>\AppData\Local\pyflexweb\pyflexweb
• macOS: ~/Library/Application Support/pyflexweb
• Linux: ~/.local/share/pyflexweb

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

If you want to contribute to the project or modify the code:

# Clone the repository
git clone https://github.com/grynn/pyflexweb.git
cd pyflexweb

# Install development dependencies using uv
uv sync --all-extras

# Install pre-commit hooks
uv run pre-commit install

# Run tests
uv run pytest

# Run linting and formatting
make lint
# or manually:
uv run pre-commit run --all-files

Releasing

This project uses automated PyPI publishing via GitHub Actions. To create a release:

# Bump version (choose one)
make bump-patch  # 0.1.1 -> 0.1.2
make bump-minor  # 0.1.1 -> 0.2.0
make bump-major  # 0.1.1 -> 1.0.0

# Create GitHub release (automatically publishes to PyPI)
make release

The release process will:

1. Run linting and tests
2. Build the package
3. Create a git tag and commit
4. Push to GitHub and create a release
5. Automatically publish to PyPI via GitHub Actions

For initial PyPI setup, run make setup-pypi for detailed instructions.

Code Quality

This project uses pre-commit hooks to ensure code quality:

• ruff: Fast Python linter and formatter (handles both linting and formatting)
• Standard hooks: trailing whitespace, end-of-file fixes, etc.

The pre-commit hooks will run automatically on each commit. You can also run them manually:

# Run all pre-commit hooks
make pre-commit-run

# Run just ruff linting
uv run ruff check --fix .

# Run just ruff formatting
uv run ruff format .

Acknowledgments

• Interactive Brokers for providing the Flex Web Service
• platformdirs for cross-platform data directory support
• requests for simplified HTTP handling