Verbinde deinen Assistenten mit CashCtrl.

Was das bringt

«Wie sehen die letzten Buchungen aus?»

Voraussetzungen

• Ein Assistent, der auf deine Dateien zugreifen und Programme ausführen darf. Welche App du dafür nutzt, spielt keine Rolle. Ein Chat ohne Zugriff auf deine Dateien reicht nicht.
• Ein CashCtrl-Konto mit PRO-Plan. Nur der PRO-Plan hat Zugriff auf die API, ohne ihn funktioniert diese Anbindung nicht. Der API-User wird unter Einstellungen > Benutzer & Rollen angelegt.

Was du danach kannst

Grenzen, ehrlich

• Die API gibt es nur im PRO-Plan. Ohne PRO-Plan funktioniert diese Anbindung nicht.
• Der API-Key kann alles ausführen, was die Rolle des API-Users erlaubt. Wähle deshalb eine eingeschränkte Rolle. Wird der Key widerrufen oder ersetzt, führst du "<cashctrl>" init erneut aus.
• Versand- und Lösch-Operationen verweigert das Programm ohne --force. Das ist Absicht: verschicken und löschen bleiben bewusste Entscheide.
• Dein Assistent macht Fehler wie ein neuer Mitarbeiter. Darum gilt: anlegen ja, aber du gibst frei.

Anleitung für deinen Assistenten

1. 1

   Im Assistenten einrichten

   Dieser Workflow gehört zum Thema Finanzen. Er liegt danach in 01_finanzen/workflows/cashctrl/, bei jeder Person am selben Ort.

   1. Prüfe, ob du in einem Assistenten arbeitest. Im geöffneten Ordner liegen AGENTS.md und CONTEXT.md, und in CONTEXT.md steht eine Tabelle mit der Kopfzeile | Aufgabe | Ordner | Status |. Fehlt das, sag der Person, dass der Gratis-Starter von wirdrei.digital diesen Rahmen einrichtet: https://wirdrei.digital/assistent. Frag sie, ob sie zuerst den Starter einrichten oder ohne ihn weitermachen will. Ohne Starter legst du einen neuen, leeren Unterordner an, dessen Namen die Person bestätigt, und arbeitest nur darin: Alle Pfade dieser Anleitung liegen dann in diesem Unterordner, nichts ausserhalb wird angefasst. Weg fallen dabei die Router-Zeilen und der Eintrag in CHANGELOG.md (Punkte 2 und 3), die Vorlagen aus dem Skill workflow-builder, _setup/werkzeuge.md, support.md und die Pflege. Die CONTEXT.md aus Schritt 2 schreibst du selbst, und was sonst in _setup/werkzeuge.md stünde (installierte Pakete und Skripte, Ort von Python), hältst du dort unter «Quellen» fest. Wo diese Anleitung auf support.md verweist, nennst du https://wirdrei.digital/kontakt.

   2. Bereich anlegen, falls er fehlt. Kopiere assets/bereich-CONTEXT.md aus dem Skill workflow-builder deines Assistenten nach 01_finanzen/CONTEXT.md und fülle {{BEREICH}} mit 01_finanzen und {{THEMA}} mit Finanzen. Wo der Skill liegt, steht im Haupt-Router CONTEXT.md in der Zeile «Eigenen Workflow bauen». Trag den Bereich direkt unter der letzten Zeile der Tabelle im Haupt-Router ein:

      | Finanzen | `01_finanzen/` | eingerichtet |
      

   3. Workflow anlegen. Gibt es 01_finanzen/workflows/cashctrl/ schon, frag, ob du ihn ergänzen sollst, und überschreib nichts. Sonst kopierst du assets/workflow-CONTEXT.md aus demselben Skill nach 01_finanzen/workflows/cashctrl/CONTEXT.md. Den Inhalt liefert Schritt 2. Trag den Workflow direkt unter der letzten Zeile der Tabelle von 01_finanzen/CONTEXT.md ein, mit der Aufgabe in den Worten der Person:

      | <Aufgabe> | `workflows/cashctrl/` | eingerichtet |
      

      Halte die Einrichtung zuoberst in CHANGELOG.md fest: Datum, was, warum und der Rückweg (den Ordner 01_finanzen/workflows/cashctrl/ und seine Router-Zeilen löschen).

   4. Gemeinsames liegt an einem Ort. Schreibstil steht nur in _marke/voice.md, Firmendaten nur in _marke/firmendaten.md. Braucht dieser Workflow eine davon und sie fehlt, kopierst du assets/marke-voice.md oder assets/marke-firmendaten.md aus dem Skill workflow-builder dorthin. Sie bleiben ENTWURF, bis die Person zustimmt. Python-Pakete installierst du nur, wenn dieser Workflow sie nennt, prüfst vorher in _setup/werkzeuge.md, ob sie schon da sind, und trägst sie dort ein. Dort stehen auch die Pfade von uv, Python und dem Laufzeitordner: Wo diese Anleitung "<uv>", "<python>" oder "<laufzeitordner>" schreibt, setzt du den Pfad von dort ein, immer in Anführungszeichen, denn er enthält oft Leerzeichen. In PowerShell steht & vor dem ersten Pfad eines Befehls. Schlüssel und Passwörter gehören nie in den Assistenten-Ordner und nie in den Chat. Braucht dieser Workflow einen, legst du die Datei "<laufzeitordner>/secrets/<dienst>.env" mit leeren Werten an und öffnest sie für die Person, ohne auf das Schliessen des Editors zu warten: auf dem Mac mit open -e "<datei>", auf Windows in Git Bash mit start "" notepad "<datei>" und in PowerShell mit Start-Process notepad "<datei>". Sie trägt die Werte ein und speichert, du liest sie nie in den Chat. Programme mit eigener Anmeldung behalten den Zugang in ihrem eigenen Speicher, wenn dieser Workflow das so vorsieht.

   5. Zum Schluss kommt der Test mit echten Daten, danach bietest du den Skill pflege an (letzter Schritt).

2. 2

   Vertrag ausfüllen

   Füll die CONTEXT.md so aus. Was in eckigen Klammern steht, klärst du mit der Person:

   # CashCtrl-Anbindung
   
   **Status: eingerichtet** (aktiv erst nach einem sauberen echten Durchlauf)
   **Auslöser:** Die Person fragt nach Buchungen, Kontakten, Rechnungen oder Offerten in CashCtrl.
   Pfade in diesem Vertrag liegen in `01_finanzen/workflows/cashctrl/`, ausser sie beginnen mit `_marke/`, `_setup/` oder einer Bereichsnummer.
   
   ## Zweck
   
   [Wofür vor allem: Buchungen, Kontakte, Rechnungen?] Gelesen und vorbereitet wird über das
   Programm `cashctrl` (cash-ctrl-cli von wirdrei.digital).
   
   ## So arbeitest du
   
   1. Lesen geht ohne Rückfrage: `"<cashctrl>" commands --json` zeigt alle Befehle.
   2. Anlegen und Ändern: erst den Entwurf im Chat zeigen, dann auf ein ausdrückliches Ja
      warten, dann ausführen.
   3. Versand- und Lösch-Operationen (zum Beispiel eine Rechnung per Mail verschicken,
      den Papierkorb leeren) verweigert das Programm ohne `--force`. `--force` setzt du nur
      nach einem eigenen Ja für genau diesen Vorgang.
   4. Meldet das Programm einen ungültigen Zugang, sag es der Person und lass sie
      `"<cashctrl>" init` im Terminal neu ausführen.
   
   ## Quellen
   
   | Was                                       | Wo                       | Zugriff                      |
   | ----------------------------------------- | ------------------------ | ---------------------------- |
   | Buchungen, Kontakte, Rechnungen, Offerten | CashCtrl über `cashctrl` | lesen, anlegen nach Freigabe |
   
   Der API-Key liegt im eigenen Speicher des Programms (`"<cashctrl>" init`, Dateirechte 0600),
   nie hier und nie im Chat.
   
   ## Ausgabe
   
   Antworten im Chat, Entwürfe im Chat und nach Freigabe die Einträge in CashCtrl.
   
   ## Grenzen
   
   - Schreibt nicht in den Assistenten-Ordner, ausser in diese `CONTEXT.md`.
   - Beträge und Kontaktdaten stammen aus CashCtrl oder von der Person, nie geschätzt.
   - Senden, Löschen und Bezahlen braucht jedes Mal ein eigenes Ja.
   - Rolle des API-Users: [Name der eingeschränkten Rolle]
   
   ## Test
   
   [Datum des ersten sauberen Lese-Aufrufs]
   

   Frag die Person nach dem Zweck und lass sie die Regeln bestätigen, bevor du den Zugang einrichtest.

3. 3

   Programm installieren

   Lade von https://github.com/wir-drei-digital/cash-ctrl-cli/releases/latest das Archiv für das System dieses Computers (macOS und Linux als .tar.gz für amd64 und arm64, Windows als .zip). Prüfe den Download gegen checksums.txt und entpacke das Archiv in einen leeren Ordner "<laufzeitordner>/downloads/cashctrl/". Kopiere daraus nur das Programm cashctrl (auf Windows cashctrl.exe) nach "<laufzeitordner>/bin/", wo auch uv liegt. Trag den vollen Pfad in _setup/werkzeuge.md ein, etwa "<laufzeitordner>/bin/cashctrl". Das ist ab jetzt "<cashctrl>": Du rufst das Programm immer mit diesem Pfad in Anführungszeichen auf und änderst keine Systemeinstellungen.

   Alternative, falls eine Go-Toolchain da ist: GOBIN="<laufzeitordner>/bin" go install github.com/wir-drei-digital/cash-ctrl-cli/cmd/cashctrl@latest (in PowerShell setzt du vorher $env:GOBIN="<laufzeitordner>\bin").

   Prüfe die Installation mit "<cashctrl>" commands --json. Kommt eine Liste von Befehlen zurück, ist sie da. Trag Programm und Version in _setup/werkzeuge.md ein.

4. 4

   API-User anlegen

   CashCtrl braucht dafür einen eigenen API-User. Leg ihn unter Einstellungen > Benutzer & Rollen > Hinzufügen > API-User an. Seine Rolle entscheidet, was der Key später darf: Gib ihm bewusst eine eingeschränkte Rolle, nicht die volle Administratorrolle, und trag sie unter «Grenzen» ein.

   Notiere dabei zwei Werte: die Organisations-Subdomain (das myorg in https://myorg.cashctrl.com) und den API-Key, den CashCtrl beim Anlegen anzeigt.

   Zum gefahrlosen Ausprobieren kopierst du die Organisation zuerst in eine Test-Organisation (Einstellungen > Organisationen > Kopieren) und legst den API-User dort an.

   Wichtig: Die Person tippt den API-Key nie in den Chat. "<cashctrl>" init fragt ihn direkt im Terminal ab und speichert ihn lokal mit Dateirechten 0600.

5. 5

   Zugang speichern

   Lass die Person "<cashctrl>" init im Terminal ausführen. Gib ihr dafür den Befehl mit dem vollen Pfad aus _setup/werkzeuge.md, in PowerShell mit & davor. Der Einrichtungsdialog fragt nach Organisations-Subdomain und API-Key, speichert beides und prüft es gleich mit einem einzigen Lese-Aufruf.

6. 6

   Mit einem Lese-Aufruf testen

   Mach einen Lese-Aufruf und zeig der Person das Ergebnis:

   "<cashctrl>" auth verify
   

   Der Befehl prüft die Zugangsdaten mit einem echten, unschädlichen Lese-Aufruf. Kommt eine Antwort ohne Fehler zurück, steht die Anbindung.

7. 7

   Abschliessen

   Lief der Test sauber, setzt du den Status auf aktiv: in 01_finanzen/workflows/cashctrl/CONTEXT.md, in der Zeile von 01_finanzen/CONTEXT.md und beim Bereich im Haupt-Router, falls dort noch eingerichtet steht. Halte das Datum des Durchlaufs im Abschnitt «Test» fest. Lief er nicht sauber, bleibt der Status eingerichtet, und du korrigierst die Regel in der CONTEXT.md, nicht nur das einzelne Ergebnis.

   Frag danach: «Soll ich kurz prüfen, ob alles sauber eingehängt ist?» Sagt die Person ja, startest du den Skill pflege. Ohne Assistenten-Rahmen (siehe Schritt 1) entfallen Router und Pflege.