Konfiguration

Die CLI liest ihre Einstellungen an vier Stellen: Kommandozeilen-Flags, Umgebungsvariablen, die formfeed.json des Projekts und Ihre Benutzerkonfiguration.

Rangfolge

Wenn dieselbe Einstellung an mehreren Stellen angegeben ist, gilt die erste:

1. Kommandozeilen-Flags (--api-key, --workspace, --region, --base-url)
2. Umgebungsvariablen (FORMFEED_API_KEY, …)
3. formfeed.json im Projekt, vom aktuellen Verzeichnis aufwärts gesucht
4. Die Benutzerkonfiguration, die formfeed login und formfeed config set schreiben

Nicht jede Einstellung lässt sich an jeder Stelle angeben:

Einstellung	Flag	Umgebung	formfeed.json	Benutzerkonfiguration	Ohne Angabe
API-Schlüssel	--api-key	FORMFEED_API_KEY		apiKey	Befehle, die die API brauchen, scheitern mit Exit-Code 3
Basis-URL	--base-url	FORMFEED_BASE_URL		baseUrl	Der Host der Region
Region	--region	FORMFEED_REGION	region	region	eu
Workspace	--workspace	FORMFEED_WORKSPACE	workspace	workspace	keiner

Der API-Schlüssel entscheidet über den Workspace. Ein Schlüssel gehört zu genau einem Workspace, und jeder Befehl, der die API aufruft, arbeitet in diesem. Die Einstellung Workspace ist eine Beschriftung: init --workspace hält sie in formfeed.json fest, damit das Team weiß, zu welchem Workspace das Projekt gehört, und config list zeigt sie an, aber kein Befehl sendet sie an die API oder vergleicht sie mit dem Schlüssel. Um in einem anderen Workspace zu arbeiten, verwenden Sie einen Schlüssel dieses Workspace. formfeed whoami zeigt, zu welchem Workspace der aktuelle Schlüssel gehört.

formfeed config list gibt den API-Schlüssel (seine ersten 12 Zeichen), die Basis-URL, den Workspace und die Region aus, die die CLI verwenden würde, dazu die gefundene formfeed.json und den Ort der Benutzerkonfiguration. Von welcher der Stellen oben ein Wert stammt, sagt es nicht.

formfeed.json

{
  "workspace": "fennlor/production",
  "region": "eu",
  "templatesDir": "templates",
  "partialsDir": "partials",
  "filesDir": "files",
  "engine": "jinja2",
  "ignore": ["**/drafts/**"],
  "types": { "lang": "ts", "out": "src/formfeed.d.ts" },
  "pull": { "redact": ["customer.*", "iban"] }
}

formfeed init schreibt die Datei mit den Standardwerten unten. Der Ordner, der sie enthält, ist der Projektordner; die CLI findet sie aus jedem Ordner darunter.

Feld	Standard	Bedeutung
workspace	keiner	org-slug/workspace-slug, zu dem das Projekt gehört; für Menschen festgehalten, nicht zur Wahl des Workspace verwendet (siehe oben)
region	eu	eu oder us: der API-Host, mit dem die CLI spricht (api-eu.formfeed.dev oder api-us.formfeed.dev)
templatesDir, partialsDir, filesDir	templates, partials, files	Ordner relativ zu formfeed.json; filesDir spiegelt die Dateibibliothek des Workspace. Siehe Projektstruktur
engine	jinja2	Vorlagensprache von Vorlagen, deren template.json keine nennt, und von Vorlagen, die templates push ohne eine anlegt (jinja2, liquid oder handlebars)
ignore	["**/drafts/**"]	Glob-Muster relativ zum Projektordner für Vorlagenordner, die templates push auslässt, wenn es alle Vorlagen hochlädt (templates/wip-*); ** umfasst mehrere Ordner, ein Name ohne / passt in jeder Tiefe. Ein auf der Kommandozeile genannter Ordner wird trotzdem hochgeladen, und --dry-run führt die ausgelassenen Ordner als ignored.
types	keiner	Standardwerte von formfeed types: lang (ts oder python, Standard ts), out (die Datei, relativ zum Projektordner; Standard formfeed.d.ts oder formfeed_templates.py) und sdkModule (das Modul, das die TypeScript-Datei erweitert, Standard @formfeed/sdk); siehe Typisierte Vorlagendaten
pull	keiner	Standardwerte von formfeed renders pull: redact, die Datenpfade, die in jedem geholten Datensatz geschwärzt werden; siehe Ein fehlgeschlagenes Rendering nachstellen

Committen Sie formfeed.json. Die Datei enthält keine Geheimnisse.

Umgebungsvariablen

Variable	Zweck
FORMFEED_API_KEY	API-Schlüssel; wird statt der gespeicherten Anmeldung verwendet. Der übliche Weg, sich in der CI zu authentifizieren.
FORMFEED_WORKSPACE	Überschreibt workspace (eine Beschriftung; der Schlüssel entscheidet über den Workspace)
FORMFEED_REGION	Überschreibt region (eu oder us)
FORMFEED_BASE_URL	Basis-URL der API inklusive /v1, statt der Adresse der Region (nur für eine andere Adresse als die öffentliche API); hat Vorrang vor der Region
FORMFEED_CONFIG_DIR	Verzeichnis der Benutzerkonfiguration, statt des Standards der Plattform
CI	Mit einem beliebigen Wert öffnet formfeed login keinen Browser (wie --ci), und lange Befehle zeichnen keine Fortschrittszeile
NO_COLOR, FORCE_COLOR	NO_COLOR schaltet Farben ab; FORCE_COLOR schaltet sie auch dann ein, wenn die Ausgabe kein Terminal ist (0 oder false schaltet sie ab)
PDFMONKEY_API_KEY	PDFMonkey-Schlüssel für formfeed import pdfmonkey, statt --key
APITEMPLATE_API_KEY	apitemplate.io-Schlüssel für formfeed import apitemplate, statt --key
APITEMPLATE_REGION	apitemplate.io-Region für formfeed import apitemplate, statt --source-region (default, wenn keins von beiden gesetzt ist)

Die Test-Helfer lesen ebenfalls FORMFEED_API_KEY, FORMFEED_REGION und FORMFEED_BASE_URL, und FORMFEED_REQUIRE_API=1 lässt ihren API-gestützten Matcher fehlschlagen, statt ihn zu überspringen, wenn kein Schlüssel gesetzt ist. Die CLI selbst liest FORMFEED_REQUIRE_API nicht.

Benutzerkonfiguration

Die Benutzerkonfiguration enthält die Einstellungen, die zu Ihnen gehören, nicht zu einem Projekt: meist den Schlüssel, den formfeed login gespeichert hat. Sie liegt in ~/.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. Die CLI schreibt sie so, dass nur Ihr Benutzer sie lesen kann.

formfeed config set region us
formfeed config get region        # us
formfeed config get apiKey        # nur die ersten 12 Zeichen

formfeed config get|set <key> liest und schreibt apiKey, baseUrl, workspace und region; einen anderen Schlüsselnamen weist es mit Exit-Code 2 ab. config set speichert den Wert wie angegeben und prüft ihn nicht.