Zum Hauptinhalt springen

Installieren und anmelden

Installieren​

Die CLI ist das npm-Paket formfeed und braucht Node.js 22 oder neuer.

# ohne Installation ausführen
npx formfeed --help

# oder global installieren
npm install -g formfeed
formfeed --version

In einem Projekt, das sie in Skripten oder in der CI nutzt, fügen Sie sie als Dev-Abhängigkeit hinzu, damit alle dieselbe Version bekommen: npm install -D formfeed. npx formfeed führt dann genau diese Version aus.

Die Befehle, die offline arbeiten (init ohne --from-workspace, dev, validate, test, einvoice, types innerhalb eines Projekts), brauchen kein Konto. Alle anderen brauchen einen API-Schlüssel: Melden Sie sich einmal an oder setzen Sie FORMFEED_API_KEY.

Anmelden​

formfeed login
  1. Die CLI gibt die Adresse der App-Seite Kommandozeile verbinden und einen Code wie ABCD-EFGH aus, öffnet die Seite mit bereits eingetragenem Code und wartet. Der Code gilt 10 Minuten.
  2. Melden Sie sich in der App an, falls nötig, prüfen Sie, dass der Code dem in Ihrem Terminal entspricht, wählen Sie den Workspace und klicken Sie auf Verbinden. Ablehnen beendet die Anmeldung im Terminal.
  3. Die CLI erhält einen API-Schlüssel und speichert ihn. Sie nennt die Organisation und den Workspace, für die er bestätigt wurde.

Der Schlüssel ist ein Live-Schlüssel (ff_live_…) mit dem Namen Formfeed CLI on <Name Ihres Rechners>, für den gewählten Workspace und mit den Scopes Ihrer Rolle in der Organisation. Er erscheint in der App unter API-Schlüssel und lässt sich dort wie jeder andere widerrufen. Weil er ein Live-Schlüssel ist, zählen Renderings, die mit ihm entstehen (formfeed render, das echte Rendering in formfeed dev, ci preview), gegen Ihren Plan. Für kostenlose Test-Renderings legen Sie unter API-Schlüssel einen Test-Schlüssel an und speichern ihn mit --api-key.

  • --no-browser lässt den Browser geschlossen; öffnen Sie die ausgegebene Adresse selbst, etwa auf einem Server oder in einer SSH-Sitzung. --ci oder eine gesetzte Variable CI wirkt genauso.
  • formfeed login --api-key ff_test_… (oder formfeed login ff_test_…) speichert stattdessen einen vorhandenen Schlüssel. Die CLI prüft ihn zuerst mit GET /account: Ein unbekannter oder widerrufener Schlüssel scheitert mit Exit-Code 3. Ein Schlüssel ohne den Scope account:read wird trotzdem gespeichert, aber formfeed whoami kann seinen Workspace nicht anzeigen.
  • formfeed whoami zeigt Organisation, Workspace und Region des gespeicherten Schlüssels, den Plan mit den verbrauchten von den enthaltenen Einheiten der laufenden Periode und ob es ein Test- oder Live-Schlüssel ist.
  • formfeed logout entfernt den Schlüssel aus der Benutzerkonfiguration. Gültig bleibt er, bis Sie ihn unter API-Schlüssel widerrufen.

Der Schlüssel liegt in der Benutzerkonfiguration, einer Datei, die nur Ihr Benutzer lesen kann: ~/.config/formfeed/config.json (oder $XDG_CONFIG_HOME/formfeed/config.json) unter macOS und Linux, %APPDATA%\formfeed\config.json unter Windows, oder config.json in FORMFEED_CONFIG_DIR, wenn diese Variable gesetzt ist. login schreibt dort auch die Region hinein und, wenn Sie eine angegeben haben, die Basis-URL.

Melden Sie sich in der CI nicht an. Setzen Sie FORMFEED_API_KEY aus Ihrem Secret-Speicher; die Variable hat Vorrang vor der gespeicherten Anmeldung.

Einen Ordner an einen Workspace binden​

formfeed init --from-workspace

Das schreibt formfeed.json, legt templates/ und partials/ an und zieht jede Vorlage aus dem Workspace des Schlüssels: die veröffentlichte Version oder, bei einer nie veröffentlichten Vorlage, den neuesten Entwurf. Dazu holt es die geteilten Partials der Organisation, damit Vorlagen, die eines einbinden, sofort validieren. Dafür braucht es einen Schlüssel mit template:read.

  • Ohne --from-workspace legt init stattdessen eine Startvorlage hello an und braucht keinen Schlüssel.
  • Übergeben Sie ein Verzeichnis, um das Projekt an anderer Stelle anzulegen: formfeed init my-templates.
  • --engine liquid (oder jinja2, handlebars) legt die Vorlagensprache neuer Vorlagen in formfeed.json fest; Standard ist jinja2.
  • --workspace fennlor/production hält den Workspace in formfeed.json als Hinweis für das Team fest. Einen Workspace wählt es nicht aus: Das tut der API-Schlüssel.
  • init verweigert einen Ordner, der schon eine formfeed.json hat (Exit-Code 2).

Weiter geht es mit Vorlagen als Code, oder lesen Sie Konfiguration und die Projektstruktur.