bunq-cli 0.2.0__tar.gz

bunq_cli-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,59 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # setuptools-scm needs the tags
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build twine
+      - run: python -m build
+      - run: twine check --strict dist/*
+      - name: Check that the package version matches the tag
+        run: |
+          expected="${GITHUB_REF_NAME#v}"
+          ls dist/ | grep -q "bunq_cli-${expected}.tar.gz" || {
+            echo "Built $(ls dist/), expected version ${expected}"; exit 1; }
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/bunq-cli/
+    permissions:
+      id-token: write  # PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

bunq_cli-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+*.conf

bunq_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Koert van der Veer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bunq_cli-0.2.0/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: bunq-cli
+Version: 0.2.0
+Summary: Command-line interface for the Bunq API
+Author-email: Koert van der Veer <koert@ondergetekende.nl>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ondergetekende/bunq-cli
+Project-URL: Repository, https://github.com/ondergetekende/bunq-cli
+Project-URL: Issues, https://github.com/ondergetekende/bunq-cli/issues
+Keywords: bunq,banking,cli,payments,finance
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: bunq-sdk>=1.28
+Requires-Dist: requests>=2.24
+Requires-Dist: tabulate>=0.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# Bunq CLI
+
+A command-line interface for [Bunq](https://www.bunq.com/), the online bank. Manage accounts, payments, cards, and more from your terminal.
+
+> **Disclaimer:** This project is not affiliated with, endorsed by, or in any way associated with Bunq B.V. "Bunq" is a trademark of Bunq N.V. This is an independent, open-source tool that uses the public Bunq API.
+
+## Quick start
+
+```bash
+pip install bunq-cli
+bunq login
+bunq accounts list
+bunq payments list --account "My Account"
+```
+
+See [Getting Started](docs/getting-started.md) for full setup instructions, output formats, pagination, and global options.
+
+## Documentation
+
+| Guide | What it covers |
+| --- | --- |
+| [Getting Started](docs/getting-started.md) | Installation, authentication, profiles (multiple clients), sandbox mode, output formats, pagination, global options |
+| [Accounts](docs/accounts.md) | Monetary accounts: list, get, create savings goals |
+| [Payments](docs/payments.md) | Payments, drafts, scheduled payments, batch payments, international transfers |
+| [Payment Requests](docs/payment-requests.md) | Request money from others, manage incoming requests |
+| [Cards](docs/cards.md) | Card management: list, get, update settings, freeze/unfreeze |
+| [Callbacks](docs/callbacks.md) | Notification filters and webhook management |
+
+## Tech stack
+
+- [Python](https://www.python.org/) >= 3.11
+- [Click](https://click.palletsprojects.com/) for the CLI framework
+- [bunq SDK](https://github.com/bunq/sdk_python) for the Bunq API
+- [Tabulate](https://pypi.org/project/tabulate/) for table formatting
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

bunq_cli-0.2.0/README.md

@@ -0,0 +1,38 @@
+# Bunq CLI
+
+A command-line interface for [Bunq](https://www.bunq.com/), the online bank. Manage accounts, payments, cards, and more from your terminal.
+
+> **Disclaimer:** This project is not affiliated with, endorsed by, or in any way associated with Bunq B.V. "Bunq" is a trademark of Bunq N.V. This is an independent, open-source tool that uses the public Bunq API.
+
+## Quick start
+
+```bash
+pip install bunq-cli
+bunq login
+bunq accounts list
+bunq payments list --account "My Account"
+```
+
+See [Getting Started](docs/getting-started.md) for full setup instructions, output formats, pagination, and global options.
+
+## Documentation
+
+| Guide | What it covers |
+| --- | --- |
+| [Getting Started](docs/getting-started.md) | Installation, authentication, profiles (multiple clients), sandbox mode, output formats, pagination, global options |
+| [Accounts](docs/accounts.md) | Monetary accounts: list, get, create savings goals |
+| [Payments](docs/payments.md) | Payments, drafts, scheduled payments, batch payments, international transfers |
+| [Payment Requests](docs/payment-requests.md) | Request money from others, manage incoming requests |
+| [Cards](docs/cards.md) | Card management: list, get, update settings, freeze/unfreeze |
+| [Callbacks](docs/callbacks.md) | Notification filters and webhook management |
+
+## Tech stack
+
+- [Python](https://www.python.org/) >= 3.11
+- [Click](https://click.palletsprojects.com/) for the CLI framework
+- [bunq SDK](https://github.com/bunq/sdk_python) for the Bunq API
+- [Tabulate](https://pypi.org/project/tabulate/) for table formatting
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

bunq_cli-0.2.0/docs/accounts.md

@@ -0,0 +1,38 @@
+# Accounts
+
+Monetary accounts in Bunq are your bank accounts -- current accounts, savings accounts, and joint accounts. Every payment and card is tied to a monetary account.
+
+## Listing accounts
+
+```bash
+# All active accounts
+bunq accounts list
+
+# Include closed accounts
+bunq accounts list --include-inactive
+```
+
+## Viewing an account
+
+```bash
+bunq accounts get 12345
+```
+
+This shows the full account details including IBAN, balance, and settings.
+
+## Account types
+
+Bunq offers several account types. The CLI displays the type in list output:
+
+- **MonetaryAccountBank** -- standard current accounts
+- **MonetaryAccountSavings** -- savings accounts
+- **MonetaryAccountJoint** -- shared accounts with another Bunq user
+
+## Checking your balance
+
+```bash
+# Quick overview of all balances
+bunq accounts list --output table
+```
+
+The table output includes the account description, IBAN, and current balance.

bunq_cli-0.2.0/docs/callbacks.md

@@ -0,0 +1,59 @@
+# Callbacks
+
+Callbacks (notification filters) let you receive real-time HTTP notifications when events happen on your Bunq account -- for example, when a payment is received or a card transaction occurs. This is useful for integrating Bunq with other systems.
+
+## Listing callbacks
+
+```bash
+bunq callbacks list
+```
+
+## Creating a callback
+
+```bash
+bunq callbacks create \
+  --url "https://example.com/webhooks/bunq" \
+  --category MUTATION
+```
+
+**Categories:**
+
+| Category | Events |
+|---|---|
+| `MUTATION` | Any balance change (payments, requests, iDEAL, etc.) |
+| `PAYMENT` | Incoming and outgoing payments |
+| `INSTANT_PAYMENT` | Instant (SCT Inst) payments |
+| `REQUEST` | Payment request updates |
+| `CARD_TRANSACTION_SUCCESSFUL` | Successful card transactions |
+| `CARD_TRANSACTION_FAILED` | Declined card transactions |
+| `SCHEDULE_STATUS` | Scheduled payment status changes |
+| `BUNQME_TAB` | bunq.me request updates |
+| `OAUTH` | OAuth connection revoked |
+
+Run `bunq callbacks create --help` for the full list. The URL must use HTTPS. New filters are added to the existing ones.
+
+Subscribe to multiple categories:
+
+```bash
+bunq callbacks create \
+  --url "https://example.com/webhooks/bunq" \
+  --category MUTATION \
+  --category CARD_TRANSACTION_SUCCESSFUL
+```
+
+## Deleting callbacks
+
+Removes all notification filters:
+
+```bash
+bunq callbacks delete
+```
+
+## Failed callbacks
+
+bunq retries a failed callback 5 times, one minute apart. After that it is stored as a failure, which you can list and retry:
+
+```bash
+bunq callbacks failures
+bunq callbacks retry 101 102 103
+```

bunq_cli-0.2.0/docs/cards.md

@@ -0,0 +1,65 @@
+# Cards
+
+Bunq issues debit cards (Maestro and Mastercard) that are linked to your monetary accounts. The CLI lets you view and manage your cards.
+
+## Listing cards
+
+```bash
+bunq cards list
+```
+
+## Viewing a card
+
+```bash
+bunq cards get 12345
+```
+
+This shows the card type, status, linked accounts, spending limits, and card settings.
+
+## Updating card settings
+
+### Freeze and unfreeze
+
+Temporarily disable a card without cancelling it:
+
+```bash
+bunq cards freeze 12345
+bunq cards unfreeze 12345
+```
+
+### Spending limits
+
+Update the daily spending and ATM limits:
+
+```bash
+bunq cards update 12345 --daily-limit 500.00
+bunq cards update 12345 --atm-limit 250.00
+```
+
+### PIN code
+
+```bash
+bunq cards update 12345 --change-pin
+```
+
+You'll be prompted for the new PIN, so it doesn't end up in your shell history.
+
+### Linked accounts
+
+Change which account a card draws from:
+
+```bash
+bunq cards update 12345 --account 67890
+```
+
+### Country permissions
+
+Restrict where a card can be used:
+
+```bash
+# Allow only domestic transactions
+bunq cards update 12345 --country-permission NL
+
+# Allow multiple countries
+bunq cards update 12345 --country-permission NL --country-permission DE --country-permission BE
+```

bunq_cli-0.2.0/docs/getting-started.md

@@ -0,0 +1,212 @@
+# Getting Started
+
+## What is Bunq?
+
+[Bunq](https://www.bunq.com/) is a Dutch online bank that offers personal and business accounts, cards, and payments. It provides a public API for building integrations.
+
+This CLI lets you interact with your Bunq accounts from the terminal -- useful for scripting, automation, and quick lookups without opening the app.
+
+## Installation
+
+```bash
+pip install bunq-cli
+```
+
+This installs a `bunq` command in your PATH.
+
+## Authentication
+
+### Step 1: Get an API key
+
+You need an API key for initial setup. Open the Bunq app on your phone:
+
+1. Go to **Profile** > **Security & Privacy** > **Developers** > **API keys**.
+2. Create a new API key and copy it.
+
+Log in with it:
+
+```bash
+bunq login --token YOUR_API_KEY
+```
+
+### Step 2: Register an OAuth client
+
+Bunq doesn't have a web portal for OAuth client registration -- it's done via the API. The CLI handles this for you:
+
+```bash
+bunq oauth-client register
+```
+
+This creates an OAuth client, registers the local callback URL, and stores the `client_id` and `client_secret` in `~/.config/bunq-cli.toml`. You can inspect them with:
+
+```bash
+bunq oauth-client show
+```
+
+You only need to do this once. Each Bunq user can have one OAuth client.
+
+### Step 3: Log in with OAuth
+
+From now on, you can log in without an API key:
+
+```bash
+bunq login
+```
+
+This opens your browser, you approve access on Bunq's website, and the CLI receives a token automatically via a local server on `http://127.0.0.1:12345/callback`.
+
+### API key (alternative)
+
+If you prefer to skip OAuth entirely (e.g., for scripting or server environments where a browser isn't available), you can always use an API key directly:
+
+```bash
+bunq login --token YOUR_API_KEY
+```
+
+API keys are only permitted for private integrations that you control yourself.
+
+### Allowed IP addresses
+
+bunq invalidates a new API key if it isn't assigned to an IP address within 4 hours. `bunq login` does this when it registers the device. By default (`*`) bunq assigns the IP you log in from, or allows any IP if you created a wildcard API key in the app. To restrict the key to specific addresses:
+
+```bash
+bunq login --token YOUR_API_KEY --allowed-ip 203.0.113.10 --allowed-ip 2001:db8::1
+```
+
+### Environment variable override
+
+If you want to override the stored OAuth credentials (e.g., for testing), set these environment variables:
+
+```bash
+export BUNQ_OAUTH_CLIENT_ID="your-client-id"
+export BUNQ_OAUTH_CLIENT_SECRET="your-client-secret"
+```
+
+Environment variables take precedence over the config file.
+
+### Logging out
+
+```bash
+bunq logout                    # the selected profile
+bunq logout --profile acme
+bunq logout --all
+```
+
+This closes the session and removes the profile's stored credentials.
+
+## Profiles (multiple clients)
+
+Each login is stored as a named profile, so you can work with several bunq users -- for example one per client. Your first login becomes the `default` profile; once profiles exist, `bunq login` needs `--profile NAME` so it never overwrites another client's login.
+
+```bash
+# Your own account registers the OAuth client once (see above)
+bunq login --profile me --token YOUR_API_KEY
+bunq --profile me oauth-client register
+
+# Each client approves via OAuth (they scan the QR code with their bunq app) ...
+bunq login --profile acme
+# ... or gives you an API key
+bunq login --profile jansen --token THEIR_API_KEY
+
+bunq profiles list             # name, client name, environment, read-only, logged in
+bunq profiles use acme         # set the default profile
+bunq profiles rename jansen jansen-bv
+bunq profiles set acme --read-only   # block commands that change data
+```
+
+Select a profile per command with `--profile`/`-p` or the `BUNQ_PROFILE` environment variable; otherwise the default profile is used. With several profiles and no default, the CLI refuses to guess.
+
+Confirmation prompts show which client you're acting for:
+
+```
+[Acme B.V. (acme)] Pay 750.00 EUR to Landlord B.V. (NL02ABNA0123456789) from the primary account? [y/N]
+```
+
+Pass `--yes` to skip the prompt in scripts.
+
+### Running a command for all clients
+
+`--all-profiles` runs a read-only command for every profile and merges the results, adding a `profile` column:
+
+```bash
+bunq --all-profiles accounts list
+bunq --all-profiles --output json payments list --count 10
+bunq --all-profiles statements create --from 2026-01-01 --to 2026-03-31
+bunq --all-profiles statements download 123 -o "statements/{profile}.csv"
+```
+
+Commands that change data (payments, cards, callbacks, ...) are refused. A failure for one client is reported on stderr and doesn't stop the others; the exit code is 1 if any profile failed.
+
+Accessing other bunq users' data is subject to bunq's API terms and may require a PSD2 license; check this before using the CLI for clients.
+
+## Sandbox mode
+
+Bunq provides a sandbox environment for testing. To use it:
+
+```bash
+bunq login --sandbox
+bunq login --token YOUR_SANDBOX_TOKEN --sandbox
+```
+
+Sandbox mode uses the `https://public-api.sandbox.bunq.com` endpoint instead of production.
+
+Create a sandbox test user and log in with it as a new profile:
+
+```bash
+bunq sandbox create-user --login sandbox-test
+```
+
+Without `--login` the new user's API key is printed. To get sandbox money, request it from bunq's test account:
+
+```bash
+bunq requests create --counterparty-email sugardaddy@bunq.com --amount 500.00 --description "Sandbox money"
+```
+
+## Output formats
+
+By default the CLI prints tables when you're in a terminal, and JSON when output is piped:
+
+```bash
+# Human-readable table
+bunq accounts list
+
+# JSON for scripting
+bunq accounts list | jq '.[].description'
+
+# Force a format
+bunq accounts list --output json
+bunq accounts list --output table
+```
+
+## Pagination
+
+All `list` commands return the first page of results by default. To fetch everything:
+
+```bash
+bunq payments list --all
+```
+
+Or navigate manually:
+
+```bash
+bunq payments list --count 50 --older-id 12345
+bunq payments list --newer-id 67890
+```
+
+The `--all` flag handles Bunq's cursor-based pagination automatically.
+
+## Global options
+
+These can be used with any command:
+
+| Option | Description |
+|---|---|
+| `--help` | Show help for a command |
+| `--version` | Show version |
+| `-v, --verbose` | Print HTTP requests to stderr |
+| `-q, --quiet` | Suppress non-error output |
+| `--token TOKEN` | Override the stored API token |
+| `--output auto\|json\|table` | Force output format |
+| `--no-color` | Disable colored output |
+| `--config PATH` | Use a custom config file |
+| `--sandbox` | Use the sandbox environment |

bunq_cli-0.2.0/docs/payment-requests.md

@@ -0,0 +1,67 @@
+# Payment Requests
+
+Payment requests (called "Request Inquiries" in the Bunq API) let you request money from other people. The recipient receives a notification and can accept or reject the request.
+
+## Creating a request
+
+Request money from another Bunq user by email or phone:
+
+```bash
+bunq requests create \
+  --account 12345 \
+  --amount 35.00 \
+  --currency EUR \
+  --counterparty-email friend@example.com \
+  --description "Concert tickets"
+```
+
+Or by phone number:
+
+```bash
+bunq requests create \
+  --account 12345 \
+  --amount 15.00 \
+  --counterparty-phone "+31612345678" \
+  --description "Lunch"
+```
+
+## Listing sent requests
+
+```bash
+# Requests you sent
+bunq requests list --account 12345
+
+# All pages
+bunq requests list --account 12345 --all
+```
+
+## Viewing a request
+
+```bash
+bunq requests get 67890 --account 12345
+```
+
+The output shows the status: `PENDING`, `ACCEPTED`, `REJECTED`, `REVOKED`, or `EXPIRED`.
+
+## Revoking a request
+
+Cancel a pending request:
+
+```bash
+bunq requests revoke 67890 --account 12345
+```
+
+## Incoming requests
+
+View payment requests others have sent to you:
+
+```bash
+# List incoming requests
+bunq requests incoming --account 12345
+
+# Accept a request
+bunq requests accept 67890 --account 12345
+
+# Reject a request
+bunq requests reject 67890 --account 12345
+```