CLI-Übersicht

vcdb ist der Hauptbefehl von vcdb-tool. Er erfordert einen Unterbefehl, um eine bestimmte Operation auf einer VCDB v5 Instanz auszuführen – wie beispielsweise das Importieren, Exportieren oder Löschen von Stadtmodelldaten. Darüber hinaus stellt der Befehl allgemeine Optionen bereit, die für alle Unterbefehle verwendet werden können.

Synopsis

vcdb [OPTIONS] COMMAND

Optionen

Option Beschreibung Standardwert

[@<filename>…​]

Eine oder mehrere Argumentdateien mit Optionen.

-h, --help

Hilfenachricht anzeigen und beenden.

-V, --version

Versionsinformationen ausgeben und beenden.

--config-file=<file>

Konfiguration aus dieser Datei laden.

-L, --log-level=<level>

Log-Level: fatal, error, warn, info, debug, trace.

info

--log-file=<file>

Log-Nachrichten in diese Datei schreiben.

--quiet

Deaktiviert Log-Nachrichten auf der Konsole.

--pid-file=<file>

Datei mit der Prozess-ID erstellen.

--plugins=<dir>

Plugins aus diesem Verzeichnis laden.

--use-plugin=<plugin[=true|false]>
[,<plugin[=true|false]>…​]

Plugins mit passendem vollqualifiziertem Klassennamen aktivieren oder deaktivieren.

true

Befehle

Befehl Beschreibung

help

Hilfe zum angegebenen Befehl anzeigen.

connect

Verbindung zur Datenbank testen.

info

Datenbankbericht anzeigen.

import

Daten in einem unterstützten Format importieren.

export

Daten in ein unterstütztes Format exportieren.

delete

Features aus der Datenbank löschen.

index

Index-Operationen durchführen.
Wenn Plugins für vcdb-tool registriert sind, können diese die Liste der Befehle erweitern, indem sie eigene Befehle zur CLI hinzufügen.

Verwendung

Version und VCDB-Unterstützung

Die Option --version gibt die Version von vcdb-tool sowie die unterstützten Versionen der VCDB aus. Ein + Zeichen neben einer VCDB-Version bedeutet, dass die Unterstützung ab dieser Version beginnt und alle nachfolgenden Patch-Updates umfasst. Eine beispielhafte Ausgabe ist nachfolgend dargestellt.

$ vcdb --version
vcdb-tool version 1.0.0
Supported VC Database versions: 5.0.0+
(C) 2022-2025 virtualcitysystems GmbH

Hilfe und CLI-Dokumentation

Um Hilfe zu einem bestimmten Befehl zu erhalten, wird die Option --help verwendet. Dadurch wird eine Hilfenachricht ausgegeben, die die Kurzbeschreibung des Befehls sowie die verfügbaren Optionen enthält. Falls der Befehl Unterbefehle hat, bezieht sich die --help Option auf den unmittelbar davorstehenden Befehl. Alternativ kann auch der Befehl help gefolgt vom gewünschten COMMAND verwendet werden, um dieselben Informationen zu erhalten. Das COMMAND kann dabei auch ein Unterbefehl sein.

  • Hilfe-Option

  • Hilfe-Befehl

vcdb --help
vcdb import --help
vcdb import citygml --help
# ...
vcdb help
vcdb help import
vcdb import help citygml
# ...

Logging

vcdb-tool protokolliert Ereignisse wie Aktivitäten, Warnungen und Fehler in der Konsole. Jeder Log-Eintrag enthält einen Zeitstempel, eine Schweregradstufe und eine Beschreibung. Die Log-Ausgabe wird über die Option --log-level gesteuert, die den minimalen Schweregrad der auszugebenden Ereignisse festlegt. Alle Nachrichten dieses Schweregrads oder höher werden angezeigt.

Die verfügbaren Log-Level, sortiert vom höchsten zum niedrigsten Schweregrad, sind:

  • fatal: Kritische Fehler, die zur sofortigen Beendigung führen

  • error: Nicht behebbare Fehler

  • warn: Warnungen zu möglichen Probleme

  • info: Allgemeine Informationen zur laufenden Operation (Standard)

  • debug: Detaillierte Debug-Informationen

  • trace: Detaillierteste Protokolle zur Fehlerbehebung

Alle Log-Nachrichten auf der Konsole werden an stderr ausgegeben, unabhängig vom gewählten Log-Level. Damit wird sichergestellt, dass strukturierte Ausgaben auf stdout (z.B. JSON-Ausgaben, die von Befehlen wie info oder connect erzeugt werden) nicht durch Log-Einträge beeinträchtigt werden. Diese Trennung ermöglicht beispielsweise, strukturierte Ausgaben an ein anderes Programm umzuleiten, während Log-Nachrichten weiterhin im Terminal ausgegeben werden.

Die Option --quiet deaktiviert die Konsolenausgabe von Log-Nachrichten. Mit dieser Option wird nur die strukturierte Ausgabe auf stdout angezeigt. Obwohl die Option aufgrund der Trennung von stdout und stderr nicht zwingend erforderlich ist, kann sie nützlich sein, wenn ausschließlich die strukturierten Ausgabe eines Befehls auf der Konsole ausgebenen werden soll.

Log-Nachrichten können auch in eine Logdatei geschrieben werden, die mit der Option --log-file angegeben wird. Die mit --log-level festgelegte Stufe gilt auch für die Logdatei.

Die Logdatei wird beim Programmstart geleert, falls sie bereits existiert.

Konfigurationsdateien

Optionen und Einstellungen für die Ausführung eines vcdb-tool-Befehls können auch aus einer Konfigurationsdatei im JSON-Format geladen werden, die mit der Option --config-file angegeben wird. Konfigurationsdateien überschreiben die Standardwerte von vcdb-tool und können auch flexibel zusammen mit Kommandozeilenoptionen verwendet werden. Allerdings ist zu beachten, dass Kommandozeilenoptionen stets Vorrang vor den Einstellungen aus Konfigurationsdateien haben. Jeder CLI-Befehl definiert seine eigene JSON-Struktur. Weitere Informationen finden Sie im Kapitel zur JSON-Konfiguration.

  • Linux

  • Windows CMD

./vcdb export citygml [...] \
    --config-file=/path/to/my-config.json
vcdb export citygml [...] ^
    --config-file=C:\path\to\my-config.json
Bei einigen Befehle können bestimmte Opionen nur über die JSON-Konfiguration eingestellt werden, aber nicht über die Kommandozeile.

Plugins

vcdb-tool bietet einen flexiblen Plugin-Mechanismus zur benutzerdefinierten Erweiterung der Funktionalität. Plugins können neue Befehle einführen oder bestehende erweitern. Sie werden typischerweise als ZIP-Paket bereitgestellt, das die Java Archive (JAR)-Datei des Plugins sie gegebenenfalls zusätzliche Ressourcen enthält.

Um ein Plugin zu installieren, entpacken Sie es (falls nötig) und kopieren die Dateien in den Unterordner plugins im Installationsverzeichnisses von vcdb-tool. Zur besseren Übersicht wird empfohlen, für jedes Plugin einen eigenen Unterordner anzulegen. vcdb-tool erkennt und lädt die Plugins automatisch aus diesem Verzeichnis und protokolliert erfolgreich geladene Plugins separat in der Konsole. Um ein Plugin zu deinstallieren, löschen Sie einfach dessen Ordner aus dem plugins Verzeichnis.

Die Option --plugins ermöglicht es, ein anderes Verzeichnis anzugeben, aus welchem die Plugins geladen werden sollen. Zum Aktivieren oder Deaktivieren von Plugins, verwenden Sie die Option --use-plugin, gefolgt vom vollqualifizierten Java-Klassennamen und dem Wert true (aktivieren) oder false (deaktivieren) (Standard: true). Deaktivierte Plugins werden nicht geladen. Mehrere Plugins können als kommaseparierte Liste angegeben werden, wie im folgenden Beispiel gezeigt.

  • Linux

  • Windows CMD

./vcdb export citygml [...] \
    --plugins=/path/to/my/plugins \
    --use-plugin=com.example.PluginA=true,com.example.PluginB=false
vcdb export citygml [...] ^
    --plugins=/path/to/my/plugins ^
    --use-plugin=com.example.PluginA=true,com.example.PluginB=false
Weitere Informationen zur Funktionalität eines Plugins, zu verfügbaren CLI-Befehlen, Optionen sowie zum vollqualifizierten Klassennamen für die Option --use-plugin finden Sie in der Plugin-Dokumentation. Der Klassenname wird außerdem beim Laden des Plugins durch vcdb-tool in der Konsole angezeigt.

Exit-Codes

vcdb-tool verwendet Exit-Codes, um den Erfolg oder das Fehlschlagen einer Operation anzuzeigen. Diese Codes helfen Benutzern und Skripten zu erkennen, ob die Ausführung erfolgreich war oder ob ein Fehler aufgetreten ist. Nachfolgend sind die von vcdb-tool verwendeten Exit-Codes aufgeführt:

  • 0: Die Operation wurde erfolgreich und ohne Fehler abgeschlossen

  • 1: Die Operation wurde aufgrund von Fehlern oder Problemen abgebrochen

  • 2: Ungültige Eingabe für eine Option oder einen Parameter

  • Größer als 2: Spezifische Fehler während der Ausführung eines Befehls

CLI-Tipps und Tricks

Angabe von Optionen

Optionen, die einen Wert erfordern, können entweder mit einem Gleichheitszeichen (=) oder einem Leerzeichen angegeben werden. Dies gilt sowohl für Kurz- als auch für Langformen von Optionen. Kurzoptionen, die keinen Wert benötigen, können hinter einem einzelnen Bindestrich - gruppiert werden, gefolgt von höchstens einer weiteren Kurzoption, die einen Wert erfordert.

Die folgenden generischen Beispiele sind alle gleichwertig, wobei -f die Kurzform für --file ist:

<command> -a -b -c --file=my-file.txt
<command> -ab -c --file my-file.txt
<command> -abc -f my-file.txt
<command> -abcf=my-file.txt

Mehrwertige Optionen wie --use-plugin können einen oder mehrere Werte annehmen. Wenn mehrere Werte übergeben werden sollen, können sie entweder als kommaseparierte Liste oder durch mehrfache Angabe der Option notiert werden.

Die folgenden Beispiele sind alle gültig:

vcdb --use-plugin=com.example.PluginA,com.example.PluginB=false
vcdb --use-plugin=com.example.PluginA --use-plugin=com.example.PluginB=false

Doppelstrich-Trennzeichen

vcdb-tool unterstützt das Trennzeichen --, um Optionen von positionsabhängigen Argumenten zu trennen. Alle Argumente nach -- werden als Positionsargumente behandelt, auch wenn sie einem Optionsnamen entsprechen.

Als Beispiel dient der folgendende Befehl import citygml zum Importieren der CityGML-Datei my-city.gml:

vcdb import citygml [...] --db-password my-city.gml

Die Option --db-password von vcdb-tool erwartet entweder ein Passwort als Wert oder fordert den Benutzer zur Eingabe des Passworts auf, wenn kein Wert angegeben wird. In obigen Beispiel wollte der Benutzer zur Passworteingabe aufgefordert werden. Stattdessen wird jedoch my-city.gml als Passwort interpretiert und nicht als Eingabedatei. Um dies zu verhindern, muss im Beispiel das ---Trennzeichen verwendet werden:

vcdb import citygml [...] --db-password -- my-city.gml

Abkürzungen für Optionen und Befehle

Zur Vereinfachung der CLI-Nutzung bietet vcdb-tool Kurzformen für einige Optionen (z.B. -h für --help). Darüber hinaus können auch alle Langoptionen ohne spezielle Kurzform durch die Anfangsbuchstaben des ersten Bestandteils und optional weiterer Bestandteile des Optionsnamens abgekürzt werden. "Bestandteile" werden entweder durch Bindestriche - oder durch Groß-/Kleinschreibung voneinander getrennt. Beispielsweise bestehen sowohl --camelCase als auch --kebab-case aus zwei Bestandteilen.

Die folgenden Abkürzungen sind gültig für die Option --super-long-option, die aus drei Bestandteilen besteht:

--sup, --sLO, --s-l-o, --s-lon, --s-opt, --sLon, --sOpt, --soLoOp (...)

Die gleiche Abkürzungssyntax kann auch für Befehle verwendet werden. Abkürzungen für Optionen und Befehle müssen jedoch eindeutig sein. Zum Beispiel könnte der Befehl import city sowohl als import citygml als auch import cityjson interpretiert werden, was zu einem Konflikt führt. In solchen Fällen bricht vcdb-tool den Vorgang ab und zeigt eine Fehlermeldung an, um Mehrdeutigkeiten zu vermeiden.

Argumentdateien

Wenn eine Befehlszeile viele Optionen oder lange Argumente enthält, können Systembeschränkungen hinsichtlich der maximalen Befehlslänge problematisch werden. Argumentdateien (sogenannte @-Dateien) helfen, diese Einschränkung zu umgehen, indem die Argumente in einer separaten Datei gespeichert werden. Eine oder mehrere Argumentdateien können in einer Befehlszeile verwendet werden, indem ihre Dateinamen in der Befehlszeile mit @ vorangestellt werden. Der Inhalt jeder @-Datei wird automatisch in die Argumentliste eingefügt.

Argumente in einer @-Datei können durch Leerzeichen oder Zeilenumbrüche getrennt sein. Argumente, die Leerzeichen enthalten, müssen in doppelte (") oder einfache (') Anführungszeichen eingeschlossen werden. Innerhalb von Anführungszeichen werden Anführungszeichen mit einem Backslash (\) maskiert, und Backslashes selbst werden durch Verdopplung (\\) maskiert. Zeilen, die mit einem # beginnen, sind Kommentare und werden ignoriert. Die Argumentdatei kann auch Verweise auf weitere @-Dateien enthalten, die rekursiv verarbeitet werden.

Angenommen, eine existiert eine @-Datei unter /home/foo/args, die die folgenden Logging-Einstellungen und Datenbankverbindungsparameter enthält:

# Diese Zeile ist ein Kommentar und wird ignoriert
--log-level=debug
--log-file=/path/to/my/logfile.log
--db-host=localhost
--db-name=citydb
--db-user=citydb_user
--db-password=changeMe

Diese @-Datei kann mit einem vcdb-tool Befehl wie folgt verwendet werden. Der angegebene Pfad kann entweder absolut oder relativ zum aktuellen Verzeichnis sein.

vcdb index status @/home/foo/args

Es können auch mehrere @-Dateien in der Befehlszeile kombiniert werden, um ihre Inhalt logisch zu trennen.

vcdb index status @/home/foo/db-args @/home/foo/logging-args
Obwohl @-Dateien eigentlich für einen anderen Zweck gedacht sind, können sie ähnlich wie Konfigurationsdateien verwendet werden, um Befehle mit unterschiedlichen Optionen je nach Szenario oder Anwendungsfall auszuführen. Es wird jedoch empfohlen, bevorzugt Konfigurationsdateien zu verwenden.
Argumentdateien haben eine Einschränkung: Parameter- oder Optionswerte, die in Anführungszeichen eingeschlossen sind, dürfen nicht direkt nach einem Gleichheitszeichen stehen. Zum Beispiel funktioniert --my-option="foo bar" nicht innerhalb einer Argumentdatei. Um dieses Problem zu umgehen, kann das Gleichheitszeichen entweder weggelassen (--my-option "foo bar") oder der gesamte Ausdruck in Anführungszeichen eingeschlossen ("--my-option=\"foo bar\"") werden.