Skip to content

USER_GUIDE.md

Latest commit

 

History

History
607 lines (456 loc) · 20.6 KB

USER_GUIDE.md

File metadata and controls

607 lines (456 loc) · 20.6 KB
Raw

Benutzerhandbuch

Dieses Dokument richtet sich an Nutzer:innen des CLI‑Tools. Es erklärt Installation, Konfiguration und typische Workflows.

Voraussetzungen

  • Python 3.11+
  • Optional: openpyxl für XLSX‑Export

Installation

Empfohlene Installation (pipx)

pipx installiert euer global in einer isolierten Umgebung, ohne dass du je eine virtuelle Umgebung aktivieren musst:

# euer installieren
pipx install git+https://github.com/curiousmarkus/euer.git

Danach ist euer sofort und dauerhaft in jedem Terminal verfügbar.

Update auf die neueste Version:

pipx upgrade euercli

Bestehende Installation aktualisieren

Wenn du bereits eine lokale euer.db nutzt, aktualisiere nicht nur das CLI, sondern auch die Datenbankstruktur. euer init ist dafür bewusst idempotent: Es kann gefahrlos erneut im Buchhaltungsordner ausgeführt werden und ergänzt fehlende Tabellen oder Spalten.

Empfohlener Ablauf nach jedem Update:

cd /pfad/zu/deinem/buchhaltungsordner

# Backup vor Schema-Migration
cp euer.db euer.backup.db

# CLI aktualisieren
pipx upgrade euercli

# lokale Datenbank migrieren
euer init

# offene Nacharbeiten prüfen
euer incomplete list
euer summary --year 2026

Wenn du mehrere Buchhaltungsordner oder Datenbanken hast, führe euer init für jede Datenbank aus. Alternativ kannst du die Datenbank explizit angeben:

euer --db /pfad/zu/euer.db init

Prüfe danach die Release Notes. pipx upgrade aktualisiert nicht automatisch Dateien, die du bereits in deine KI-Anwendung kopiert hast. Bei Releases mit geänderter Agenten-Logik musst du diese lokalen Kopien zusätzlich aus dem aktuellen Release/Repo aktualisieren:

  • docs/skills/euer-buchhaltung/SKILL.md in den Skill-Ordner deiner lokalen KI-Anwendung kopieren.
  • docs/templates/accountant-agent.md in deiner lokalen Agenten-Konfiguration ersetzen.
  • docs/templates/onboarding-prompt.md erneut nutzen, wenn die Release Notes eine Änderung an deiner persönlichen AGENTS.md verlangen.

Die persönliche AGENTS.md enthält deine individuellen Pfade, Konten und Regeln. Überschreibe sie deshalb nicht blind. Wenn eine Release Note eine Anpassung verlangt, kannst du deinen KI-Agenten gezielt damit beauftragen:

Lies docs/RELEASE_NOTES.md und prüfe nur die Hinweise für meine installierte Version.
Aktualisiere meine lokale AGENTS.md entsprechend, erhalte aber alle persönlichen
Pfade, Konten, Lieferanten-Mappings und Steuerdaten.

KI-Agenten Konfiguration

Das CLI-Tool ist so konzipiert, dass KI-Agenten die Buchhaltung automatisieren können. Im Ordner docs/templates/ findest du Vorlagen für die Agent-Konfiguration.

Verfügbare Templates

Datei Beschreibung
accountant-agent.md Agent-Definition für KI-Buchhalter (Regeln, Workflows, Steuerlogik)
Agents-Template.md Template für persönliche Buchhaltungsdaten (kann geführt mit dem Onboarding-Prompt erstellt werden)
onboarding-prompt.md Interview-Prompt zur Erstellung einer personalisierten AGENTS.md

Schnellstart für KI-Agenten

  1. Onboarding durchführen:

    • Kopiere den Inhalt von docs/templates/onboarding-prompt.md in einen neuen LLM-Chat
    • Der Assistent führt ein Interview und erstellt deine persönliche AGENTS.md

  2. Agent konfigurieren:

    • Speichere die generierte AGENTS.md in deinem Buchhaltungsordner
    • Füge die accountant-agent.md als Agent-Definition zu deinem Agent-Framework hinzu
    • kopiere den Skill in den korrekten Pfad, so dass dein Agent darauf Zugriff hat: docs/skills/euer-buchhaltung/SKILL.md
    • Starte deinen KI-Agenten im Buchhaltungsordner (so hat er Zugriff auf AGENTS.md als Kontext)

  3. CLI einrichten:

    • Führe euer init und euer setup aus, um die Datenbank und die Konfiguration anzulegen (achte darauf, dass du im Buchhaltungsordner bist!)
    • Die Konfiguration wird unter macOS/Linux in ~/.config/euer/config.toml gespeichert, unter Windows in %APPDATA%\\euer\\config.toml

Empfohlene Tools für Agenten

Erste Schritte

Nach der Installation

Wechsle in deinen Buchhaltungs-Arbeitsordner, z.B.:

# Beispiel: Separater Ordner für Buchhaltungsdaten
mkdir -p ~/Documents/Buchhaltung
cd ~/Documents/Buchhaltung

# Datenbank anlegen (erstellt euer.db + exports/ hier)
euer init

# Beleg-/Export-Pfade und Steuermodus konfigurieren (empfohlen)
euer setup

# Konfiguration prüfen
euer config show

# Erste Buchung
euer add expense --payment-date 2026-02-02 --vendor "Test" --category "Laufende EDV-Kosten" --amount -10.00

Wo liegen meine Daten?

  • Datenbank: euer.db im aktuellen Verzeichnis (wo du euer init ausgeführt hast)
  • Konfiguration: ~/.config/euer/config.toml (systemweit)
  • Belege: Pfade in der Konfiguration festgelegt
  • Exports: exports/ im aktuellen Verzeichnis oder als konkreter Pfad in der Config festgelegt. exports.directory unterstützt keinen {year}-Platzhalter.

Grundbegriffe

  • Ausgaben haben immer negative Beträge (--amount -10.00).
  • Einnahmen haben immer positive Beträge (--amount 10.00).
  • Privateinlagen/Privatentnahmen (add private-*) verwenden immer positive Beträge; die Richtung ergibt sich aus dem Command.
  • Kategorien sind vorgegeben und müssen existieren: euer list categories.
  • Buchungskonten (--ledger-account) sind optional und werden in der Config als [[ledger_accounts]] gepflegt. Sie setzen die Kategorie automatisch.
  • Datumsfelder: payment_date (Wertstellung, EÜR-relevant) und invoice_date (Rechnungsdatum). Mindestens eines der beiden muss gesetzt sein.
  • Belege können geprüft und geöffnet werden, wenn Pfade konfiguriert sind.
  • Datenbank: Standard euer.db im aktuellen Verzeichnis; alternativ via --db PFAD.
  • Arbeitsverzeichnis: Das Tool sucht nach euer.db dort, wo du es aufrufst. Wechsle vor dem Arbeiten in deinen Buchhaltungsordner!

Typische Befehle

Ausgaben & Einnahmen erfassen

# Ausgabe
euer add expense --payment-date 2026-01-15 --invoice-date 2026-01-14 --vendor "1und1" \
    --category "Telekommunikation" --amount -39.99 --account "Sparkasse Giro"

# Ausgabe mit Kontenrahmen
euer add expense --payment-date 2026-01-15 --vendor "Hetzner" \
    --ledger-account hosting --amount -29.00 --account "g-n26"

# Einnahme
euer add income --payment-date 2026-01-20 --invoice-date 2026-01-18 --source "Kunde ABC" \
    --category "Umsatzsteuerpflichtige Betriebseinnahmen" --amount 1500.00

# Einnahme bei Regelbesteuerung mit explizitem USt-Satz
euer add income --payment-date 2026-01-20 --source "Kunde ABC" \
    --category "Umsatzsteuerpflichtige Betriebseinnahmen" --amount 1190.00 --vat-rate 19

# Einnahme mit Kontenrahmen
euer add income --payment-date 2026-01-20 --source "Kunde ABC" \
    --ledger-account erloese-19 --amount 1500.00

Anzeigen & Filtern

# Default: aktuelles Jahr
euer list expenses --year 2026
euer list expenses --year 2026 --month 1
euer list expenses --year 2026 --full
euer list income --year 2026
euer list income --year 2026 --full
euer list categories
euer list ledger-accounts
euer list ledger-accounts --category "Laufende EDV-Kosten"

Hinweis: list ... --format csv gibt die Liste als CSV auf stdout aus (für Pipes/Redirects). Hinweis: euer list expenses --full erweitert die Tabellenansicht um fachliche Details wie Konto, Beleg, Fremdw. und Notiz. Hinweis: euer list income zeigt in der Tabellenansicht die Spalte USt (vat_output) immer an. Hinweis: RC-Ausgaben zeigen in der Spalte RC den Typ eu oder third-country. Hinweis: euer list income --full ergänzt die Tabellenansicht um die Spalte Notiz. Hinweis: Kategorien werden in Listen als (<EÜR-Zeile>) <Name> dargestellt, z.B. (51) Arbeitsmittel.

Privatvorgänge

# Direkte Privatvorgänge
euer add private-deposit --date 2026-01-15 --amount 500 --description "Einlage"
euer add private-withdrawal --date 2026-01-20 --amount 200 --description "Entnahme"

# Als Liste (inkl. Sacheinlagen aus Ausgaben mit privater Zahlung)
euer list private-transfers --year 2026
euer list private-deposits --year 2026
euer list private-withdrawals --year 2026

Bei Ausgaben kannst du private Zahlung explizit markieren:

euer add expense --payment-date 2026-01-10 --vendor "Adobe" \
  --category "Laufende EDV-Kosten" --amount -22.99 --private-paid

Korrigieren & Löschen

# Ausgabe korrigieren
euer update expense 42 --amount -25.00 --notes "Korrigiert"
euer update expense 42 --payment-date 2026-01-17
euer update expense 42 --invoice-date 2026-01-15
euer update expense 42 --ledger-account hosting
euer update expense 42 --private-paid
euer update expense 42 --no-private-paid
euer update expense 42 --rc eu
euer update expense 42 --rc third-country
euer update expense 42 --no-rc
euer update income 17 --vat-rate 7
euer update income 17 --tax-free

# Privatvorgang korrigieren
euer update private-transfer 7 --amount 600 --description "Korrektur"
euer update private-transfer 7 --clear-related-expense

# Löschen
euer delete expense 42
euer delete expense 42 --force
euer delete private-transfer 7 --force

# Änderungshistorie
euer audit 42 --table expenses

Zusammenfassung & Export

euer summary --year 2026
euer summary --year 2026 --include-private
euer private-summary --year 2026
euer reconcile private --year 2026 --dry-run
euer reconcile private --year 2026
euer vat-report --year 2026
euer vat-report --year 2026 --quarter 1
euer vat-report --year 2026 --month 3 --format csv --output exports/

# Default: CSV, ohne --year = alle Jahre
euer export
euer export --year 2026
# XLSX benötigt openpyxl:
euer export --year 2026 --format xlsx

Hinweis: export schreibt Dateien ins Export-Verzeichnis:

  • Ausgaben
  • Einnahmen
  • PrivateTransfers (direkte Privatvorgänge)
  • Sacheinlagen (aus expenses.is_private_paid abgeleitet)

exports.directory ist ein konkreter Ordner und unterstützt keinen {year}-Platzhalter. Für jahresweise Ablage nutze entweder --output mit einem konkreten Jahresordner oder setze die Config entsprechend um:

euer export --year 2026 --output "/pfad/zu/Buchhaltung/2026/Exporte"

Hinweis: Exporte für Ausgaben und Einnahmen enthalten zusätzlich die Spalten Buchungskonto, Kontonummer, Steuersatz und Steuerklasse.

Hinweis: Für die Kategorie Bewirtungsaufwendungen rechnet euer summary den Aufwand automatisch als 70% abziehbar / 30% nicht abziehbar. In list expenses und Exporten bleibt der Betrag 100%.

SQL‑Abfragen (nur lesend)

# Ausgabe als CSV auf stdout (nur SELECT)
euer query "SELECT id, payment_date, invoice_date, vendor, amount_eur FROM expenses WHERE vendor LIKE '%OpenAI%' ORDER BY payment_date DESC"

Hinweis: query ist nur für SELECT‑Abfragen. Keine Änderungen/Schreiboperationen.

Bulk‑Import & Unvollständige Einträge

euer import --file import.csv --format csv
euer import --schema  # Schema + Beispiele

euer incomplete list
euer incomplete list --format csv

Hinweise zum Import:

  • Pflichtfelder: type, party, amount_eur und mindestens eines aus payment_date/invoice_date (date ist Alias für payment_date)
  • Optionale Felder: category, account, ledger_account, foreign_amount, receipt_name, notes, rc, private_paid, vat_input, vat_output, vat_rate, vat_code, tax_free
  • Fehlende Pflichtfelder führen zu einem Import-Abbruch.
  • type kann fehlen, wenn amount_eur ein Vorzeichen hat (negativ = Ausgabe, positiv = Einnahme).
  • CSV‑Exports für Ausgaben/Einnahmen können direkt re‑importiert werden (Spaltennamen sind gemappt).
  • Exporte PrivateTransfers und Sacheinlagen sind nicht als Standard-Importquelle vorgesehen.
  • Kategorien mit "(NN)" werden beim Import automatisch bereinigt.
  • Alias‑Keys werden akzeptiert (z.B. EUR, Belegname, Lieferant, Quelle, RC).
  • private_paid=true|1|yes|X markiert eine importierte Ausgabe manuell als Sacheinlage.
  • rc akzeptiert eu oder third-country; Legacy-Werte rc=true|X brauchen zusätzlich eine Jurisdiktionsspalte.
  • vat_rate akzeptiert 19, 7, 0 sowie Werte mit %.
  • vat_code akzeptiert persistierte Steuerklassen wie output_standard_19, output_reduced_7, output_zero_0, output_tax_free_no_vorsteuer, input_invoice, reverse_charge_eu, reverse_charge_third_country.

Kontenrahmen

Der optionale Kontenrahmen lebt in ~/.config/euer/config.toml und ordnet frei benannte Buchungskonten einer bestehenden EÜR-Kategorie zu:

[[ledger_accounts]]
key = "hosting"
name = "Hosting & Cloud-Dienste"
category = "Laufende EDV-Kosten"
account_number = "4940"

[[ledger_accounts]]
key = "erloese-19"
name = "Erlöse 19% USt"
category = "Umsatzsteuerpflichtige Betriebseinnahmen"
account_number = "8400"

Wichtig:

  • --account bleibt das Zahlungskonto (Bank-/Kreditkartenkonto).
  • --ledger-account ist das Buchungskonto aus dem Kontenrahmen.
  • euer setup kann Buchungskonten interaktiv anlegen.
  • euer list ledger-accounts zeigt den aktuell konfigurierten Kontenrahmen.
  • Steuerfelder:
    • small_business + rc=eu|third-country: vat_output wird automatisch aus amount_eur * 0.19 berechnet, vat_input wird auf 0.0 gesetzt (Felder können weggelassen werden).
    • small_business + Einnahmen: neue Einnahmen werden als output_tax_free_no_vorsteuer klassifiziert.
    • standard + Ausgaben: --vat bzw. vat_input ist der Vorsteuerbetrag; RC bucht vat_input und vat_output automatisch.
    • standard + Einnahmen: ohne explizite Angabe gilt vat_rate=19. Nutze --vat-rate 7, --vat-rate 0 oder --tax-free für abweichende Fälle. amount_eur wird immer 1:1 als Brutto-Zahlfluss gespeichert.

Workflow für unvollständige Einträge:

  1. Import/Add ausführen → Buchungen werden angelegt (Pflichtfelder müssen vorhanden sein).
  2. euer incomplete list zeigt fehlende Qualitätsfelder: payment_date, invoice_date, category, receipt, vat, account (abhängig von Typ/Steuermodus).
  3. Fehlende Infos per euer update expense|income <ID> nachpflegen. Hinweis: Für die Kategorie Gezahlte USt (57) ist kein Beleg erforderlich.

Beleg‑Verwaltung

Konfiguration

euer setup legt Pfade und den Audit‑User in ~/.config/euer/config.toml an. Belege werden unter einem gemeinsamen Root jahrzentriert erwartet: <root>/<Jahr>/<Typ>/<Belegname>. Mit euer setup --set section.key value kannst du einzelne Werte ohne Prompt setzen.

[receipts]
root = "/pfad/zu/Buchhaltung"
year_dir = "{year}"
expenses_dir = "Ausgaben"
income_dir = "Einnahmen"

[exports]
directory = "/pfad/zu/exports"

[user]
name = "Dein Name"

[accounts]
private = ["privat", "private Kreditkarte"]

Beispiele:

/pfad/zu/Buchhaltung/2026/Ausgaben/2026-01-15_Amazon.pdf
/pfad/zu/Buchhaltung/2026/Einnahmen/2026-01-20_Rechnung_001.pdf

year_dir muss {year} enthalten. Damit sind auch Ordner wie Buchhaltung 2026 möglich:

euer setup --set receipts.root "/pfad/zu/Buchhaltung"
euer setup --set receipts.year_dir "Buchhaltung {year}"
euer setup --set receipts.expenses_dir "Ausgaben"
euer setup --set receipts.income_dir "Einnahmen"

Prüfen & Öffnen

euer receipt check --year 2026
euer receipt check --type expense

euer receipt open 12
euer receipt open 5 --table income

Tipp: Wenn der gespeicherte Belegname keine Dateiendung hat, versucht der Check automatisch .pdf, .jpg, .jpeg und .png.

USt‑Modus (Config)

Hier legst du fest, wie das Tool mit Umsatzsteuer (USt) rechnet:

  • Kleinunternehmerregelung (§19 UStG) oder
  • Regelbesteuerung.

Der Modus wird in der Config gesetzt (Standard: small_business).

[tax]
mode = "small_business"  # oder "standard"
  • small_business = Kleinunternehmerregelung (§19 UStG): keine Vorsteuer; Reverse‑Charge erzeugt USt‑Zahllast.
  • standard = Regelbesteuerung: Vorsteuer wird erfasst; Reverse‑Charge bucht USt und VorSt gleichzeitig.

Einnahmen klassifizieren

Für den UStVA-Report speichert euer an Einnahmen vat_rate und vat_code.

euer add income ... --vat-rate 19
euer add income ... --vat-rate 7
euer add income ... --vat-rate 0
euer add income ... --tax-free

--tax-free ist exklusiv zu --vat-rate und --vat. Im Modus standard setzt euer ohne Angabe automatisch 19 %. Der Betrag bleibt der tatsächliche Zahlfluss; vat_output wird aus dem Bruttobetrag herausgerechnet, sofern kein manueller Steuerbetrag per --vat gesetzt ist.

Steuermodus setzen, einsehen, aendern

  • Setzen (interaktiv): euer setup fragt nach small_business|standard.
  • Einsehen: euer config show zeigt den aktuellen Wert unter [tax].
  • Aendern: euer setup erneut ausfuehren und den Modus neu waehlen.
  • Manuell: ~/.config/euer/config.toml bearbeiten und mode anpassen.

Audit‑User

Der Audit‑User wird für Änderungen in der audit_log‑Tabelle gespeichert.

  • Setzen (interaktiv): euer setup fragt nach dem Namen.
  • Einsehen: euer config show zeigt den aktuellen Wert unter [user].
  • Manuell: ~/.config/euer/config.toml bearbeiten und name anpassen.
# aktuelle Konfiguration inkl. Steuermodus anzeigen
euer config show

# Steuermodus neu setzen (interaktiv)
euer setup

Reverse‑Charge (RC)

Verwende --rc eu oder --rc third-country für ausländische Anbieter ohne deutsche USt. Der RC-Typ ist Pflicht, damit spätere UStVA-Auswertungen EU-Leistungen und Drittland-Leistungen trennen können:

euer add expense --date 2026-01-04 --vendor "RENDER.COM" \
    --category "Laufende EDV-Kosten" --amount -22.71 --rc third-country

Hinweis: Bei small_business setzt RC automatisch vat_output, vat_input bleibt 0.0. Bestehende RC-Buchungen ohne EU-/Drittland-Typ können nachgepflegt werden:

euer update expense 42 --rc eu
euer update expense 42 --rc third-country

USt-Voranmeldung (vat-report)

vat-report ist ein separater, formularnaher Arbeitsbericht für die manuelle Übertragung in ELSTER. Er nutzt ausschließlich payment_date; Buchungen ohne Wertstellungsdatum werden nicht eingerechnet und erscheinen als Warnung.

euer vat-report --year 2026
euer vat-report --year 2026 --quarter 1
euer vat-report --year 2026 --month 3
euer vat-report --year 2026 --quarter 1 --format csv --output exports/
euer vat-report --year 2026 --month 3 --format xlsx --output exports/

Der Report enthält u.a. KZ 81/86/87/48 für Ausgangsumsätze, KZ 46/47 und 84/85 für Reverse Charge, KZ 66/67 für Vorsteuer sowie KZ 83 als Zahllast oder Erstattung. CSV erzeugt zusätzlich eine Diagnose-Datei mit ausgeschlossenen und gewarnten Buchungen; XLSX enthält ein zweites Sheet Diagnose.

Backfill / Reklassifikation für bestehende DB

Empfohlen ist zuerst der CLI-Abgleich:

euer reconcile private --year 2026 --dry-run
euer reconcile private --year 2026

Das Kommando reklassifiziert persistierte expenses.is_private_paid-Werte auf Basis der aktuellen Config ([accounts].private) und lässt manuelle Markierungen unverändert.

Alternativ: Einmaliger Backfill direkt in SQLite

Wenn du alte Ausgaben nachträglich als private Sacheinlagen markieren willst:

  1. Backup erstellen:
cp euer.db euer.backup.db
  1. Sicherstellen, dass neue Spalten existieren:
euer init
  1. Einmaliger Backfill (Beispiel-Regeln):
sqlite3 euer.db <<'SQL'
BEGIN;

-- Regel 1: private Konten
UPDATE expenses
SET is_private_paid = 1,
    private_classification = 'account_rule'
WHERE LOWER(COALESCE(account, '')) IN ('privat', 'private kreditkarte', 'barauslagen')
  AND is_private_paid = 0;

-- Regel 2: Nutzungseinlage-Kategorie
UPDATE expenses
SET is_private_paid = 1,
    private_classification = 'category_rule'
WHERE category_id IN (
  SELECT id FROM categories
  WHERE type = 'expense' AND name = 'Fahrtkosten (Nutzungseinlage)'
);

COMMIT;
SQL
  1. Ergebnis prüfen:
euer private-summary --year 2026
euer list private-deposits --year 2026

Hinweis: Direkte Privatentnahmen/Privateinlagen aus früheren Jahren können nicht zuverlässig aus expenses/income rekonstruiert werden und sollten bei Bedarf manuell über add private-deposit/add private-withdrawal nachgetragen werden.

Troubleshooting

  • Kategorie fehlt: euer list categories prüfen.
  • Duplikat erkannt: gleiche Transaktion wurde bereits importiert.
  • Beleg nicht gefunden: Pfade in config.toml prüfen und Ordnerstruktur beachten.

Hilfe

Für Details zu Parametern:

euer --help
euer add expense --help
euer receipt --help