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#

Laden Sie sich die aktuelle Version des Kommandozeilen-Clients herunter.
Diese finden Sie auf der Download-Seite oder direkt im git.

Wenn Sie Windows verwenden, nehmen Sie diesen Download.
Windows-Anwender? Öffnen Sie ein Kommando-Fenster

Unter Windows öffnen Sie ein Kommandozeilen-Fenster (cmd, PowerShell oder bash, falls vorhanden) in dem Verzeichnis, in das Sie den Client geladen haben. Am besten legen Sie den Client in ein Verzeichnis im Suchpfad, dann können Sie ihn jederzeit und von überall aus starten (z. B. aus dem Verzeichnis, in dem Ihre CSV-Dateien liegen).

Wir empfehlen außerdem, das geladene Programm der Einfachheit halber in livectl.exe umzubenennen. Die weiteren Beispiele sind betriebssystemunabhängig und funktionieren unter Windows, Mac und Linux gleichermaßen.
Prüfen Sie die Version
```
$ livectl version
Client: Version 1.5.1001 (1001) [BuildVersion: 1760711093670 from 2025-10-17T14:24:53Z]
```
Eine erste Meldung, dass der Server nicht erreichbar ist, ist hier normal — der Server wurde noch nicht konfiguriert. Das holen wir im nächsten Schritt nach.
Verbinden Sie den Client mit dem Server
```
livectl server https://app.inkasso.live
```
Falls Sie den Server häufiger wechseln (etwa zwischen einem Testsystem und localhost), gibt es passende Kurzbefehle, die die Server-URL direkt setzen: livectl app (https://app.inkasso.live), livectl demo (https://demo.inkasso.live), livectl lab (https://lab.inkasso.live), livectl prod (https://portal.field-service.team) und livectl local (http://localhost:8080).
Stellen Sie die Sprache ein (optional)
```
livectl language de
```
Damit erscheinen die Hilfe-Texte auf Deutsch. Die Kommandos selbst bleiben unverändert.
Verschaffen Sie sich einen Überblick über die Kommandos
```
livectl help
```
Oder die Hilfe zu einem einzelnen Kommando:
```
livectl assignments --help
```
Registrieren Sie sich am Server

Die Registrierung funktioniert mit dem CLI identisch zur App — nur dass hier statt eines Fingerabdrucks das sichere Systemlogin verwendet wird. Den <token> erhalten Sie von Ihrem Administrator (siehe Onboarding).
```
livectl register <token>
```
Melden Sie sich am Server an

Die Authentifizierung baut während des Login-Prozesses eine gesicherte Verbindung zum Server auf:
```
livectl login
```

Sie können nun alle Kommandos verwenden, für die Sie berechtigt sind. 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

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#

Der Client prüft die Daten, bevor sie zum Server geschickt werden. 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
*** 63/353 ***
Schuldner Anrede: Pflichtfeld
Schuldner Vorname: Pflichtfeld
*** 151/353 ***
Hauptforderung, Kosten und Gesamtforderung müssen gesetzt sein.

Man sieht hier, in welchen Zeilen und in welchen Feldern Fehler gefunden wurden — die übrigen, gültigen Zeilen wurden importiert.

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
*** 9/11 ***
Gesamtforderung: Die Gesamtforderung (262,06 != Summe 144,30) muss der Hauptforderung (55,34) zzgl. Kosten (48,20) und optional Zinsen (40,76) entsprechen
BezeichnungRatenzahlungsvereinbarung: Pflichtfeld
GebuehrRatenzahlungsvereinbarung: Pflichtfeld

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

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:

Filter-Feld (Alias)	Bedeutung
`processedDate` (`Abschlussdatum`)	Abschluss durch den Ausführenden
`dueDate` (`Bearbeitungsende`)	Soll-Frist
`deliveryDate` (`Einstelldatum`)	Anlage / Übernahme
`returnDate` (`Rückgabedatum`)	Rückgabe
`modified` (`since`, `lupdate`)	letzte Änderung

# 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 gibt es die Kurzform --since (entspricht modified>=…). Sie akzeptiert ein Datum, einen Zeitstempel oder eine relative Spanne wie 7d (letzte 7 Tage):

# nur die Anzahl der in den letzten 7 Tagen geänderten Aufträge
livectl assignments count --since 7d

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).