moneybird-cli 0.1.0__tar.gz

moneybird_cli-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+**/__pycache__
+*.egg-info
+dist/
+build/
+.venv/

moneybird_cli-0.1.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.

moneybird_cli-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: moneybird-cli
+Version: 0.1.0
+Summary: Command-line interface for the Moneybird API
+Author-email: Koert van der Veer <koert@ondergetekende.nl>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ondergetekende/moneybird-cli
+Project-URL: Repository, https://github.com/ondergetekende/moneybird-cli
+Project-URL: Issues, https://github.com/ondergetekende/moneybird-cli/issues
+Keywords: moneybird,accounting,cli,invoicing,bookkeeping
+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 :: Accounting
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: requests>=2.31
+Requires-Dist: tabulate>=0.9
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+Dynamic: license-file
+
+# Moneybird CLI
+
+A command-line interface for [Moneybird](https://www.moneybird.com/), the online accounting platform. Manage invoices, contacts, expenses, time tracking, and more from your terminal.
+
+> **Disclaimer:** This project is not affiliated with, endorsed by, or in any way associated with Moneybird B.V. "Moneybird" is a trademark of Moneybird B.V. This is an independent, open-source tool that uses the public Moneybird API.
+
+## Quick start
+
+```bash
+pip install moneybird-cli
+moneybird login --token YOUR_API_TOKEN
+moneybird contacts list
+moneybird sales-invoices list --state open
+```
+
+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, multiple administrations, output formats, pagination, global options |
+| [Contacts](docs/contacts.md) | Customer and supplier management: list, search, filter, create, update, archive |
+| [Invoicing](docs/invoicing.md) | Sales invoices, estimates, recurring invoices, external invoices, payments, credit notes, PDF downloads |
+| [Products & Subscriptions](docs/products-and-subscriptions.md) | Reusable product definitions, subscription lifecycle management |
+| [Financial](docs/financial.md) | Bank accounts, transactions, reconciliation, purchase transactions |
+| [Documents](docs/documents.md) | Purchase invoices, receipts, journal entries, general documents, assets |
+| [Time Tracking](docs/time-tracking.md) | Projects and time entries |
+| [Reports](docs/reports.md) | Profit/loss, balance sheet, cash flow, tax, debtors/creditors, and more |
+| [Settings](docs/settings.md) | Ledger accounts, tax rates, webhooks |
+
+## Tech stack
+
+- [Python](https://www.python.org/) >= 3.11
+- [Click](https://click.palletsprojects.com/) for the CLI framework
+- [Requests](https://requests.readthedocs.io/) for HTTP
+- [Tabulate](https://pypi.org/project/tabulate/) for table formatting
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

moneybird_cli-0.1.0/README.md

@@ -0,0 +1,41 @@
+# Moneybird CLI
+
+A command-line interface for [Moneybird](https://www.moneybird.com/), the online accounting platform. Manage invoices, contacts, expenses, time tracking, and more from your terminal.
+
+> **Disclaimer:** This project is not affiliated with, endorsed by, or in any way associated with Moneybird B.V. "Moneybird" is a trademark of Moneybird B.V. This is an independent, open-source tool that uses the public Moneybird API.
+
+## Quick start
+
+```bash
+pip install moneybird-cli
+moneybird login --token YOUR_API_TOKEN
+moneybird contacts list
+moneybird sales-invoices list --state open
+```
+
+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, multiple administrations, output formats, pagination, global options |
+| [Contacts](docs/contacts.md) | Customer and supplier management: list, search, filter, create, update, archive |
+| [Invoicing](docs/invoicing.md) | Sales invoices, estimates, recurring invoices, external invoices, payments, credit notes, PDF downloads |
+| [Products & Subscriptions](docs/products-and-subscriptions.md) | Reusable product definitions, subscription lifecycle management |
+| [Financial](docs/financial.md) | Bank accounts, transactions, reconciliation, purchase transactions |
+| [Documents](docs/documents.md) | Purchase invoices, receipts, journal entries, general documents, assets |
+| [Time Tracking](docs/time-tracking.md) | Projects and time entries |
+| [Reports](docs/reports.md) | Profit/loss, balance sheet, cash flow, tax, debtors/creditors, and more |
+| [Settings](docs/settings.md) | Ledger accounts, tax rates, webhooks |
+
+## Tech stack
+
+- [Python](https://www.python.org/) >= 3.11
+- [Click](https://click.palletsprojects.com/) for the CLI framework
+- [Requests](https://requests.readthedocs.io/) for HTTP
+- [Tabulate](https://pypi.org/project/tabulate/) for table formatting
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

moneybird_cli-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "moneybird-cli"
+version = "0.1.0"
+description = "Command-line interface for the Moneybird API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+keywords = ["moneybird", "accounting", "cli", "invoicing", "bookkeeping"]
+authors = [
+    { name = "Koert van der Veer", email = "koert@ondergetekende.nl" },
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "Intended Audience :: System Administrators",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Accounting",
+]
+dependencies = [
+    "click>=8.1",
+    "requests>=2.31",
+    "tabulate>=0.9",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "responses>=0.23",
+]
+
+[project.urls]
+Homepage = "https://github.com/ondergetekende/moneybird-cli"
+Repository = "https://github.com/ondergetekende/moneybird-cli"
+Issues = "https://github.com/ondergetekende/moneybird-cli/issues"
+
+[project.scripts]
+moneybird = "moneybird_cli.main:cli"
+
+[tool.setuptools.packages.find]
+where = ["src"]

moneybird_cli-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

moneybird_cli-0.1.0/src/moneybird_cli/__init__.py

@@ -0,0 +1 @@
+"""Moneybird CLI - Command-line interface for the Moneybird API."""

moneybird_cli-0.1.0/src/moneybird_cli/client.py

@@ -0,0 +1,176 @@
+"""Moneybird API client with pagination, rate limiting, and error handling."""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+import click
+import requests
+
+logger = logging.getLogger(__name__)
+
+API_BASE = "https://moneybird.com/api/v2"
+
+
+class MoneybirdApiError(click.ClickException):
+    """API error with HTTP status code context."""
+
+    def __init__(self, status_code: int, message: str) -> None:
+        self.status_code = status_code
+        super().__init__(f"API error {status_code}: {message}")
+
+
+class MoneybirdClient:
+    """HTTP client for the Moneybird API."""
+
+    def __init__(
+        self,
+        token: str,
+        administration_id: str,
+        dry_run: bool = False,
+        verbose: bool = False,
+        timezone: str | None = None,
+    ) -> None:
+        self.token = token
+        self.administration_id = administration_id
+        self.dry_run = dry_run
+        self.verbose = verbose
+        self.base_url = f"{API_BASE}/{administration_id}"
+        self.session = requests.Session()
+        headers = {
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        if timezone:
+            headers["Time-Zone"] = timezone
+        self.session.headers.update(headers)
+
+    def _url(self, path: str) -> str:
+        return f"{self.base_url}/{path}.json"
+
+    def _handle_response(self, response: requests.Response) -> tuple[Any, requests.Response]:
+        if response.status_code == 429:
+            retry_after = int(response.headers.get("Retry-After", "60"))
+            logger.warning("Rate limited. Retrying after %d seconds.", retry_after)
+            time.sleep(retry_after)
+            return self._handle_response(
+                self.session.send(response.request)  # type: ignore[arg-type]
+            )
+
+        if response.status_code == 204:
+            return None, response
+
+        if response.status_code >= 400:
+            try:
+                body = response.json()
+                message = body.get("error", body.get("message", response.text))
+            except (ValueError, KeyError):
+                message = response.text
+            raise MoneybirdApiError(response.status_code, message)
+
+        if not response.content:
+            return None, response
+        return response.json(), response
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: dict | None = None,
+        json: dict | None = None,
+    ) -> Any:
+        url = self._url(path)
+        if self.verbose:
+            click.echo(f"{method.upper()} {url}", err=True)
+            if json:
+                click.echo(f"  Body: {json}", err=True)
+
+        if self.dry_run and method.upper() != "GET":
+            click.echo(f"[dry-run] {method.upper()} {url}", err=True)
+            return None
+
+        response = self.session.request(method, url, params=params, json=json)
+        data, _ = self._handle_response(response)
+        return data
+
+    def _request_with_headers(
+        self,
+        method: str,
+        path: str,
+        params: dict | None = None,
+    ) -> tuple[Any, requests.Response]:
+        """Like _request, but also returns the response for header inspection."""
+        url = self._url(path)
+        if self.verbose:
+            click.echo(f"{method.upper()} {url}", err=True)
+
+        response = self.session.request(method, url, params=params)
+        return self._handle_response(response)
+
+    @staticmethod
+    def _respect_rate_limit(response: requests.Response, verbose: bool = False) -> None:
+        """Sleep if rate limit is nearly exhausted."""
+        remaining = response.headers.get("RateLimit-Remaining")
+        if remaining is not None and int(remaining) <= 1:
+            reset = int(response.headers.get("RateLimit-Reset", "60"))
+            if verbose:
+                click.echo(f"Rate limit nearly exhausted, waiting {reset}s.", err=True)
+            time.sleep(reset)
+
+    def get(self, path: str, params: dict | None = None) -> Any:
+        return self._request("GET", path, params=params)
+
+    @staticmethod
+    def list_administrations(token: str) -> list[dict]:
+        """List all administrations accessible with the given token."""
+        url = f"{API_BASE}/administrations.json"
+        response = requests.get(
+            url,
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Accept": "application/json",
+            },
+        )
+        if response.status_code >= 400:
+            try:
+                body = response.json()
+                message = body.get("error", body.get("message", response.text))
+            except (ValueError, KeyError):
+                message = response.text
+            raise MoneybirdApiError(response.status_code, message)
+        return response.json()
+
+    def get_all(
+        self, path: str, params: dict | None = None, per_page: int = 100
+    ) -> list[dict]:
+        """GET with automatic pagination. Returns all results.
+
+        Respects rate limit headers: pauses when RateLimit-Remaining is low.
+        """
+        params = dict(params or {})
+        params["per_page"] = per_page
+        page = 1
+        results: list[dict] = []
+        while True:
+            params["page"] = page
+            data, response = self._request_with_headers("GET", path, params=params)
+            if not data:
+                break
+            results.extend(data)
+            if len(data) < per_page:
+                break
+            self._respect_rate_limit(response, verbose=self.verbose)
+            page += 1
+        return results
+
+    def post(self, path: str, json: dict | None = None) -> Any:
+        return self._request("POST", path, json=json)
+
+    def patch(self, path: str, json: dict | None = None) -> Any:
+        return self._request("PATCH", path, json=json)
+
+    def delete(self, path: str) -> Any:
+        return self._request("DELETE", path)

moneybird_cli-0.1.0/src/moneybird_cli/commands/assets.py

@@ -0,0 +1,87 @@
+"""Assets commands."""
+
+from __future__ import annotations
+
+import click
+
+from moneybird_cli.main import pass_context, Context
+from moneybird_cli.output import echo_output
+
+LIST_COLUMNS = ["id", "name", "purchase_date", "purchase_value", "current_value"]
+
+
+@click.group()
+def assets() -> None:
+    """Manage assets (company cars, laptops, furniture, etc.)."""
+
+
+@assets.command("list")
+@click.option("--all", "fetch_all", is_flag=True, help="Fetch all pages (respects rate limits).")
+@click.option("--include-inactive", is_flag=True, help="Include inactive assets.")
+@click.option("--ledger-account-id", help="Filter by ledger account ID.")
+@click.option("--page", type=int, default=None, help="Page number (default: 1).")
+@click.option("--per-page", type=int, default=None, help="Results per page (max 100).")
+@pass_context
+def list_assets(ctx: Context, fetch_all: bool, include_inactive: bool, ledger_account_id: str | None, page: int | None, per_page: int | None) -> None:
+    """List assets. Returns the first page by default; use --all to fetch everything."""
+    client = ctx.get_client()
+    params: dict = {}
+    if include_inactive:
+        params["active"] = "false"
+    if ledger_account_id:
+        params["ledger_account_id"] = ledger_account_id
+    if fetch_all:
+        data = client.get_all("assets", params=params, per_page=per_page or 100)
+    else:
+        params["page"] = page or 1
+        if per_page:
+            params["per_page"] = per_page
+        data = client.get("assets", params=params)
+    echo_output(data, fmt=ctx.output_format, columns=LIST_COLUMNS)
+
+
+@assets.command("get")
+@click.argument("id")
+@pass_context
+def get_asset(ctx: Context, id: str) -> None:
+    """Get a single asset by ID."""
+    client = ctx.get_client()
+    data = client.get(f"assets/{id}")
+    echo_output(data, fmt=ctx.output_format)
+
+
+@assets.command("create")
+@click.option("--name", required=True, help="Asset name.")
+@click.option("--purchase-date", help="Purchase date (YYYY-MM-DD).")
+@click.option("--purchase-value", help="Purchase value.")
+@pass_context
+def create_asset(ctx: Context, **kwargs: str | None) -> None:
+    """Create a new asset."""
+    client = ctx.get_client()
+    asset = {k: v for k, v in kwargs.items() if v is not None}
+    data = client.post("assets", json={"asset": asset})
+    echo_output(data, fmt=ctx.output_format)
+
+
+@assets.command("update")
+@click.argument("id")
+@click.option("--name", help="Asset name.")
+@pass_context
+def update_asset(ctx: Context, id: str, **kwargs: str | None) -> None:
+    """Update an asset by ID."""
+    client = ctx.get_client()
+    asset = {k: v for k, v in kwargs.items() if v is not None}
+    data = client.patch(f"assets/{id}", json={"asset": asset})
+    echo_output(data, fmt=ctx.output_format)
+
+
+@assets.command("delete")
+@click.argument("id")
+@click.confirmation_option(prompt="Are you sure you want to delete this asset?")
+@pass_context
+def delete_asset(ctx: Context, id: str) -> None:
+    """Delete an asset by ID."""
+    client = ctx.get_client()
+    client.delete(f"assets/{id}")
+    if not ctx.quiet:
+        click.echo(f"Asset {id} deleted.")

moneybird_cli-0.1.0/src/moneybird_cli/commands/contacts.py

@@ -0,0 +1,159 @@
+"""Contacts commands."""
+
+from __future__ import annotations
+
+import click
+
+from moneybird_cli.main import pass_context, Context
+from moneybird_cli.output import echo_output
+
+LIST_COLUMNS = ["id", "company_name", "firstname", "lastname", "email"]
+
+
+@click.group()
+def contacts() -> None:
+    """Manage contacts."""
+
+
+@contacts.command("list")
+@click.option("--all", "fetch_all", is_flag=True, help="Fetch all pages (respects rate limits).")
+@click.option("--page", type=int, default=None, help="Page number (default: 1).")
+@click.option("--per-page", type=int, default=None, help="Results per page (max 100).")
+@click.option("--include-archived", is_flag=True, help="Include archived contacts.")
+@pass_context
+def list_contacts(ctx: Context, fetch_all: bool, page: int | None, per_page: int | None, include_archived: bool) -> None:
+    """List contacts. Returns the first page by default; use --all to fetch everything."""
+    client = ctx.get_client()
+    params: dict = {}
+    if include_archived:
+        params["include_archived"] = "true"
+    if fetch_all:
+        data = client.get_all("contacts", params=params, per_page=per_page or 100)
+    else:
+        params["page"] = page or 1
+        if per_page:
+            params["per_page"] = per_page
+        data = client.get("contacts", params=params)
+    echo_output(data, fmt=ctx.output_format, columns=LIST_COLUMNS)
+
+
+@contacts.command("get")
+@click.argument("id")
+@pass_context
+def get_contact(ctx: Context, id: str) -> None:
+    """Get a single contact by ID."""
+    client = ctx.get_client()
+    data = client.get(f"contacts/{id}")
+    echo_output(data, fmt=ctx.output_format)
+
+
+@contacts.command("search")
+@click.argument("query")
+@pass_context
+def search_contacts(ctx: Context, query: str) -> None:
+    """Search contacts by name or email."""
+    client = ctx.get_client()
+    data = client.get_all("contacts", params={"query": query})
+    echo_output(data, fmt=ctx.output_format, columns=LIST_COLUMNS)
+
+
+@contacts.command("filter")
+@click.option("--created-after", help="Filter by creation date (ISO 8601).")
+@click.option("--updated-after", help="Filter by update date (ISO 8601).")
+@click.option("--first-name", help="Filter by first name.")
+@click.option("--last-name", help="Filter by last name.")
+@pass_context
+def filter_contacts(
+    ctx: Context,
+    created_after: str | None,
+    updated_after: str | None,
+    first_name: str | None,
+    last_name: str | None,
+) -> None:
+    """Filter contacts by criteria."""
+    client = ctx.get_client()
+    params: dict = {}
+    if created_after:
+        params["filter"] = f"created_after:{created_after}"
+    if updated_after:
+        params["filter"] = f"updated_after:{updated_after}"
+    if first_name:
+        params["filter"] = f"first_name:{first_name}"
+    if last_name:
+        params["filter"] = f"last_name:{last_name}"
+    data = client.get_all("contacts/filter", params=params)
+    echo_output(data, fmt=ctx.output_format, columns=LIST_COLUMNS)
+
+
+@contacts.command("create")
+@click.option("--company-name", help="Company name.")
+@click.option("--firstname", help="First name.")
+@click.option("--lastname", help="Last name.")
+@click.option("--email", help="Email address.")
+@click.option("--phone", help="Phone number.")
+@click.option("--address1", help="Address line 1.")
+@click.option("--address2", help="Address line 2.")
+@click.option("--zipcode", help="Zip code.")
+@click.option("--city", help="City.")
+@click.option("--country", help="Country code (e.g., NL).")
+@click.option("--delivery-method", type=click.Choice(["Email", "Simplerinvoicing", "Post", "Manual"]), help="Invoice delivery method.")
+@pass_context
+def create_contact(ctx: Context, **kwargs: str | None) -> None:
+    """Create a new contact."""
+    client = ctx.get_client()
+    contact = {k.replace("_", ""): v for k, v in kwargs.items() if v is not None}
+    # Map back to API field names
+    field_map = {
+        "companyname": "company_name",
+        "address1": "address1",
+        "address2": "address2",
+        "deliverymethod": "delivery_method",
+    }
+    api_contact = {}
+    for k, v in contact.items():
+        api_contact[field_map.get(k, k)] = v
+    data = client.post("contacts", json={"contact": api_contact})
+    echo_output(data, fmt=ctx.output_format)
+
+
+@contacts.command("update")
+@click.argument("id")
+@click.option("--company-name", help="Company name.")
+@click.option("--firstname", help="First name.")
+@click.option("--lastname", help="Last name.")
+@click.option("--email", help="Email address.")
+@click.option("--phone", help="Phone number.")
+@pass_context
+def update_contact(ctx: Context, id: str, **kwargs: str | None) -> None:
+    """Update a contact by ID."""
+    client = ctx.get_client()
+    contact = {k: v for k, v in kwargs.items() if v is not None}
+    field_map = {"company_name": "company_name"}
+    api_contact = {}
+    for k, v in contact.items():
+        api_contact[field_map.get(k, k)] = v
+    data = client.patch(f"contacts/{id}", json={"contact": api_contact})
+    echo_output(data, fmt=ctx.output_format)
+
+
+@contacts.command("delete")
+@click.argument("id")
+@click.confirmation_option(prompt="Are you sure you want to delete this contact?")
+@pass_context
+def delete_contact(ctx: Context, id: str) -> None:
+    """Delete a contact by ID."""
+    client = ctx.get_client()
+    client.delete(f"contacts/{id}")
+    if not ctx.quiet:
+        click.echo(f"Contact {id} deleted.")
+
+
+@contacts.command("archive")
+@click.argument("id")
+@pass_context
+def archive_contact(ctx: Context, id: str) -> None:
+    """Archive a contact by ID."""
+    client = ctx.get_client()
+    client.patch(f"contacts/{id}/archive")
+    if not ctx.quiet:
+        click.echo(f"Contact {id} archived.")