# 💲 leggen
An Open Banking CLI and API service for managing bank connections and transactions.
This tool provides a **unified command-line interface** (`leggen`) with both CLI commands and an integrated **FastAPI backend service**, plus a **React Web Interface** to connect to banks using the GoCardless Open Banking API.
Having your bank data accessible through both CLI and REST API gives you the power to backup, analyze, create reports, and integrate with other applications.
## 🛠️ Technologies
### 🔌 API & Backend
- [FastAPI](https://fastapi.tiangolo.com/): High-performance async API backend (integrated into `leggen server`)
- [GoCardless Open Banking API](https://developer.gocardless.com/bank-account-data/overview): for connecting to banks
- [APScheduler](https://apscheduler.readthedocs.io/): Background job scheduling with configurable cron
### 📦 Storage
- [SQLite](https://www.sqlite.org): for storing transactions, simple and easy to use
### Frontend
- [React](https://reactjs.org/): Modern web interface with TypeScript
- [Vite](https://vitejs.dev/): Fast build tool and development server
- [Tailwind CSS](https://tailwindcss.com/): Utility-first CSS framework
- [shadcn/ui](https://ui.shadcn.com/): Modern component system built on Radix UI
- [TanStack Query](https://tanstack.com/query): Powerful data synchronization for React
## ✨ Features
### 🎯 Core Banking Features
- Connect to banks using GoCardless Open Banking API (30+ EU countries)
- List all connected banks and their connection statuses
- View balances of all connected accounts
- List and filter transactions across all accounts
- Support for both booked and pending transactions
### 🔄 Data Management
- Sync all transactions with SQLite database
- Background sync scheduling with configurable cron expressions
- Automatic transaction deduplication and status tracking
- Real-time sync status monitoring
### 📡 API & Integration
- **REST API**: Complete FastAPI backend with comprehensive endpoints
- **CLI Interface**: Enhanced command-line tools with new options
### 🔔 Notifications & Monitoring
- Discord and Telegram notifications for filtered transactions
- Configurable transaction filters (case-sensitive/insensitive)
- Account expiry notifications and status alerts
- Comprehensive logging and error handling
## 🚀 Quick Start
### Prerequisites
1. Create a GoCardless account at [https://gocardless.com/bank-account-data/](https://gocardless.com/bank-account-data/)
2. Get your API credentials (key and secret)
### Installation Options
#### Option 1: Docker Compose (Recommended)
The easiest way to get started is with Docker Compose, which includes both the React frontend and FastAPI backend:
```bash
# Clone the repository
git clone https://github.com/elisiariocouto/leggen.git
cd leggen
# Create your configuration
mkdir -p data && cp config.example.toml data/config.toml
# Edit data/config.toml with your GoCardless credentials
# Start all services (frontend + backend)
docker compose up -d
# Access the web interface at http://localhost:3000
# API is available at http://localhost:8000
```
#### Production Deployment
For production deployment using published Docker images:
```bash
# Clone the repository
git clone https://github.com/elisiariocouto/leggen.git
cd leggen
# Create your configuration
mkdir -p data && cp config.example.toml data/config.toml
# Edit data/config.toml with your GoCardless credentials
# Start production services
docker compose up -d
# Access the web interface at http://localhost:3000
# API is available at http://localhost:8000
```
### Development vs Production
- **Development**: Use `docker compose -f compose.dev.yml up -d` (builds from source)
- **Production**: Use `docker compose up -d` (uses published images)
#### Option 2: Local Development
For development or local installation:
```bash
# Install with uv (recommended) or pip
uv sync # or pip install -e .
# Start the API service
uv run leggen server --reload # Development mode with auto-reload
# Use the CLI (in another terminal)
uv run leggen --help
```
### Configuration
Create a configuration file at `./data/config.toml` (for Docker) or `~/.config/leggen/config.toml` (for local development):
```toml
[gocardless]
key = "your-api-key"
secret = "your-secret-key"
url = "https://bankaccountdata.gocardless.com/api/v2"
[database]
sqlite = true
# Optional: Background sync scheduling
[scheduler.sync]
enabled = true
hour = 3 # 3 AM
minute = 0
# cron = "0 3 * * *" # Alternative: use cron expression
# Optional: Discord notifications
[notifications.discord]
webhook = "https://discord.com/api/webhooks/..."
enabled = true
# Optional: Telegram notifications
[notifications.telegram]
token = "your-bot-token"
chat_id = 12345
enabled = true
# Optional: Transaction filters for notifications
[filters]
case_insensitive = ["salary", "utility"]
case_sensitive = ["SpecificStore"]
```
## 📖 Usage
### API Service (`leggen server`)
Start the FastAPI backend service:
```bash
# Production mode
leggen server
# Development mode with auto-reload
leggen server --reload
# Custom host and port
leggen server --host 127.0.0.1 --port 8080
```
**API Documentation**: Visit `http://localhost:8000/docs` for interactive API documentation.
### CLI Commands (`leggen`)
#### Basic Commands
```bash
# Check connection status
leggen status
# Connect to a new bank
leggen bank add
# View account balances
leggen balances
# List recent transactions
leggen transactions --limit 20
# View detailed transactions
leggen transactions --full
```
#### Sync Operations
```bash
# Start background sync
leggen sync
# Synchronous sync (wait for completion)
leggen sync --wait
# Force sync (override running sync)
leggen sync --force --wait
```
#### API Integration
```bash
# Use custom API URL
leggen --api-url http://localhost:8080 status
# Set via environment variable
export LEGGEN_API_URL=http://localhost:8080
leggen status
```
### Docker Usage
#### Development (build from source)
```bash
# Start development services
docker compose -f compose.dev.yml up -d
# View service status
docker compose -f compose.dev.yml ps
# Check logs
docker compose -f compose.dev.yml logs frontend
docker compose -f compose.dev.yml logs leggen-server
# Stop development services
docker compose -f compose.dev.yml down
```
#### Production (use published images)
```bash
# Start production services
docker compose up -d
# View service status
docker compose ps
# Check logs
docker compose logs frontend
docker compose logs leggen-server
# Access the web interface at http://localhost:3000
# API documentation at http://localhost:8000/docs
# Stop production services
docker compose down
```
## 🔌 API Endpoints
The FastAPI backend provides comprehensive REST endpoints:
### Banks & Connections
- `GET /api/v1/banks/institutions?country=PT` - List available banks
- `POST /api/v1/banks/connect` - Create bank connection
- `GET /api/v1/banks/status` - Connection status
- `GET /api/v1/banks/countries` - Supported countries
### Accounts & Balances
- `GET /api/v1/accounts` - List all accounts
- `GET /api/v1/accounts/{id}` - Account details
- `GET /api/v1/accounts/{id}/balances` - Account balances
- `GET /api/v1/accounts/{id}/transactions` - Account transactions
### Transactions
- `GET /api/v1/transactions` - All transactions with filtering
- `GET /api/v1/transactions/stats` - Transaction statistics
### Sync & Scheduling
- `POST /api/v1/sync` - Trigger background sync
- `POST /api/v1/sync/now` - Synchronous sync
- `GET /api/v1/sync/status` - Sync status
- `GET/PUT /api/v1/sync/scheduler` - Scheduler configuration
### Notifications
- `GET/PUT /api/v1/notifications/settings` - Manage notifications
- `POST /api/v1/notifications/test` - Test notifications
## 🛠️ Development
### Local Development Setup
```bash
# Clone and setup
git clone https://github.com/elisiariocouto/leggen.git
cd leggen
# Install dependencies
uv sync
# Start API service with auto-reload
uv run leggen server --reload
# Use CLI commands
uv run leggen status
```
### Testing
Run the comprehensive test suite with:
```bash
# Run all tests
uv run pytest
# Run unit tests only
uv run pytest tests/unit/
# Run with verbose output
uv run pytest tests/unit/ -v
# Run specific test files
uv run pytest tests/unit/test_config.py -v
uv run pytest tests/unit/test_scheduler.py -v
uv run pytest tests/unit/test_api_banks.py -v
# Run tests by markers
uv run pytest -m unit # Unit tests
uv run pytest -m api # API endpoint tests
uv run pytest -m cli # CLI tests
```
The test suite includes:
- **Configuration management tests** - TOML config loading/saving
- **API endpoint tests** - FastAPI route testing with mocked dependencies
- **CLI API client tests** - HTTP client integration testing
- **Background scheduler tests** - APScheduler job management
- **Mock data and fixtures** - Realistic test data for banks, accounts, transactions
### Code Structure
```
leggen/ # CLI application
├── commands/ # CLI command implementations
├── utils/ # Shared utilities
├── api/ # FastAPI API routes and models
├── services/ # Business logic
├── background/ # Background job scheduler
└── api_client.py # API client for server communication
tests/ # Test suite
├── conftest.py # Shared test fixtures
└── unit/ # Unit tests
├── test_config.py # Configuration tests
├── test_scheduler.py # Background scheduler tests
├── test_api_banks.py # Banks API tests
├── test_api_accounts.py # Accounts API tests
└── test_api_client.py # CLI API client tests
```
### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request
The repository uses GitHub Actions for CI/CD:
- **CI**: Runs Python tests (`uv run pytest`) and frontend linting/build on every push
- **Release**: Creates GitHub releases with changelog when tags are pushed
## ⚠️ Notes
- This project is in active development
- GoCardless API rate limits apply
- Some banks may require additional authorization steps
- Docker images are automatically built and published on releases
Raw data
{
"_id": null,
"home_page": null,
"name": "leggen",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.13.0",
"maintainer_email": null,
"keywords": "bank, cli, finance, gocardless, openbanking, psd2, transactions",
"author": null,
"author_email": "Elisi\u00e1rio Couto <elisiario@couto.io>",
"download_url": "https://files.pythonhosted.org/packages/52/6c/f201650f7608f1ef72a7046e37bb45a8d6a3dbb5dcaa37cea7248159ae62/leggen-2025.9.18.tar.gz",
"platform": null,
"description": "# \ud83d\udcb2 leggen\n\nAn Open Banking CLI and API service for managing bank connections and transactions.\n\nThis tool provides a **unified command-line interface** (`leggen`) with both CLI commands and an integrated **FastAPI backend service**, plus a **React Web Interface** to connect to banks using the GoCardless Open Banking API.\n\nHaving your bank data accessible through both CLI and REST API gives you the power to backup, analyze, create reports, and integrate with other applications.\n\n## \ud83d\udee0\ufe0f Technologies\n\n ### \ud83d\udd0c API & Backend\n - [FastAPI](https://fastapi.tiangolo.com/): High-performance async API backend (integrated into `leggen server`)\n - [GoCardless Open Banking API](https://developer.gocardless.com/bank-account-data/overview): for connecting to banks\n - [APScheduler](https://apscheduler.readthedocs.io/): Background job scheduling with configurable cron\n\n ### \ud83d\udce6 Storage\n - [SQLite](https://www.sqlite.org): for storing transactions, simple and easy to use\n\n ### Frontend\n - [React](https://reactjs.org/): Modern web interface with TypeScript\n - [Vite](https://vitejs.dev/): Fast build tool and development server\n - [Tailwind CSS](https://tailwindcss.com/): Utility-first CSS framework\n - [shadcn/ui](https://ui.shadcn.com/): Modern component system built on Radix UI\n - [TanStack Query](https://tanstack.com/query): Powerful data synchronization for React\n\n## \u2728 Features\n\n### \ud83c\udfaf Core Banking Features\n- Connect to banks using GoCardless Open Banking API (30+ EU countries)\n- List all connected banks and their connection statuses\n- View balances of all connected accounts\n- List and filter transactions across all accounts\n- Support for both booked and pending transactions\n\n### \ud83d\udd04 Data Management\n- Sync all transactions with SQLite database\n- Background sync scheduling with configurable cron expressions\n- Automatic transaction deduplication and status tracking\n- Real-time sync status monitoring\n\n### \ud83d\udce1 API & Integration\n- **REST API**: Complete FastAPI backend with comprehensive endpoints\n- **CLI Interface**: Enhanced command-line tools with new options\n\n### \ud83d\udd14 Notifications & Monitoring\n- Discord and Telegram notifications for filtered transactions\n- Configurable transaction filters (case-sensitive/insensitive)\n- Account expiry notifications and status alerts\n- Comprehensive logging and error handling\n\n## \ud83d\ude80 Quick Start\n\n### Prerequisites\n1. Create a GoCardless account at [https://gocardless.com/bank-account-data/](https://gocardless.com/bank-account-data/)\n2. Get your API credentials (key and secret)\n\n### Installation Options\n\n#### Option 1: Docker Compose (Recommended)\nThe easiest way to get started is with Docker Compose, which includes both the React frontend and FastAPI backend:\n\n```bash\n# Clone the repository\ngit clone https://github.com/elisiariocouto/leggen.git\ncd leggen\n\n# Create your configuration\nmkdir -p data && cp config.example.toml data/config.toml\n# Edit data/config.toml with your GoCardless credentials\n\n# Start all services (frontend + backend)\ndocker compose up -d\n\n# Access the web interface at http://localhost:3000\n# API is available at http://localhost:8000\n```\n\n#### Production Deployment\n\nFor production deployment using published Docker images:\n\n```bash\n# Clone the repository\ngit clone https://github.com/elisiariocouto/leggen.git\ncd leggen\n\n# Create your configuration\nmkdir -p data && cp config.example.toml data/config.toml\n# Edit data/config.toml with your GoCardless credentials\n\n# Start production services\ndocker compose up -d\n\n# Access the web interface at http://localhost:3000\n# API is available at http://localhost:8000\n```\n\n### Development vs Production\n\n- **Development**: Use `docker compose -f compose.dev.yml up -d` (builds from source)\n- **Production**: Use `docker compose up -d` (uses published images)\n\n#### Option 2: Local Development\nFor development or local installation:\n\n```bash\n# Install with uv (recommended) or pip\nuv sync # or pip install -e .\n\n# Start the API service\nuv run leggen server --reload # Development mode with auto-reload\n\n# Use the CLI (in another terminal)\nuv run leggen --help\n```\n\n### Configuration\n\nCreate a configuration file at `./data/config.toml` (for Docker) or `~/.config/leggen/config.toml` (for local development):\n\n```toml\n[gocardless]\nkey = \"your-api-key\"\nsecret = \"your-secret-key\"\nurl = \"https://bankaccountdata.gocardless.com/api/v2\"\n\n[database]\nsqlite = true\n\n# Optional: Background sync scheduling\n[scheduler.sync]\nenabled = true\nhour = 3 # 3 AM\nminute = 0\n# cron = \"0 3 * * *\" # Alternative: use cron expression\n\n# Optional: Discord notifications\n[notifications.discord]\nwebhook = \"https://discord.com/api/webhooks/...\"\nenabled = true\n\n# Optional: Telegram notifications\n[notifications.telegram]\ntoken = \"your-bot-token\"\nchat_id = 12345\nenabled = true\n\n# Optional: Transaction filters for notifications\n[filters]\ncase_insensitive = [\"salary\", \"utility\"]\ncase_sensitive = [\"SpecificStore\"]\n```\n\n## \ud83d\udcd6 Usage\n\n### API Service (`leggen server`)\n\nStart the FastAPI backend service:\n\n```bash\n# Production mode\nleggen server\n\n# Development mode with auto-reload\nleggen server --reload\n\n# Custom host and port\nleggen server --host 127.0.0.1 --port 8080\n```\n\n**API Documentation**: Visit `http://localhost:8000/docs` for interactive API documentation.\n\n### CLI Commands (`leggen`)\n\n#### Basic Commands\n```bash\n# Check connection status\nleggen status\n\n# Connect to a new bank\nleggen bank add\n\n# View account balances\nleggen balances\n\n# List recent transactions\nleggen transactions --limit 20\n\n# View detailed transactions\nleggen transactions --full\n```\n\n#### Sync Operations\n```bash\n# Start background sync\nleggen sync\n\n# Synchronous sync (wait for completion)\nleggen sync --wait\n\n# Force sync (override running sync)\nleggen sync --force --wait\n```\n\n#### API Integration\n```bash\n# Use custom API URL\nleggen --api-url http://localhost:8080 status\n\n# Set via environment variable\nexport LEGGEN_API_URL=http://localhost:8080\nleggen status\n```\n\n### Docker Usage\n\n#### Development (build from source)\n```bash\n# Start development services\ndocker compose -f compose.dev.yml up -d\n\n# View service status\ndocker compose -f compose.dev.yml ps\n\n# Check logs\ndocker compose -f compose.dev.yml logs frontend\ndocker compose -f compose.dev.yml logs leggen-server\n\n# Stop development services\ndocker compose -f compose.dev.yml down\n```\n\n#### Production (use published images)\n```bash\n# Start production services\ndocker compose up -d\n\n# View service status\ndocker compose ps\n\n# Check logs\ndocker compose logs frontend\ndocker compose logs leggen-server\n\n# Access the web interface at http://localhost:3000\n# API documentation at http://localhost:8000/docs\n\n# Stop production services\ndocker compose down\n```\n\n## \ud83d\udd0c API Endpoints\n\nThe FastAPI backend provides comprehensive REST endpoints:\n\n### Banks & Connections\n- `GET /api/v1/banks/institutions?country=PT` - List available banks\n- `POST /api/v1/banks/connect` - Create bank connection\n- `GET /api/v1/banks/status` - Connection status\n- `GET /api/v1/banks/countries` - Supported countries\n\n### Accounts & Balances\n- `GET /api/v1/accounts` - List all accounts\n- `GET /api/v1/accounts/{id}` - Account details\n- `GET /api/v1/accounts/{id}/balances` - Account balances\n- `GET /api/v1/accounts/{id}/transactions` - Account transactions\n\n### Transactions\n- `GET /api/v1/transactions` - All transactions with filtering\n- `GET /api/v1/transactions/stats` - Transaction statistics\n\n### Sync & Scheduling\n- `POST /api/v1/sync` - Trigger background sync\n- `POST /api/v1/sync/now` - Synchronous sync\n- `GET /api/v1/sync/status` - Sync status\n- `GET/PUT /api/v1/sync/scheduler` - Scheduler configuration\n\n### Notifications\n- `GET/PUT /api/v1/notifications/settings` - Manage notifications\n- `POST /api/v1/notifications/test` - Test notifications\n\n## \ud83d\udee0\ufe0f Development\n\n### Local Development Setup\n```bash\n# Clone and setup\ngit clone https://github.com/elisiariocouto/leggen.git\ncd leggen\n\n# Install dependencies\nuv sync\n\n# Start API service with auto-reload\nuv run leggen server --reload\n\n# Use CLI commands\nuv run leggen status\n```\n\n### Testing\n\nRun the comprehensive test suite with:\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run unit tests only\nuv run pytest tests/unit/\n\n# Run with verbose output\nuv run pytest tests/unit/ -v\n\n# Run specific test files\nuv run pytest tests/unit/test_config.py -v\nuv run pytest tests/unit/test_scheduler.py -v\nuv run pytest tests/unit/test_api_banks.py -v\n\n# Run tests by markers\nuv run pytest -m unit # Unit tests\nuv run pytest -m api # API endpoint tests\nuv run pytest -m cli # CLI tests\n```\n\nThe test suite includes:\n- **Configuration management tests** - TOML config loading/saving\n- **API endpoint tests** - FastAPI route testing with mocked dependencies\n- **CLI API client tests** - HTTP client integration testing\n- **Background scheduler tests** - APScheduler job management\n- **Mock data and fixtures** - Realistic test data for banks, accounts, transactions\n\n### Code Structure\n```\nleggen/ # CLI application\n\u251c\u2500\u2500 commands/ # CLI command implementations\n\u251c\u2500\u2500 utils/ # Shared utilities\n\u251c\u2500\u2500 api/ # FastAPI API routes and models\n\u251c\u2500\u2500 services/ # Business logic\n\u251c\u2500\u2500 background/ # Background job scheduler\n\u2514\u2500\u2500 api_client.py # API client for server communication\n\ntests/ # Test suite\n\u251c\u2500\u2500 conftest.py # Shared test fixtures\n\u2514\u2500\u2500 unit/ # Unit tests\n \u251c\u2500\u2500 test_config.py # Configuration tests\n \u251c\u2500\u2500 test_scheduler.py # Background scheduler tests\n \u251c\u2500\u2500 test_api_banks.py # Banks API tests\n \u251c\u2500\u2500 test_api_accounts.py # Accounts API tests\n \u2514\u2500\u2500 test_api_client.py # CLI API client tests\n```\n\n### Contributing\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes with tests\n4. Submit a pull request\n\nThe repository uses GitHub Actions for CI/CD:\n- **CI**: Runs Python tests (`uv run pytest`) and frontend linting/build on every push\n- **Release**: Creates GitHub releases with changelog when tags are pushed\n\n## \u26a0\ufe0f Notes\n- This project is in active development\n- GoCardless API rate limits apply\n- Some banks may require additional authorization steps\n- Docker images are automatically built and published on releases\n",
"bugtrack_url": null,
"license": null,
"summary": "An Open Banking CLI",
"version": "2025.9.18",
"project_urls": {
"Repository": "https://github.com/elisiariocouto/leggen"
},
"split_keywords": [
"bank",
" cli",
" finance",
" gocardless",
" openbanking",
" psd2",
" transactions"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3eddf9758653d83f8840a9bb062dc0fbe9cb3e1f4186cf14e5c070a250a1aa41",
"md5": "d7593328c64a29697b16047784426eba",
"sha256": "2ecd167a70a93fa57a9b3256d49c931a9a1e4c1ae74432916a33b362eb62e929"
},
"downloads": -1,
"filename": "leggen-2025.9.18-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d7593328c64a29697b16047784426eba",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.13.0",
"size": 54085,
"upload_time": "2025-09-19T10:25:42",
"upload_time_iso_8601": "2025-09-19T10:25:42.628033Z",
"url": "https://files.pythonhosted.org/packages/3e/dd/f9758653d83f8840a9bb062dc0fbe9cb3e1f4186cf14e5c070a250a1aa41/leggen-2025.9.18-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "526cf201650f7608f1ef72a7046e37bb45a8d6a3dbb5dcaa37cea7248159ae62",
"md5": "f8a64464bd5abfd15c64f442aa7a0a34",
"sha256": "a81ff875a41b7c53ca491caba356883671a83723505f9255bf6dce0be0a18b27"
},
"downloads": -1,
"filename": "leggen-2025.9.18.tar.gz",
"has_sig": false,
"md5_digest": "f8a64464bd5abfd15c64f442aa7a0a34",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.13.0",
"size": 41181,
"upload_time": "2025-09-19T10:25:43",
"upload_time_iso_8601": "2025-09-19T10:25:43.585510Z",
"url": "https://files.pythonhosted.org/packages/52/6c/f201650f7608f1ef72a7046e37bb45a8d6a3dbb5dcaa37cea7248159ae62/leggen-2025.9.18.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-19 10:25:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "elisiariocouto",
"github_project": "leggen",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "leggen"
}
JSON
