CLI-Referenz

Edge Connector Reference

Die Edge Connector CLI (edge-connector) bietet Befehle zum Authentifizieren, Generieren von Tool-Implementierungen, Verwalten von Bundles, lokalem Testen, Paketieren, Hochladen und Verwalten von Cloud Connectors.

edge-connector [command] [options]

Globale Optionen:

Option	Beschreibung
--version	CLI-Version ausgeben
--auto-resume	Automatisch vom vorherigen Laufzustand fortfahren. Wird vom Autostart genutzt, um den Connector nach einem Systemneustart in seinen letzten bekannten Zustand zurückzuversetzen.
--help	Hilfe für einen beliebigen Befehl anzeigen

Interaktives Menü

Wenn du edge-connector ohne Argumente ausführst, startet ein geführtes interaktives Menü. Das Menü führt dich der Reihe nach durch die gängigsten Workflows:

1. Authentifizieren — Anmelden via Browser oder Token
2. Generieren — Tool-Implementierungen aus der Registry erstellen
3. Hochladen — Deine Tools als Bundle paketieren und hochladen
4. Bundle-Verwaltung — Bundles auflisten, auschecken, zuweisen und umbenennen
5. Cloud-Operationen — Cloud Connectors provisionieren, starten, stoppen und verwalten

Jeder Top-Level-Befehl unterstützt auch ein --interactive-Flag (oder -i, wo es nicht mit anderen Kurzflags kollidiert), um statt aller Optionen auf der Kommandozeile geführte Eingabeaufforderungen zu starten.

# Vollständiges interaktives Menü starten
edge-connector

# Interaktiven Modus für einen bestimmten Befehl starten
edge-connector auth --interactive
edge-connector generate --interactive
edge-connector run --interactive

---

auth

Den Edge Connector bei der nara-Plattform authentifizieren. Nach erfolgreicher Authentifizierung synchronisiert die CLI das Standard-Bundle deiner Organisation.

edge-connector auth [options]

Optionen:

Option	Beschreibung
-t, --token <token>	Authentifizierungs-Token — akzeptiert einen JWT-String oder einen Pfad zu einer JSON-Datei mit einem token-Feld
-b, --browser	Über Browser-OAuth-Flow authentifizieren (öffnet deinen Standardbrowser)
-i, --interactive	Interaktive Authentifizierungseingaben starten

Verhalten:

• Wenn --token angegeben wird, validiert die CLI den JWT (prüft Ablauf und Organisationszugehörigkeit), speichert ihn im konfigurierten Token-Pfad und synchronisiert das Standard-Bundle.
• Wenn --browser angegeben wird, startet die CLI den Desktop-OAuth-Flow: Sie öffnet ein Browserfenster, wartet auf die Autorisierung und speichert den zurückgegebenen Token.
• Wenn keine Optionen angegeben werden (oder --interactive verwendet wird), startet die CLI eine interaktive Eingabeaufforderung, die dich durch die Authentifizierung führt.
• --token und --browser können nicht gleichzeitig verwendet werden.

Beispiele:

# Über Browser authentifizieren
edge-connector auth --browser

# Mit einem JWT-String authentifizieren
edge-connector auth --token "eyJhbGciOiJSUzI1NiIs..."

# Mit einer Token-Datei authentifizieren
edge-connector auth --token ./my-token.json

# Interaktiver Modus
edge-connector auth --interactive

---

run

Den Edge Connector lokal starten, um eigene Tool-Implementierungen zu testen. Dieser Befehl startet die Runtime im Testmodus, bei dem State-Persistenz und Autostart deaktiviert sind.

edge-connector run [options]

Optionen:

Option	Standard	Beschreibung
-i, --implementations <path>	./custom-implementations	Pfad zu deinem Implementierungsverzeichnis
-T, --type <type>	EDGE	Connector-Typ
-u, --url <url>	ws://localhost:3001	WebSocket-URL des Platform Servers
--interactive		Im interaktiven Modus mit geführten Eingaben starten

Verhalten:

• Setzt folgende Umgebungsvariablen für den gestarteten Prozess:
  • EC_TEST_RUN=1 — aktiviert den Testmodus
  • EC_DISABLE_STATE=1 — deaktiviert State-Persistenz
  • EC_DISABLE_AUTOSTART=1 — verhindert Autostart-Registrierung
• Startet die Edge Connector Runtime als Kindprozess mit der angegebenen Konfiguration. Stdout und stderr der Runtime werden in dein Terminal geleitet.
• Die Runtime verbindet sich mit dem nara Platform Server, lädt deine eigenen Implementierungen und beginnt, Tool-Ausführungsanfragen anzunehmen.
• Drücke Ctrl+C, um den Testlauf zu beenden.

Achtung

Der run-Befehl ist nur für lokale Entwicklung und Tests gedacht. Für Produktions-Deployments lade dein Bundle auf die Plattform hoch und lade den vorkonfigurierten Connector aus der Webapp herunter.

Beispiele:

# Mit Standardeinstellungen starten (lokale Entwicklung)
edge-connector run

# Mit benutzerdefiniertem Implementierungspfad und Produktionsserver starten
edge-connector run -i ./my-tools -u wss://tool-rpc.nara.de

# Interaktiver Modus
edge-connector run --interactive

---

bundle

Tool-Bundles für deine Organisation verwalten. Bundles sind versionierte Sammlungen von Tool-Implementierungen, die auf die Plattform hochgeladen und an Edge-Connector-Instanzen verteilt werden.

edge-connector bundle <subcommand> [options]

bundle list

Alle für deine Organisation registrierten Bundles auflisten.

edge-connector bundle list [--api <url>]

Zeigt jedes Bundle mit Name (oder Kurz-ID), Version, Tool-Anzahl, Gesamtgröße und ob es der Organisations-Standard ist. Das aktuell ausgecheckte Bundle wird mit einem Sternchen (*) markiert.

bundle checkout

Zu einem anderen Bundle wechseln oder vom aktuellen Bundle trennen.

edge-connector bundle checkout <bundleId> [--api <url>]
edge-connector bundle checkout --new

Option	Beschreibung
<bundleId>	Vollständige oder partielle Bundle-ID zum Wechseln
--new	Vom aktuellen Bundle trennen; der nächste Upload erstellt ein neues Bundle

Beim Auschecken eines Bundles synchronisiert die CLI die Tool-Referenzen in dein lokales tools/-Verzeichnis. Für jedes Tool im Bundle: Wenn du lokalen Quellcode hast, bleibt er erhalten. Falls nicht, wird eine .ref.json-Referenzdatei erstellt.

bundle status

Deine lokalen Tools mit dem aktuell ausgecheckten Bundle vergleichen.

edge-connector bundle status [--api <url>]

Zeigt jedes Tool mit einem Statusindikator:

• [src] — lokale Quelldatei vorhanden
• [ref] — verwendet eine servergehostete Referenz
• + — neues Tool, das beim nächsten Upload hinzugefügt wird
• - — Tool fehlt lokal und wird beim nächsten Upload entfernt

bundle tools

Alle verfügbaren Tool-Versionen für deine Organisation über alle Bundles hinweg auflisten.

edge-connector bundle tools [--api <url>]

Zeigt jeden Tool-Namen, die neueste Versionsnummer und die Gesamtzahl der verfügbaren Versionen.

bundle ref

Einen Tool-Versions-Referenzpointer (.ref.json) für ein bestimmtes Tool abrufen.

edge-connector bundle ref <toolName> [--version <n>] [--api <url>]

Option	Beschreibung
<toolName>	Name des zu referenzierenden Tools
--version <n>	Auf eine bestimmte Versionsnummer festlegen (Standard: neueste)

Erstellt eine .ref.json-Datei im tools/-Verzeichnis, die auf die angegebene Tool-Version auf dem Server zeigt. Beim Upload des Bundles löst die Plattform diese Referenz zur korrekten kompilierten Implementierung auf. Eine lokale Quelldatei für dasselbe Tool darf nicht existieren — entferne sie zuerst, um eine Referenz zu verwenden.

bundle set-default

Ein Bundle als Organisations-Standard festlegen. Neue Edge-Connector-Instanzen ohne spezifische Bundle-Zuweisung synchronisieren automatisch dieses Bundle.

edge-connector bundle set-default <bundleId> [--api <url>]

bundle assign

Ein Bundle einem bestimmten Deployment zuweisen. Die zugewiesene Edge-Connector-Instanz synchronisiert dieses Bundle bei ihrem nächsten Check.

edge-connector bundle assign <bundleId> --deployment <deploymentId> [--version <n>] [--api <url>]

Option	Beschreibung
--deployment <deploymentId>	(Erforderlich) Deployment-ID, der das Bundle zugewiesen wird
--version <n>	Auf eine bestimmte Bundle-Version festlegen (Standard: neueste)

bundle rename

Ein Bundle umbenennen, um ihm ein lesbares Label zu geben.

edge-connector bundle rename <bundleId> <name> [--api <url>]

---

cloud

Den Lebenszyklus eines Cloud Connectors für deine Organisation verwalten. Cloud Connectors sind vollständig verwaltete Edge-Connector-Instanzen, die auf der Cloud-Infrastruktur von nara laufen.

edge-connector cloud <subcommand>

Hinweis

Alle Cloud-Befehle benötigen einen gültigen Authentifizierungs-Token. Führe zuerst edge-connector auth aus.

cloud provision

Einen neuen Cloud-Connector-Eintrag für deine Organisation provisionieren.

edge-connector cloud provision [--env <env>]

Option	Standard	Beschreibung
--env <env>	prod	Zielumgebung: dev, stage oder prod

cloud start

Die Cloud-Connector-Runtime starten. Die Plattform fährt die Kubernetes-Ressourcen hoch und beginnt, dein zugewiesenes Bundle auszuführen.

edge-connector cloud start

cloud stop

Die Cloud-Connector-Runtime stoppen. Ressourcen werden herunterskaliert, aber der Deployment-Eintrag bleibt erhalten.

edge-connector cloud stop

cloud status

Den aktuellen Status deines Cloud Connectors abrufen, einschließlich Runtime-Status, gewünschtem Status, Umgebung, Image-Tag und der letzten Operation.

edge-connector cloud status

cloud force-complete

Eine feststeckende Cloud-Operation erzwungen abschließen. Verwende das, wenn eine Provision-, Start- oder Stop-Operation nicht voranschreitet.

edge-connector cloud force-complete

cloud delete

Den Cloud Connector löschen und alle zugehörigen Kubernetes-Ressourcen abbauen. Diese Aktion ist unwiderruflich.

edge-connector cloud delete

---

generate

Boilerplate-Code für eine Tool-Implementierung generieren. Verbindet sich mit dem nara Platform Server, um die Parameter- und Ergebnis-Schemas des Tools abzurufen, und generiert dann eine TypeScript-Datei mit den korrekten Typen und einem Handler-Stub.

edge-connector generate [options]

Alias: g

Optionen:

Option	Standard	Beschreibung
-l, --language <language>		Zielsprache (typescript)
-t, --tool <tool>		Name des zu generierenden EDGE-Tools
-o, --output <path>	./custom-implementations	Ausgabeverzeichnis für generierte Dateien
-i, --interactive		Interaktive Eingaben zur Tool-Auswahl starten

Verhalten:

• Verbindet sich über deinen gespeicherten Authentifizierungs-Token mit dem nara Platform Server.
• Ruft die Liste der für deine Organisation verfügbaren EDGE-Tools ab (ohne eingebaute Diagnose-Tools).
• Generiert eine TypeScript-Implementierungsdatei für das angegebene Tool, inklusive typisierter Parameter, Ergebnis-Schema und Fehlerbehandlungs-Scaffolding.
• Wenn --language oder --tool weggelassen wird, fällt die CLI auf den interaktiven Modus zurück.

Beispiele:

# Ein bestimmtes Tool generieren
edge-connector generate -l typescript -t getSystemInfo -o ./custom-implementations

# Derselbe Befehl mit dem Kurz-Alias "g"
edge-connector g -l typescript -t getSystemInfo

# Interaktiver Modus -- Tools durchsuchen und auswählen
edge-connector g --interactive

---

upload

Deine eigenen Implementierungen paketieren und als Bundle auf die nara-Plattform hochladen. Dieser Befehl kombiniert die Paketierungs- und Upload-Schritte in einer einzigen Operation.

edge-connector upload [options]

Optionen:

Option	Standard	Beschreibung
-f, --file <path>		Pfad zu einer vorgebauten .tgz-Bundle-Datei (überspringt Paketierung)
-i, --implementations <path>	./custom-implementations	Pfad zum Implementierungsverzeichnis
--no-build		TypeScript-Kompilierung vor dem Paketieren überspringen
--api <url>	Platform-API-URL aus Config	Basis-URL der Platform-API
--name <text>		Optionaler lesbarer Name für das Bundle
--notes <text>	Uploaded via CLI	Notizen zu dieser Bundle-Version

Verhalten:

• Wenn --file nicht angegeben wird, führt die CLI zuerst den Paketierungsschritt aus: Kompiliert TypeScript-Tool-Dateien mit esbuild, erstellt ein Manifest und erzeugt ein .tgz-Archiv.
• Das Archiv wird auf die Plattform hochgeladen.
• Die maximale Bundle-Größe beträgt 50 MB.
• Wenn du aktuell ein Bundle trackst (currentBundleId in der Config), aktualisiert der Upload dieses Bundle mit einer neuen Version. Andernfalls wird ein neues Bundle erstellt.
• Manifest-Referenzen (.ref.json) werden automatisch aus dem .tgz-Archiv extrahiert, sodass du Bundles aus lokalen und servergehosteten Tools zusammenstellen kannst.
• Bei Erfolg gibt die CLI die neue Bundle-Versionsnummer aus.

Beispiele:

# In einem Schritt paketieren und hochladen
edge-connector upload

# Ein vorgebautes Bundle hochladen
edge-connector upload -f ./artifacts/edge-bundle-org123-1710000000.tgz

# Mit Name und Notizen hochladen
edge-connector upload --name "Production v2" --notes "Added VPN diagnostic tool"

---

package

Ein verteilbares Bundle-Archiv aus deinen Tool-Implementierungen bauen, ohne es hochzuladen. Das ist nützlich, wenn du das Bundle vor dem Upload inspizieren oder von einer anderen Maschine hochladen möchtest.

edge-connector package [options]

Optionen:

Option	Standard	Beschreibung
-i, --implementations <path>	./custom-implementations	Pfad zum Implementierungsverzeichnis
-o, --out <dir>	./artifacts	Ausgabeverzeichnis für das Bundle-Archiv
--no-build		TypeScript-Kompilierung überspringen (setzt voraus, dass dist/ bereits existiert)

Verhalten:

• Wenn node_modules/ im Implementierungsverzeichnis nicht existiert, wird vor dem Paketieren automatisch pnpm install ausgeführt.
• Entdeckt Tool-Quelldateien in <implementations>/tools/ (.ts, .js, .mjs, .cjs).
• TypeScript wird automatisch erkannt: Wenn eine index.ts-Datei im Implementierungs-Root existiert, wird es als TypeScript-Projekt behandelt und entsprechend kompiliert.
• Kompiliert jedes Tool einzeln mit esbuild in das dist/tools/-Verzeichnis.
• Generiert einen Auto-Index (dist/index.js), der alle Tool-Handler aus den kompilierten dist/tools/-Dateien re-exportiert.
• Entdeckt .ref.json-Referenzdateien und nimmt sie in das Manifest auf.
• Erstellt ein .tgz-Archiv mit Manifest und kompilierter Ausgabe.
• Die Archivdatei heißt edge-bundle-<orgId>-<timestamp>.tgz.

Tipp

Jedes Tool muss eine eigene Datei unter tools/ sein (z.B. tools/my_tool.ts). Single-Entrypoint-Bundles mit nur einer index.ts werden nicht mehr unterstützt.

Beispiele:

# Mit Standardeinstellungen paketieren
edge-connector package

# Aus einem benutzerdefinierten Verzeichnis paketieren
edge-connector package -i ./my-tools -o ./build

# Ohne Neubau paketieren (vorhandenes dist/ verwenden)
edge-connector package --no-build