CLI-Referenz

Befehl	Ausgabe
tree <file> [node] [--depth N] [--json]	Node-IDs, REST-Typen (wie in nodes) und Namen; eingerückter Text oder verschachteltes JSON mit Größe, Ausblendung und Auto-Layout-Modus jedes Nodes sowie firstText (erster sichtbarer Text) bei Nodes einer Seite oder Section
tree <file> [node] --top-frames [--json]	Nur die Screens, einer pro Zeile, direkt nutzbar für --frames -: Frames, Komponenten, Komponentensets und Instanzen auf einer Seite oder in ihren Sections (Gruppen und interne Seiten ausgenommen); --json ergänzt Seiten- und Section-IDs sowie den ersten sichtbaren Text jedes Screens (firstText), der Canvas-Beschriftungen von Screens unterscheidet
find <file> <query> [--type TYPE] [--node ID] [--limit N]	Suche über Layer-Namen und Text ohne Beachtung der Groß-/Kleinschreibung; Pfade, Größen und Vorschauen. Standardmäßig 20 Ergebnisse (1-200)
search <file> <query> [--node ID] [--type T[,T]] [--limit N] [--cursor C] [--include-hidden] [--include-internal] [--mode text|semantic|hybrid|visual] [--image PNG|--image-ref JSON] [--crop x,y,w,h]	Gerankte Suche über Layer-Namen und vollständigen Text mit angewendeten Instanz-Overrides, Text-/Boolean-Properties und Swaps; exakte Node-Referenzen (auch I…;…-Sublayer-IDs für inspect), Treffergründe, UTF-16-Spannen, Abdeckung und Cursor-Seiten. Standardmäßig 20 (1-200); ausgeblendete Layer und interne Seiten brauchen ihr Flag. Mit --file/--workspace/--id statt <file> liest es den vorbereiteten Index des Workspaces (siehe index) --mode semantic|hybrid braucht ein eingerichtetes Modell: siehe Optionale semantische Suche.
models list|status|configure <profile> --model DIR [--runtime FILE]|remove <profile>	Lokales Textmodell für die semantische Suche (bge-m3, experimentell) und Bildmodell für die Bildsuche (siglip-base, experimentell); configure prüft die selbst heruntergeladenen Dateien und lädt nie herunter; remove behält sie. Siehe Optionale semantische Suche.
usages <file> <node|resource> [--scope ID] [--relation R[,R]] [--out] [--snapshot S] [--include-hidden] [--limit N] [--cursor C]	Exakte Beziehungen eines Layers oder einer Ressource (VariableID:…, StyleKey:…, image:…) in einem gespeicherten Bereich, verschachtelte Instanzen und Swaps eingeschlossen: wo eine Komponente, ein Set, eine Variable, ein Style oder ein Bild verwendet wird (Standard) oder worauf ein Layer zeigt (--out). Jedes Ergebnis behält seine exakte Referenz, Beziehung, seinen Zustand (resolved, missing, unresolved, …), Basis und Beleg; Namen gelten nie als Identität. Keine Gesamtzahl: Die Coverage sagt vollständig oder partiell. Standard 50 (1-200). Mit --file/--workspace/--id statt <file> liest es den vorbereiteten Index von --scope des Workspace. Mit --out nennt eine Verwendung einer gecachten Bibliothekskopie auch ihre library {kind, namespace, key}.
usages --file|--workspace|--id … --library <kind> --namespace <ns> --key <key> [--definition-source ID --definition-snapshot SNAP --definition-node NODE] [--source ID] [--scope ID] [--include-hidden] [--limit N] [--cursor C]	Layer, die eine Bibliothekskomponente, einen Bibliotheks-Style oder eine Bibliotheksvariable (kind) verwenden, so wie die zwischengespeicherte Kopie jeder Datei sie festhält, über den vorbereiteten --scope aller Quellen (--source beschränkt auf eine). Die Definition bleibt unresolved, außer die drei --definition-*-Flags wählen sie per exakter Referenz (selected, keyEvidence: unverified); die Coverage nennt den Zustand jeder Quelle und warum sie partiell ist. Die Angaben stehen im Feld library von usages --out auf einer Ebene, die es nutzt.
diff <old.fig> <new.fig> [--node ID] [--limit N] [--cursor C] [--json]	Was sich zwischen zwei gespeicherten Revisionen geändert hat: eine Zeile pro geändertem Top-Level-Frame mit Zählern je Facette (Text, Layout, Aussehen, Eigenschaften, Struktur, Bindungen); --json ergänzt alte/neue Feldwerte und Edge-Änderungen. Layer werden nur über exakte ID und Typ zugeordnet; ein Frame mit gleichem Namen oder gleicher Position ist nur ein markierter Possible Match, und eine vorzeitig gestoppte Seite oder eine Ebene, deren einziger Unterschied ein nicht lesbares Feld ist, meldet unknown, nie entfernt oder geändert. Seiten mit 100 Änderungen (1-500) Stoppt eine Seite an einem Limit, steht stopped early statt no changes; mit --node eingrenzen.
inspect <file> <node> [--depth N] [--images] [--states] [--compare-variant ID] [--compare ID] [--flat] [--full-text] [--colors]	Kompakte Zusammenfassung des expandierten Layouts/Texts, höchstens 200 Nodes. --images ergänzt Bitmap-Abmessungen und Crop-Footprints. --flat gibt stattdessen eine Zeile pro Node aus: Position relativ zum Node, Größe, Text, Schrift, Füllung, Kontur, Radius, Auto-Layout, Ausrichtung, Fixed/Fill-Größen, Schatten und Blurs --full-text liefert jeden Text vollständig (bis 10.000 Zeichen); --colors ergänzt sichtbare Vollton-Füllungen (Hex, Deckkraft, gebundene Variable), auch mit --flat; keine Verläufe, Bilder oder Konturen.
nodes <file> <node>	Das Objekt je Node einer REST-nodes-Antwort (document, components, componentSets, styles): expandierte Instanzen und Overrides, Auto-Layout, Textstile, Füllungen, Effekte, gebundene Variablen, Komponenten-Eigenschaften, Render-Bounds
nodes <file> --frames <list>, --frames - (stdin), --ids <node>...	Ein Decode, viele Nodes: eine JSON-Zeile pro gelisteter ID, die nodes-Ausgabe mit ihrer nodeId oder {nodeId, error}
variables <file> [node] variables <file.fig> --format dtcg --collection ID --mode ID --out FILE	Standard: unveränderte gebundene/lokale Variablen im REST-Format. DTCG-2025.10-Export: exakte Collection-/Mode-IDs, kein Node; nur Farben und einheitenlose Zahlen. Ausgabeordner vorher anlegen; bei Diagnosen schlägt der gesamte Export fehl, die Ausgabedatei bleibt unverändert. Eine Library-Collection wird aus den in der Datei zwischengespeicherten Kopien exportiert (libraryCopy: true). Ein Alias in eine andere Collection exportiert deren Wert, festgehalten in aliasOf; hat sie mehrere Modes, --alias-mode COLLECTION=MODE angeben.
bundle <file> <node> <out.zip> [--states]	Ein Design-Bundle für einen Frame; gibt {nodeId, path, warnings} aus
bundle <file> --frames <list> --out-dir <dir> [--jobs N] [--states], --frames - (stdin)	Viele Bundles aus einem Decode, parallel
verify <bundle> [--fonts <dir>]	Prüft ein Bundle (.zip oder entpacktes Verzeichnis) gegen sein Manifest: verifizierte, fehlende und geänderte Dateien, fehlende Assets, die im Projekt zu bestätigenden Fonts und findings: jede fehlende, nicht unterstützte oder unverifizierte Handoff-Eingabe mit Nodes, Belegen und nächstem Schritt; ein Font mit Datei auf diesem Rechner oder in --fonts <dir> (Projektordner, liefert zusätzlich ein @font-face) ist local_file, kein Beleg, dass der Browser ihn lädt
export <file> <node> <out> [--bounds layout] [--scale N] [--quality 1-100] [--max-kb N] [--max-size N] [--match-dir DIR] [--hide ID[,ID]]	SVG, PNG, JPG, WebP oder AVIF; PNGs bis 4.194.304 Pixel werden automatisch verlustfrei optimiert, ohne die dekodierten RGBA-Werte zu ändern; nur kleinere Ergebnisse ersetzen die ursprünglichen kodierten Bytes, größere PNGs behalten die reguläre Kodierung; --max-kb senkt die verlustbehaftete Qualität, bis es passt (PNG schlägt bei weiterer Überschreitung fehl, ohne verlustbehafteten Fallback); --bounds layout exportiert die Layout-Box statt der Render-Grenzen; --match-dir DIR (nur SVG, mit Unterordnern) listet die SVGs dort, die dieselben Umrisse zeichnen (matches), und bis zu 10 ähnliche Formen mit Score (similar); --hide ID[,ID] zeichnet diese Ebenen im Node als ausgeblendet über derselben Fläche, sodass ein Vergleich mit dem normalen Export zeigt, wo diese Ebene, wie figlens sie zeichnet, das Ergebnis ändert (kein Unterschied beweist nicht, dass das übersprungene Rendering unschädlich ist)
export <file> --frames <list> --out-dir <dir> [--format F] [--scale N] ..., --frames - (stdin)	Ein Decode, viele Exporte (Standard png): schreibt <dir>/<nodeId>.<format>, eine JSON-Zeile pro ID, die export-Ausgabe mit ihrer nodeId oder {nodeId, error}
export <file> --batch <items.json>, --batch - (stdin)	Ein Decode, viele Exporte mit je eigenen Optionen: ein JSON-Array aus 1-64 {node, out, bounds?, scale?, quality?, maxKb?, maxSize?, hide?} (MCP export_batch). Gibt ein Manifest {count, failed, items} aus: je Eintrag die export-Ausgabe oder {error} (die übrigen werden trotzdem exportiert); ein fehlerhafter Eintrag oder ein doppeltes out scheitert vor jedem Schreiben
preview <file> [node] [--out preview.html] [--port N] [--bind IP]	Lokaler Viewer, der das Design nie schreibt; semantische/hybride Suche nach Enable index; --out schreibt einen eigenständigen Offline-Snapshot; Ergebnisse und kopierter Context nennen die Seite und, live, den Dateipfad, den Snapshot des geladenen Source und die lokale Revision (offline unbekannt; der Pfad wird nie eingebettet); der Context enthält zudem die Coverage des Referenz-Scopes, complete: null wenn ungeprüft. Visual/Hybrid nimmt ein Referenz-PNG oder einen ausgewählten Layer mit Pixelzuschnitt an. Visuelle Indexierung wird ausdrücklich aktiviert; Suchbilder werden nicht gespeichert.
compare <file> <nodes.json> <node>	Diff gegen einen REST-Export desselben Frames
compare-image <file> <node> <screenshot.png>	Vergleicht einen Screenshot der gebauten Oberfläche mit dem in seinem Maßstab gerenderten Node (--scale, --limit, --out diff.png, --full-page für eine ganzseitige Aufnahme, die kürzer als der Frame ist; MCP compare_image). Gibt mismatch, nonTextMismatch und die größten abweichenden Bereiche in Node-Pixeln aus, je mit den tiefsten Ebenen darunter; text: true markiert Bereiche über Text (oft Schrift-Fallback; jeden prüfen)
node <file> <node>	Ein roher .fig-Node
index prepare|refresh|rebuild|clear|status|add|remove|relocate|reset|track|untrack|embed|visual	Lokaler Workspace im figlens-Statusverzeichnis des Benutzers oder unter einem --storage DIR, das sich der Workspace danach merkt. prepare <file> --scope NODE baut den Suchindex dieses Bereichs einmal; danach antwortet search --file <file> (oder --workspace DIR) ohne erneutes Parsen, über alle Quellen des Workspaces gerankt. refresh baut geänderte Dateien neu, rebuild alle oder eine --source/--scope, clear entfernt ungenutzte Indizes; der bisherige Index bleibt nutzbar, bis ein neuer fertig ist. reset entfernt nur die Workspace-Datenbank, nie Designs, Exporte oder den gemerkten Ort. track --scope NODE zeichnet die Änderungen dieses Scopes ab einem Baseline-Build auf; untrack beendet das und behält den Verlauf. embed bettet veröffentlichte Bereiche mit dem konfigurierten Modell ein (CPU und Speicher); nur ausführen, wenn Sie semantische Workspace-Suche wollen. visual --scope NODE rendert die Bildschirme und Komponenten dieses veröffentlichten Bereichs für die Bildsuche und bettet sie mit einem konfigurierten Bildprofil ein; nur ausführen, wenn Sie visuelle Workspace-Suche wollen.
jobs status|cancel <jobId>	Status eines Index-Builds anzeigen oder ihn abbrechen; cancel kehrt erst zurück, wenn der Build gestoppt ist
changes --file <file>|--id ID|--workspace DIR [--source ID] [--scope NODE] [--consumer NAME|--subscription ID|--cursor C] [--revision R] [--limit N]	Aufgezeichnete Änderungen verfolgter Scopes, älteste zuerst: eine Revision pro veröffentlichtem Build (baseline oder changes) mit Abdeckung und Zählungen pro Änderungsart und Facette; jede changes-Revision hat eine impact-Zusammenfassung der Layer, die ihre Änderungen erreichen (null vor Schema 7); --revision blättert die geänderten Nodes dieser Revision, dann die von impact gelisteten Layer (entry sagt, welche); tracking zeigt, wann ein Scope index refresh braucht, damit eine Änderung aufgezeichnet wird. Nur lesend
watch ack --file <file>|--id ID|--workspace DIR --consumer NAME|--subscription ID --cursor C [--source ID] [--scope NODE]	Den Checkpoint eines Consumers auf den nextCursor der letzten mit denselben Filtern verarbeiteten changes-Seite setzen; Wiederholen ist sicher, und er bewegt sich nur vorwärts, außer dass ein aktueller Recovery-Cursor einen Checkpoint hinter einer Löschung zurücksetzt, damit die behaltenen Revisionen erneut gelesen werden; ein Cursor von vor einer Löschung durch Retention, die er nicht passiert hat, ist event_gap und schreibt nichts
watch run --file <file>|--id ID|--workspace DIR --scope NODE [--source ID] [--request-id R]	Hält im Vordergrund einen Lease auf einen getrackten Scope: Der gemeinsame Runner des Workspace aktualisiert ihn bei jedem Speichern (Abfrage alle 250 ms, Inhaltsprüfung alle 60 s), sodass changes neue Revisionen ohne index refresh zeigt. Gibt den Lease aus, dann eine Endzeile, wenn stdin schließt, bei Ctrl-C oder SIGTERM oder wenn der Scope nicht mehr getrackt wird. MCP watch start und stop halten Leases, solange der Server läuft; ein nicht erneuerter Lease endet nach 30 s, und der Runner beendet sich nach dem letzten
watch status --file <file>|--id ID|--workspace DIR	Die Leases des Workspace (active, unauthorized, untracked, expired, ended) und sein Runner (running, stopping, stopped, unknown, mit Platzierung); schreibt nie
watch subscribe --file <file>|--id ID|--workspace DIR --consumer NAME --source ID [--scope NODE] [--node ID] [--owner NAME]	Einer Quelle, einem Scope oder genau einer Ebene (--node) ab ihrer neuesten Revision mit eigenem Checkpoint folgen, gelesen mit changes --subscription und bestätigt mit watch ack --subscription; eine fehlende oder mehrdeutige Ebene ist target_missing oder identity_uncertain, nie eine gleichnamige; --owner macht sie für diese Aufgabe temporär
watch subscribe --file <file>|--id ID|--workspace DIR --consumer NAME --source ID --query TEXT [--type T[,T]] [--scope NODE]	Eine Suche über den Scope einer Quelle speichern: ihre Top 50 werden sofort ausgewertet; changes --subscription liest die gespeicherten Auswertungen und berechnet keine
watch subscribe --file <file>|--id ID|--workspace DIR --consumer NAME --sources visible|ID[,ID] --query TEXT|--library KIND --key KEY [--namespace NS] [--definition-source ID --definition-snapshot SNAP --definition-node NODE]	Speichert eine Suche oder die Verwendungen eines Bibliothekselements mit ihrem definitionMatch über eine feste Menge von höchstens 10 Quellen (visible wird jetzt aufgelöst; spätere Quellen kommen nie hinzu): delta.changedSourceIds nennt Quellen mit neuen Bytes, corpus_changed eine Änderung der Menge, coverage.transitive ist not_followed und delta.notFollowedSourceIds nennt geänderte Quellen ohne Verwendung, deren Abhängige nicht erneut geprüft wurden; das Entfernen eines Mitglieds deaktiviert sie (unsubscribe, dann erneut subscribe)
watch evaluate --file <file>|--id ID|--workspace DIR --subscription ID	Die Auswertung einer Query-Subscription für den aktuellen Index des Scopes speichern, sofern noch nicht ausgewertet; ein Watch auf dem Scope tut das nach jeder Veröffentlichung
watch list --file <file>|--id ID|--workspace DIR [--consumer NAME] [--after ID] [--subscription ID]	Die sichtbaren Subscriptions und ihren Zustand seitenweise auflisten; --subscription liest nur diese eine (leer, wenn nicht sichtbar)
watch unsubscribe --file <file>|--id ID|--workspace DIR --subscription ID|--consumer C --owner NAME	Eine Subscription samt Checkpoint entfernen, oder die temporären eines Owners; Tracking und Verlauf bleiben
watch forget --file <file>|--id ID|--workspace DIR --consumer NAME [--source ID] [--scope NODE]	Die rohen Checkpoints eines Consumers entfernen; ein Consumer hält höchstens 64 Subscriptions und Checkpoints, ein Workspace 4096, und nichts wird automatisch verdrängt
mcp	Lokaler MCP-Server über stdio
update	Ersetzt das Binary durch das neueste Release

Für zugehörige Komponentenvarianten inspect --states oder bundle --states verwenden (MCP: states: true, standardmäßig false; keine Konfigurationsänderung). Die Nachweise behalten Quellen-, Unbekannt- und Kürzungsmarkierungen. Bundles ergänzen design/states.json und eine Zusammenfassung in context.md. Umfang und Grenzen stehen unter Zustandsnachweise.

Zwei Varianten desselben Component-Sets mit inspect <file> <variantA> --compare-variant <variantB> vergleichen (MCP compareVariant). variantComparison meldet Unterschiede gespeicherter Felder und Wertemengen samt Quell-IDs und unbekannten Werten, Kindknoten werden nach eindeutigem Namen, dann nach Hauptkomponente, dann nach Stapelreihenfolge in gleich großen Namensgruppen gepaart (pairedNodes mit Änderungen je Paar; pairedBy prüfen, order ist der schwächste Beleg; der Rest bleibt ungepaart); gebundene Variablen werden benannt. Siehe Vergleichsgrenzen.

Um zwei beliebige Knoten derselben Datei zu vergleichen (leerer und gefüllter Screen, Mobile- und Desktop-Breakpoint, zwei Screens mit gemeinsamem Header), verwende inspect <file> <nodeA> --compare <nodeB> (MCP compare). comparison hat dieselbe Form plus rootDelta (Größe und Position relativ zum Elternknoten); Kinder werden nach eindeutigem Namen, dann nach Hauptkomponente, dann nach Stapelreihenfolge in gleich großen Namensgruppen gepaart (pairedBy nennt das Verfahren), der Rest bleibt ungepaart mit reason: ambiguous-name; Instanzen werden nicht expandiert, und ein Knoten lässt sich nicht mit seinem Vorfahren vergleichen. --compare-variant verlangt weiterhin dasselbe Component Set.

Ein Node-Argument akzeptiert 12:345, 12-345 oder eine Figma-URL mit ?node-id=. <file> kann auch gs://bucket/object sein, heruntergeladen mit deinem gcloud-Login und im Cache abgelegt. Der GCS-Snapshot-Leitfaden beschreibt die Übergabe über ein festes Objekt, nötige Zugriffsrechte und Grenzen der Aktualisierung. Jeder CLI-Aufruf decodiert die Datei; MCP verwendet nur die zuletzt gelesene, unveränderte lokale Datei erneut. Remote-Aufrufe parsen erneut. Führe figlens --help oder figlens inspect --help (auch -h) für die vollständige CLI-Hilfe aus. index add gs://bucket/object registriert eine fixierte Kopie dieser Generation und meldet remote {uri, generation}; nur add startet gcloud.

inspect enthält gespeicherte Textgrößenanpassung, Kürzung, maximale Zeilenzahl und Textdekoration. Ein Elternknoten ohne Auto-Layout trägt childSpacing: "derived": Abstände zwischen seinen Kindern sind Koordinatendifferenzen, keine Auto-Layout-Regel; constraints können sie dennoch fixieren. handoffDiagnostics meldet gespeicherte, aber nicht ausgegebene Semantik mit Anzahl, Beispielen und Abdeckungsgrenzen. Ausgaben schützen die Quelle und ersetzen das Ziel erst nach vollständigem Schreiben. MCP begrenzt Anfragezeilen auf 1 MiB und vollständige Antworten auf 8 MiB; Überschreitungen ergeben einen ausdrücklichen Fehler. Vollständiges JSON bleibt über die CLI verfügbar.