Bedienung des CLI (Kommandozeilenclient)#

Hier die ersten Schritte mit dem CLI. In der Darstellung sehen wir Terminal-Ausgaben aus einer bash. Grundsätzlich funktioniert das natürlich mit allen Shells.

Bei Beispielen, in denen Ausgaben zu sehen sind, haben wir den Befehlen Prompts vorangestellt ($), um die Befehle zu kennzeichnen und von den Ausgaben zu trennen. In Beispielen ohne Ausgabe bzw. in Beispielen, bei denen die Ausgabe irrelevant ist, haben wir die Prompts bewusst weggelassen, damit Sie diese leichter per Copy & Paste verwenden können. Zum Kopieren klicken Sie in das Feld, bis Sie einen blauen Rahmen sehen. Das markiert den kompletten Text.

Einmalige Vorbereitung#

Sie können nun alle Kommandos verwenden, für die Sie berechtigt sind.

Admin-Modus (ab Version 1.6): Sind Sie Administrator Ihres Mandanten, wirken diese Rechte nur, wenn Sie sie für den Aufruf anfordern – mit dem Schalter --admin direkt hinter livectl:

livectl --admin assignments import auftraege.csv --tenant-id <mandant> --dto fsg1

Nötig ist das für alles, was über Ihre eigene Organisation hinausgeht: Aufträge für einen anderen Auftraggeber einspielen, die Gesamtsicht auf den Mandanten, Konten, Rollen, Tokens und Organisationen verwalten sowie der Import mit Originalfeldern. Ohne --admin arbeiten Sie mit Ihren normalen Rechten. Details: Admin-Modus.

Ein Server ab Version 1.6 nimmt das livectl der Version 1.5 nicht mehr an – bitte das passende livectl von der Download-Seite verwenden, auch für automatisierte Importe. Die aufgelöste Konfiguration (Server, Sprache usw.) zeigt Ihnen livectl config.

Beispiel: Import#

Hier ein Beispiel für einen Import mit livectl.

Neuaufträge (FSG1) spielen Sie mit assignments import ein:

livectl assignments import auftraege.csv --tenant-id <mandant> --dto fsg1

Spielen Sie Aufträge für einen anderen Auftraggeber ein – etwa als Verwaltung des Mandanten –, gehört --admin dazu: livectl --admin assignments import auftraege.csv --tenant-id <mandant> --dto fsg1.

import ist der empfohlene Regelweg: Er ist idempotent und wiederholbar — neue Aufträge werden angelegt, bereits vorhandene aktualisiert (Upsert), und bereits eingetragene Ergebnisse bleiben erhalten. Korrekturen spielen Sie einfach als erneuten Import derselben Datei ein; der Auftrag wird dabei über das Aktenzeichen (AktenzeichenEinspeisender) wiedergefunden, das deshalb stabil bleiben muss.

Daneben gibt es assignments create für den Sonderfall einer garantiert leeren Erstbefüllung: create legt ausschließlich neue Aufträge an und bricht ab, sobald ein Auftrag schon existiert.

Postleitzahlen / Servicegebiete importieren Sie über das Aggregat postal-areas:

livectl postal-areas import plz.csv --dto fsg.postal-area

livectl erkennt das Format anhand der Dateiendung automatisch. Falls das einmal nicht klappt, erzwingen Sie es mit -f <format> (z. B. -f csv).

Beispiel: Import mit fehlerhaften Daten#

Jede Zeile wird beim Import geprüft. Standardmäßig arbeitet der Import tolerant: Gültige Zeilen werden importiert, fehlerhafte Zeilen werden einzeln mit Zeilennummer und Grund gemeldet und sind anschließend in der PWA als „Ungültig" sichtbar und korrigierbar.

$ livectl assignments import test1.csv --tenant-id <mandant> --dto fsg1
Loaded 3 rows from test1.csv
Uploading 3 rows
running [1/3] Accepted 1 of 3 assignment rows
running [0/2] Writing 2 rejected assignment rows
Imported 3/3 rows, rejected 2
Done: patch 3/3 rows, rejected 2
Rejected row 3 (Auftraggeber=AG-4201, AktenzeichenEinspeisender=79100002): subjectBirthDate: Max age is 120.
Rejected row 4 (Auftraggeber=AG-9999, AktenzeichenEinspeisender=79100003): FSG assignment import names a client (Auftraggeber) that does not resolve to a known client.
completed [3/3] Completed

Man sieht hier, in welchen Zeilen (gezählt als Zeile der Datei, die Kopfzeile ist Zeile 1) und aus welchem Grund Fehler gefunden wurden — die übrigen, gültigen Zeilen wurden importiert. Die Fortschritts- und Zusammenfassungszeilen gibt livectl auf Englisch aus, die fachlichen Prüfmeldungen stammen vom Server.

Der Client bereinigt CSV-Daten, bevor sie verwendet werden. Oft sind es fehlende Anführungszeichen, unerlaubte Zeilenumbrüche in Spalten oder abweichende Datums- oder Währungsformate. Der Client versucht, diese Dinge so gut wie möglich zu korrigieren. Gelingt das nicht, gibt es passende Fehlermeldungen:

$ livectl assignments import test2.csv --tenant-id <mandant> --dto fsg1
Loaded 5 rows from test2.csv
Uploading 5 rows
running [4/5] Accepted 4 of 5 assignment rows
running [0/4] Writing 4 accepted assignment rows
running [0/1] Writing 1 rejected assignment rows
completed [5/5] Completed
Imported 5/5 rows, rejected 1
Done: patch 5/5 rows, rejected 1
Rejected row 6 (Auftraggeber=AG-4201, AktenzeichenEinspeisender=79200005): totalClaim: Gesamtforderung muss 2909.22 oder nach Zahlungen 2909.22 sein.

Wird dieselbe Datei noch einmal eingespielt, meldet livectl die unveränderten Zeilen als noop (z. B. Imported 0/5 rows, noop 4, rejected 1) — ein wiederholter Import ändert nichts.

Wenn Sie möchten, dass der Import bei der ersten fehlerhaften Zeile komplett abbricht (statt tolerant nur die gültigen Zeilen zu übernehmen), verwenden Sie --strict:

livectl assignments import test3.csv --tenant-id <mandant> --dto fsg1 --strict

Dann bricht der Import mit der ersten ungültigen Zeile ab, und es wird nichts übernommen:

$ livectl assignments import test2.csv --tenant-id <mandant> --dto fsg1 --strict
Loaded 5 rows from test2.csv
Uploading 5 rows
failed Invalid fsg.assignment-order row 5: totalClaim: Gesamtforderung muss 2909.22 oder nach Zahlungen 2909.22 sein.
Invalid fsg.assignment-order row 5: totalClaim: Gesamtforderung muss 2909.22 oder nach Zahlungen 2909.22 sein.

Hier zählt row die Datenzeilen ohne Kopfzeile.

Export#

Aufträge exportieren Sie über den Lese-Befehl. Einen eigenen export-Unterbefehl gibt es für Aufträge bewusst nicht — der Export ist der Lese-Befehl mit dem Export-Format FSG3:

livectl assignments --dto fsg3 -f csv > auftraege.csv

Alternativ mit Zieldatei:

livectl assignments list auftraege.csv --dto fsg3 -f csv

Stammdaten-Aggregate (Konten, Auftraggeber, Partner …) besitzen dagegen einen eigenen export-Unterbefehl:

livectl clients export clients.csv -f csv

Wenn Sie kein Format angeben, leitet livectl das gewünschte Dateiformat aus dem Dateinamen ab.

Filtern#

assignments list, assignments count und der FSG3-Export teilen denselben serverseitigen Filter — count liefert damit exakt die Zeilenzahl des gleich gefilterten Exports. Filter geben Sie über --filter '<Ausdruck>' an (mehrfach erlaubt).

Den Status filtern Sie mit = bzw. !=:

livectl assignments list --filter 'status=processed'

Datumsfelder vergleichen Sie mit =, !=, >, >=, <, <=; als Wert ein ISO-Datum (z. B. 2026-06-20) oder einen Zeitstempel in Millisekunden. Die deutschen Exportspalten dürfen Sie als Alias verwenden:

# Alle seit dem 20.06.2026 vom Ausführenden abgeschlossenen Aufträge als FSG3-CSV
livectl assignments list --dto fsg3 -f csv --filter 'processedDate>=2026-06-20' export.csv

Für das Änderungsfenster filtern Sie auf modified (letzte Änderung). Auch hier ist der Wert ein ISO-Datum oder ein Zeitstempel in Millisekunden; relative Angaben wie 7d nimmt der Filter nicht an:

# nur die Anzahl der seit dem 01.10.2026 geänderten Aufträge
$ livectl assignments count --filter 'modified>=2026-10-01'
44

Die Kurzform --since gibt es für Aufträge nicht. livectl weist sie mit einem Hinweis ab, statt sie stillschweigend zu übergehen.

Ein Auftrag ohne das jeweilige Datum erfüllt keinen >=-Filter — noch nicht abgeschlossene Aufträge fallen also aus processedDate>=… heraus. Die Felder Rechnungsdatum und der Endzustand-Zeitpunkt sind noch nicht filterbar (Abrechnungs-/Abschluss-Flow folgt in einer späteren Version).