n8n-cli Operations-Skill

Ein Skill zur Unterstützung der Workflow-Verwaltung mit n8n-cli (TypeScript/Bun).

Sitzungsinitialisierung (Wichtig)

Führen Sie bei neuen Sitzungen immer zuerst Folgendes aus, um sicherzustellen, dass n8n-cli auf dem neuesten Stand ist.

Priorität 1: Aus lokaler Quelle erstellen (Entwicklung)

Wenn das n8n-cli-Quellrepository über add-dir verfügbar ist (z. B. /pfad/zu/n8n-cli/Makefile existiert), erstellen Sie aus der lokalen Quelle anstatt ein Release zu verwenden. Dadurch werden die neuesten Entwicklungsänderungen sofort übernommen.

# Wenn n8n-cli Repo über add-dir sichtbar ist
N8N_CLI_REPO="/pfad/zu/n8n-cli"  # Durch add-dir-Pfad ersetzen
if [ -f "$N8N_CLI_REPO/Makefile" ]; then
  echo "Erstelle n8n-cli aus lokaler Quelle: $N8N_CLI_REPO"
  cd "$N8N_CLI_REPO" && bun install && make build
  cp "$N8N_CLI_REPO/n8n-cli" /pfad/zu/ziel/n8n-cli
  cd /pfad/zu/ziel
  echo "Aus lokaler Quelle erstellt: $(./n8n-cli version 2>/dev/null | head -1)"
fi

Priorität 2: Automatisches Update von GitHub Releases (bevorzugt)

Vorgefertigte Binärdateien sind auf GitHub Releases verfügbar. Dies ist schneller als das Erstellen aus der Quelle und stellt sicher, dass Sie das offizielle Release ausführen.

# 1. Die neueste Release-Version prüfen
LATEST_TAG=$(gh release view --repo ubie-oss/n8n-cli --json tagName -q '.tagName' 2>/dev/null)

# 2. Aktuelle lokale Version prüfen (wenn Binärdatei existiert)
CURRENT_VERSION=""
if [ -x ./n8n-cli ]; then
  CURRENT_VERSION=$(./n8n-cli version 2>/dev/null | head -1 | grep -oE 'v[0-9]+\.[0-9]+\.[0-9]+' || echo "")
fi

# 3. Vergleichen und bei Bedarf herunterladen
if [ -z "$CURRENT_VERSION" ] || [ "$CURRENT_VERSION" != "$LATEST_TAG" ]; then
  echo "Aktualisiere n8n-cli: ${CURRENT_VERSION:-keine} -> ${LATEST_TAG}"

  # Plattform erkennen
  ARCH=$(uname -m)
  OS=$(uname -s | tr '[:upper:]' '[:lower:]')
  case "$ARCH" in
    arm64|aarch64) ASSET_NAME="n8n-cli-${OS}-arm64" ;;
    x86_64)        ASSET_NAME="n8n-cli-${OS}-x64" ;;
    *)             echo "Nicht unterstützte Architektur: $ARCH"; exit 1 ;;
  esac

  # Binärdatei herunterladen
  gh release download "$LATEST_TAG" --repo ubie-oss/n8n-cli --pattern "$ASSET_NAME" --output n8n-cli --clobber
  chmod +x ./n8n-cli
  echo "Aktualisiert auf $(./n8n-cli version 2>/dev/null | head -1)"
else
  echo "n8n-cli ist aktuell: $CURRENT_VERSION"
fi

Fallback: Aus Quelle erstellen

Wenn die gh CLI nicht verfügbar ist oder Sie einen Entwicklungsbuild benötigen:

# Abhängigkeiten installieren + CLI erstellen
bun install && make build

Build-Überprüfung:

./n8n-cli version

Umgebungseinrichtung

Prüfen der .env-Datei

Wenn .env im Projektstammverzeichnis existiert, kann n8n-cli ohne Angabe von Parametern verwendet werden. Lesen Sie den Inhalt nicht.

# Nur auf Existenz von .env prüfen (Inhalt nicht lesen)
test -f .env && echo ".env existiert - n8n-cli kann ohne Parameter verwendet werden"

Wenn .env existiert:

N8N_API_URL und N8N_API_KEY sind bereits konfiguriert
./n8n-cli kann ohne Parameter ausgeführt werden

Wenn .env nicht existiert:

Fordern Sie den Benutzer auf, eine .env-Datei zu erstellen
Oder verwenden Sie die Flags --api-url und --api-key

Erstellen von .env (nur bei Bedarf)

cp .env.example .env
# Bitten Sie den Benutzer, die Datei zu bearbeiten

Häufige Befehle

1. Status von Remote-Workflows prüfen

Einen bestimmten Workflow prüfen:

# Workflow-Info nach ID abrufen
./n8n-cli workflow get <workflow-id>

# In Tabellenformat für Lesbarkeit anzeigen
./n8n-cli -o table workflow get <workflow-id>

# In Datei speichern (nützlich für Diff-Vergleiche)
./n8n-cli workflow get <workflow-id> > /tmp/remote-workflow.json

Workflows auflisten:

# Alle Workflows
./n8n-cli workflow list

# Tabellenformat
./n8n-cli -o table workflow list

# Nur aktive
./n8n-cli workflow list --active

2. Workflows importieren (Remote -> Lokal)

Lokales Format vor dem Import prüfen

Beim Abrufen von Remote-Inhalten ins Lokale führen Sie immer folgende Schritte aus:

Lokales Dateiformat prüfen

# Prüfen, ob Datei existiert und ihr Format
ls -la definitions/*<workflow-id>* definitions/**/*<workflow-id>*

Geeignete Import-Optionen basierend auf Format verwenden
- .json-Dateien: nur --ids verwenden
- .yaml/.yml-Dateien: sowohl --ids als auch --yaml verwenden

Einen bestimmten Workflow importieren:

# Workflow im JSON-Format
./n8n-cli import --ids=<workflow-id>

# Workflow im YAML-Format
./n8n-cli import --ids=<workflow-id> --yaml

# In ein benutzerdefiniertes Verzeichnis
./n8n-cli import --ids=<workflow-id> -d ./mein-verz

Mehrere Workflows importieren:

# Kommagetrennte Liste
./n8n-cli import --ids=abc123,def456,ghi789

Alle Workflows importieren:

./n8n-cli import

Zusätzliche Optionen:

Option	Beschreibung
`--include-archived`	Archivierte Workflows einschließen
`--cleanup-orphans`	Verwaiste Dateien ohne passende IDs löschen
`-t, --threshold <int>`	Mindestzeilen für die externe Dateiextraktion (Standard: 0, in CLAUDE.md konfigurierbar)
`--dry-run`	Nur Vorschau (keine Dateiänderungen)
`--tags <tags>`	Nach kommagetrennten Tagnamen filtern (UND-Bedingung)

3. Dry-Run (Änderungsvorschau)

Vor der Anwendung immer mit Dry-Run überprüfen:

# Vorschau der Änderungen für alle Workflows
./n8n-cli apply --dry-run

# Nur für einen bestimmten Workflow (nach ID)
./n8n-cli apply --dry-run --ids=<workflow-id>

# Nur für eine bestimmte Datei
./n8n-cli apply --dry-run -d definitions/pfad/zum/workflow.json

Beispielausgabe:

=== ERSTELLEN (1 Workflow) ===
  + neuer-workflow.json (name: "Neue Automatisierung")

=== AKTUALISIEREN (2 Workflows) ===
  ~ vorhanden.json (id: R2cTI0LDzCJSnvNG)
    - name: "Alter Name" -> "Neuer Name"
    - nodes: 3 -> 5 nodes

=== ÜBERSPRINGEN (1 Workflow) ===
  = unverändert.json (keine Änderungen)

Zusammenfassung (Dry-Run): 1 zu erstellen, 2 zu aktualisieren, 1 unverändert

4. Anwenden (Deployment)

KI-Assistenten müssen immer --ids verwenden

# Nur einen bestimmten Workflow anwenden (empfohlen)
./n8n-cli apply --ids=<workflow-id>

# Nur eine bestimmte Datei anwenden
./n8n-cli apply -d definitions/pfad/zum/workflow.json

# Erzwungenes Anwenden (Remote-Änderungen überschreiben)
./n8n-cli apply --ids=<workflow-id> --force

Verboten: Anwenden auf ein ganzes Verzeichnis

# Diese dürfen NICHT von der KI ausgeführt werden
./n8n-cli apply -d definitions/
./n8n-cli apply

Zusätzliche Optionen:

Option	Beschreibung
`--from-git-changes <spec>`	Nur in Git Diff geänderte Dateien anwenden
`--yaml` / `--no-yaml`	YAML-Verarbeitung aktivieren/deaktivieren
`--allow-duplicates`	Die vorgelagerte Duplikatnamen-Prüfung überspringen (Standard: an; verwenden Sie `--force`, um Warnungen zu überschreiten, anstatt die Prüfung zu deaktivieren)
`--no-auto-tag`	Automatische Tag-Erstellung deaktivieren (managed-as-code)
`-p, --project <id>`	Zielprojekt-ID angeben

Umgebungsvariablen:

APPLY_FILTER_BY_TAGS - Nach kommagetrennten Tagnamen filtern (UND-Bedingung)

Git-Diff-Modus:

# Nur Änderungen aus einem Feature-Branch anwenden
./n8n-cli apply --from-git-changes origin/main..HEAD

# Vorschau
./n8n-cli apply --from-git-changes origin/main..HEAD --dry-run

# Änderungen aus den letzten 3 Commits
./n8n-cli apply --from-git-changes HEAD~3..HEAD

3-Wege-Konflikterkennung: Wenn --from-git-changes angegeben wird, werden Konflikte erkannt, indem Basis (Referenzpunkt), Lokal (aktuell) und Remote (Server) verglichen werden, um nur echte Konflikte zu identifizieren.

5. Linter (Qualitätsprüfungen)

Der Linter ist in die CLI integriert. Kein separater Build erforderlich.

Hinweis: Positionsargumente werden nicht unterstützt. Geben Sie Dateien/Verzeichnisse immer mit -f oder -d an.

# Eine bestimmte Datei prüfen (-f erforderlich)
./n8n-cli lint -f definitions/<dateiname>

# Ein bestimmtes Verzeichnis prüfen
./n8n-cli lint -d ./definitions/beispiel-projekt

# Alle Workflows prüfen
./n8n-cli lint -d ./definitions

# JSON-Ausgabe (für CI/CD)
./n8n-cli lint -d ./definitions -o json

Optionen:

Option	Beschreibung
`-d, --dir <pfad>`	Verzeichnis der Definitionsdateien
`-f, --file <dateien...>`	Bestimmte Datei(en)
`-c, --config <pfad>`	Konfigurationsdateipfad (.n8nlintrc.json)
`--disable-rule <name>`	Bestimmte Regel(n) deaktivieren
`--list-rules`	Alle Regeln auflisten
`-o, --output <format>`	Ausgabeformat: text, json (Standard: text)

Regeln (11 Regeln):

Regel	Schweregrad	Beschreibung
`json-syntax`	Fehler	JSON-Syntaxprüfung
`required-fields`	Fehler	Prüfung auf erforderliche Felder (name, nodes, connections)
`connection-reference`	Fehler	Prüfung auf Existenz des Verbindungszielknotens
`webhook-id-required`	Fehler	Prüfung, ob Webhook- und formTrigger-Knoten das Feld webhookId haben
`orphaned-node`	Warnung	Erkennung verwaister Knoten
`implicit-json-ref`	Warnung	Erkennung impliziter `$json`-Referenzen
`expression-mode-prefix`	Warnung	Erkennung fehlender `=`-Präfixe
`ai-agent-output-ref`	Warnung	Erkennung von Fehlverweisen auf KI-Agentenausgaben
`node-params`	Warnung	Validierung des Knotenparameterschemas
`node-ref-field-check`	Warnung	Validierung der Existenz referenzierter Felder
`node-ref-cardinality`	Warnung	Validierung der `.item`/`.first()`-Verwendung

Konfigurationsdatei (.n8nlintrc.json):

{
  "rules": {
    "json-syntax": "error",
    "required-fields": "error",
    "orphaned-node": "warning",
    "implicit-json-ref": "off"
  }
}

Suchreihenfolge der Konfigurationsdatei:

Mit --config-Flag angegebener Pfad
.n8nlintrc.json / .n8nlintrc im Zielverzeichnis
.n8nlintrc.json / .n8nlintrc im aktuellen Verzeichnis

6. Formatierer (Auto-Formatierung)

Hinweis: fmt akzeptiert Positionsargumente für Dateien (keine -f-Option).

# Eine bestimmte Datei formatieren (Positionsargument)
./n8n-cli fmt definitions/<dateiname>

# Mehrere Dateien
./n8n-cli fmt definitions/datei1.yaml definitions/datei2.yaml

# Ein ganzes Verzeichnis formatieren
./n8n-cli fmt -d ./definitions

# Nur Vorschau
./n8n-cli fmt -d ./definitions --dry-run

7. Testen (Ausführung)

Workflows über Test-Webhooks testen:

# Basistest
./n8n-cli test <workflow-id>

# Mit Testdaten
./n8n-cli test <workflow-id> -d '{"email": "[email protected]"}'

# Auf Ausführungsende warten (empfohlen)
./n8n-cli test <workflow-id> --wait-execution

# Inaktive Workflows automatisch aktivieren
./n8n-cli test <workflow-id> --activate

# Nur Webhook-URL prüfen
./n8n-cli test <workflow-id> --dry-run

# Eingabeparameter prüfen
./n8n-cli test <workflow-id> --show-inputs

Optionen:

Option	Beschreibung
`-d, --data <json>`	Testdaten (JSON-String)
`--timeout <dauer>`	HTTP-Timeout (Standard: 30s)
`--wait-execution`	Auf Ausführungsende warten und Ergebnisse anzeigen
`--activate`	Inaktive Workflows automatisch aktivieren
`--dry-run`	Nur Webhook-URL prüfen
`--show-inputs`	Eingabeparameter anzeigen
`-o, --output <fmt>`	Ausgabeformat: json, table (Standard: json)

Test aus einer lokalen Datei:

# Eine lokale JSON/YAML-Datei angeben
./n8n-cli test ./definitions/mein-workflow.json

8. Ausführung (Protokolle & Fehler)

Letzte Ausführungen auflisten:

# Alle letzten Ausführungen auflisten
./n8n-cli execution list

# Tabellenformat für Lesbarkeit
./n8n-cli -o table execution list

# Nach Status filtern
./n8n-cli execution list --status error
./n8n-cli execution list --status success

# Nach Workflow filtern
./n8n-cli execution list --workflow <workflow-id>

# Ergebnisse begrenzen
./n8n-cli execution list --limit 5

# Kombinierte Filter
./n8n-cli execution list --workflow <workflow-id> --status error --limit 10

Ausführungsdetails abrufen:

# Ausführung nach ID abrufen
./n8n-cli execution get <execution-id>

# Tabellenformat mit Fehlerdetails
./n8n-cli -o table execution get <execution-id>

# Knotenausführungszusammenfassung einschließen
./n8n-cli -o table execution get <execution-id> --show-data

Optionen für execution list:

Option	Beschreibung
`-w, --workflow <id>`	Nach Workflow-ID filtern
`-s, --status <status>`	Nach Status filtern (success, error, running, waiting)
`-l, --limit <n>`	Maximale Anzahl von Ausführungen (Standard: 20)

Optionen für execution get:

Option	Beschreibung
`--show-data`	Knotenausführungszusammenfassung in die Ausgabe einschließen

Angezeigte Fehlerinformationen:

Feld	Beschreibung
Fehlerknoten	Der Knoten, in dem der Fehler aufgetreten ist
Fehlermeldung	Die Fehlermeldung
Fehlerdetails	Zusätzliche Fehlerbeschreibung (falls verfügbar)
Letzter Knoten	Der zuletzt ausgeführte Knoten

Typischer Debugging-Workflow:

# 1. Letzte Fehler auflisten
./n8n-cli -o table execution list --status error --limit 5

# 2. Details einer bestimmten fehlgeschlagenen Ausführung abrufen
./n8n-cli -o table execution get <execution-id> --show-data

# 3. Fehlerdetails überprüfen und Workflow korrigieren

9. Konvertieren (Formatkonvertierung)

Workflow-Dateien zwischen JSON- und YAML-Formaten konvertieren (nur lokal, keine API erforderlich):

# Alle JSON-Workflows nach YAML konvertieren
./n8n-cli convert -d ./definitions --format yaml

# Bestimmte Workflows nach ID konvertieren
./n8n-cli convert -d ./definitions --format json --ids <workflow-id>

# Vorschau ohne Schreiben
./n8n-cli convert -d ./definitions --format yaml --dry-run

# Originaldateien behalten
./n8n-cli convert -d ./definitions --format yaml --keep

# Eine einzelne Datei konvertieren
./n8n-cli convert --format yaml definitions/<dateiname>.json

Optionen:

Option	Beschreibung
`--format <format>`	Zielformat: `json`, `yaml` (erforderlich)
`-d, --directory <verz>`	Verzeichnis zum Durchsuchen von Workflow-Dateien
`--ids <ids>`	Kommagetrennte Workflow-IDs zum Konvertieren
`--tags <tags>`	Nach Tags filtern (kommagetrennt, UND-Bedingung)
`-t, --threshold <n>`	Mindestzeilen für Code-Externalisierung (JSON→YAML)
`--dry-run`	Nur Vorschau
`--keep`	Originaldateien behalten

Verhalten:

JSON→YAML: erzeugt YAML + _subfiles/ mit externalisiertem Code
YAML→JSON: löst !include-Referenzen auf und entfernt _subfiles/
Dateien, die bereits im Zielformat vorliegen, werden übersprungen
Originaldateien werden nach der Konvertierung entfernt, außer bei --keep

10. Datentabellen

Datentabellen und Zeilen verwalten:

# Alle Datentabellen auflisten
./n8n-
...

ubie-oss/n8n-cli

Was ist n8n-cli?

In Ihrer bevorzugten KI fragen

Dokumentation

n8n-cli Operations-Skill

Sitzungsinitialisierung (Wichtig)

Priorität 1: Aus lokaler Quelle erstellen (Entwicklung)

Priorität 2: Automatisches Update von GitHub Releases (bevorzugt)

Fallback: Aus Quelle erstellen

Umgebungseinrichtung

Prüfen der .env-Datei

Erstellen von .env (nur bei Bedarf)

Häufige Befehle

1. Status von Remote-Workflows prüfen

2. Workflows importieren (Remote -> Lokal)

Lokales Format vor dem Import prüfen

3. Dry-Run (Änderungsvorschau)

4. Anwenden (Deployment)

5. Linter (Qualitätsprüfungen)

6. Formatierer (Auto-Formatierung)

7. Testen (Ausführung)

8. Ausführung (Protokolle & Fehler)

9. Konvertieren (Formatkonvertierung)

10. Datentabellen

Verwandte Skills

steipete/notion

langchain-ai/langchain

bytedance/podcast-generation

composiohq/twitter-algorithm-optimizer

composiohq/competitive-ads-extractor

upstash/context7