Référence de la CLI

Commande	Sortie
tree <file> [node] [--depth N] [--json]	Ids, types REST (comme nodes) et noms des nodes ; texte indenté, ou JSON imbriqué avec la taille de chaque node, son masquage et son mode d'auto layout, plus firstText (premier texte visible) sur les nodes d'une page ou d'une section
tree <file> [node] --top-frames [--json]	Uniquement les écrans, un par ligne, prêts pour --frames - : frames, composants, ensembles de composants et instances d'une page ou de ses sections (groupes et pages internes ignorés) ; --json ajoute les ids de page et de section et le premier texte visible de chaque écran (firstText), qui distingue les libellés du canevas des écrans
find <file> <query> [--type TYPE] [--node ID] [--limit N]	Recherche insensible à la casse dans les noms de calques et le texte ; chemins, tailles et aperçus. 20 résultats par défaut (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]	Recherche classée dans les noms de calques et le texte complet, avec overrides d’instance, propriétés texte/booléennes et swaps appliqués ; références exactes de nœuds (y compris les ids de sous-calques I…;… pour inspect), raisons de correspondance, plages UTF-16, couverture et pages par curseur. 20 par défaut (1-200) ; calques masqués et pages internes exigent leur flag. Avec --file/--workspace/--id au lieu de <file>, il lit l'index préparé du workspace (voir index) --mode semantic|hybrid exige un modèle configuré : voir Recherche sémantique optionnelle.
models list|status|configure <profile> --model DIR [--runtime FILE]|remove <profile>	Modèle de texte local pour la recherche sémantique (bge-m3, expérimental) et modèle d’image pour la recherche par image (siglip-base, expérimental) ; configure vérifie les fichiers que vous avez téléchargés et ne télécharge jamais ; remove les garde. Voir Recherche sémantique optionnelle.
usages <file> <node|resource> [--scope ID] [--relation R[,R]] [--out] [--snapshot S] [--include-hidden] [--limit N] [--cursor C]	Relations exactes d'un calque ou d'une ressource (VariableID:…, StyleKey:…, image:…) dans une portée enregistrée, instances imbriquées et swaps compris : où un composant, un set, une variable, un style ou une image est utilisé (par défaut), ou ce que désigne un calque (--out). Chaque résultat garde sa référence exacte, sa relation, son état (resolved, missing, unresolved, …), sa base et sa preuve ; un nom ne vaut jamais identité. Pas de total : la couverture dit complète ou partielle. 50 par défaut (1-200). Avec --file/--workspace/--id au lieu de <file>, lit l'index préparé de --scope du workspace. Avec --out, un usage d'une copie de bibliothèque en cache donne aussi sa 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]	Calques qui utilisent un composant, un style ou une variable de bibliothèque (kind), tel que la copie en cache de chaque fichier l'enregistre, dans le --scope préparé de toutes les sources (--source limite à une). La définition reste unresolved, sauf si les trois options --definition-* la sélectionnent par référence exacte (selected, keyEvidence: unverified) ; la couverture donne l'état de chaque source et pourquoi elle est partielle. Prenez-la dans le champ library de usages --out sur un calque qui l'utilise.
diff <old.fig> <new.fig> [--node ID] [--limit N] [--cursor C] [--json]	Ce qui a changé entre deux révisions enregistrées : une ligne par frame de premier niveau modifié, avec des comptes par facette (texte, layout, apparence, propriétés, structure, liaisons) ; --json ajoute les valeurs de champ anciennes/nouvelles et les changements d'edges. Les calques ne se correspondent que par id et type exacts ; un frame de même nom ou de même position n'est qu'un possible match étiqueté, et un côté arrêté avant la fin, ou un calque dont la seule différence est un champ illisible, signale unknown, jamais supprimé ni modifié. Pages de 100 changements (1-500) Un côté arrêté à une limite affiche stopped early au lieu de no changes ; restreignez avec --node.
inspect <file> <node> [--depth N] [--images] [--states] [--compare-variant ID] [--compare ID] [--flat] [--full-text] [--colors]	Résumé compact de la mise en page/du texte étendus, 200 nodes au plus. --images ajoute les dimensions des bitmaps et les emprises de recadrage. --flat affiche plutôt une ligne par node : position relative au node, taille, texte, police, remplissage, contour, rayon, auto-layout, alignement, taille fixed/fill, ombres et flous --full-text renvoie chaque texte en entier (jusqu'à 10 000 caractères) ; --colors ajoute les remplissages unis visibles (hex, opacité, variable liée), aussi avec --flat ; ni dégradés, ni images, ni contours.
nodes <file> <node>	L'objet par nœud d'une réponse REST nodes (document, components, componentSets, styles) : instances étendues et overrides, auto-layout, styles de texte, fills, effets, variables liées, propriétés de composants, render bounds
nodes <file> --frames <list>, --frames - (stdin), --ids <node>...	Un seul décodage, plusieurs nœuds : une ligne JSON par id listé, la sortie de nodes avec son nodeId, ou {nodeId, error}
variables <file> [node] variables <file.fig> --format dtcg --collection ID --mode ID --out FILE	Par défaut : variables liées/locales au format REST inchangé. Export DTCG 2025.10 : IDs exacts de collection et de mode, sans nœud ; couleurs et nombres sans unité uniquement. Créez d’abord le dossier de sortie ; tout diagnostic fait échouer l’export entier sans modifier le fichier de sortie. Une collection de bibliothèque est exportée depuis les copies mises en cache dans le fichier (libraryCopy: true). Un alias vers une autre collection exporte la valeur de celle-ci, notée dans aliasOf ; si elle a plusieurs modes, indiquez --alias-mode COLLECTION=MODE.
bundle <file> <node> <out.zip> [--states]	Un bundle de design pour une frame ; affiche {nodeId, path, warnings}
bundle <file> --frames <list> --out-dir <dir> [--jobs N] [--states], --frames - (stdin)	Plusieurs bundles depuis un seul décodage, en parallèle
verify <bundle> [--fonts <dir>]	Vérifie un bundle (.zip ou dossier extrait) par rapport à son manifeste : fichiers vérifiés, manquants et modifiés, assets manquants, polices à confirmer dans le projet, et findings : chaque entrée de handoff manquante, non prise en charge ou non vérifiée, avec ses nœuds, preuves et prochaine action; une police dont le fichier est sur cette machine ou dans --fonts <dir> (dossier du projet, qui fournit aussi un @font-face) est local_file, sans preuve que le navigateur la charge
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 ou AVIF ; les PNG jusqu’à 4 194 304 pixels sont automatiquement optimisés sans perte, sans modifier les valeurs RGBA décodées ; les octets encodés d’origine sont conservés si le résultat n’est pas plus petit, et les PNG plus grands gardent l’encodage habituel ; --max-kb abaisse la qualité avec perte jusqu’à tenir dans la limite (PNG échoue s’il la dépasse encore, sans solution de repli avec perte) ; --bounds layout exporte la boîte de layout au lieu des limites de rendu ; --match-dir DIR (SVG uniquement, sous-dossiers compris) liste les SVG qui dessinent les mêmes contours (matches) et jusqu’à 10 formes proches avec un score (similar) ; --hide ID[,ID] dessine ces calques du nœud comme masqués sur la même zone, si bien que la comparaison avec l’export normal montre où ce calque, tel que figlens le dessine, modifie le résultat (l’absence de différence ne prouve pas que le rendu ignoré est sans effet)
export <file> --frames <list> --out-dir <dir> [--format F] [--scale N] ..., --frames - (stdin)	Un décodage, plusieurs exports (png par défaut) : écrit <dir>/<nodeId>.<format>, une ligne JSON par id, la sortie d’export avec son nodeId, ou {nodeId, error}
export <file> --batch <items.json>, --batch - (stdin)	Un décodage, plusieurs exports, chacun avec ses options : un tableau JSON de 1 à 64 {node, out, bounds?, scale?, quality?, maxKb?, maxSize?, hide?} (MCP export_batch). Affiche un manifeste {count, failed, items} : par élément, la sortie d'export ou {error} (les autres sont tout de même exportés) ; un élément mal formé ou un out répété échoue avant toute écriture
preview <file> [node] [--out preview.html] [--port N] [--bind IP]	Viewer local qui n’écrit jamais le design ; recherche sémantique/hybride après Enable index ; --out écrit un snapshot hors ligne autonome ; les résultats et le context copié indiquent la page et, en direct, le chemin du fichier, le snapshot du source chargé et la revision locale (inconnus hors ligne, où le chemin n'est jamais intégré) ; le context porte aussi la coverage du scope de référence, complete: null si non vérifiée. Visual/Hybrid accepte un PNG de référence ou un calque sélectionné avec recadrage en pixels. Activez explicitement l’index visuel ; les images de recherche ne sont pas conservées.
compare <file> <nodes.json> <node>	Diff par rapport à un export REST de la même frame
compare-image <file> <node> <screenshot.png>	Compare une capture de l’écran construit au node rendu à son échelle (--scale, --limit, --out diff.png, --full-page pour une capture pleine page plus courte que la frame ; MCP compare_image). Affiche mismatch, nonTextMismatch et les plus grandes régions différentes en pixels du node, chacune avec les calques les plus profonds dessous ; text: true signale une région sur du texte (souvent une police de substitution ; vérifiez chacune)
node <file> <node>	Un node .fig brut
index prepare|refresh|rebuild|clear|status|add|remove|relocate|reset|track|untrack|embed|visual	Workspace local dans le répertoire d'état figlens de l'utilisateur, ou sous un --storage DIR que le workspace mémorise ensuite. prepare <file> --scope NODE construit une fois l'index de recherche de cette portée ; ensuite search --file <file> (ou --workspace DIR) répond sans réanalyser, avec un classement commun aux sources du workspace. refresh reconstruit les fichiers modifiés, rebuild tous ou une --source/--scope, clear supprime les index inutilisés ; l'index précédent sert jusqu'à ce que le nouveau soit prêt. reset supprime uniquement la base de données du workspace, jamais les designs, les exports ni l'emplacement mémorisé. track --scope NODE enregistre les modifications de ce scope à partir d'un build baseline ; untrack l'arrête en gardant l'historique. embed encode les portées publiées avec le modèle configuré (CPU et mémoire) ; ne le lancez que pour une recherche sémantique de workspace. visual --scope NODE rend les écrans et composants de cette portée publiée pour la recherche par image et les encode si un profil de vision est configuré ; ne le lancez que pour une recherche visuelle de workspace.
jobs status|cancel <jobId>	Afficher ou annuler une construction d'index ; cancel rend la main une fois la construction arrêtée
changes --file <file>|--id ID|--workspace DIR [--source ID] [--scope NODE] [--consumer NAME|--subscription ID|--cursor C] [--revision R] [--limit N]	Modifications enregistrées des scopes suivis, de la plus ancienne à la plus récente : une révision par build publié (baseline ou changes) avec couverture et comptes par type de changement et facette ; chaque révision changes a un résumé impact des calques que ses changements atteignent (null avant le schéma 7) ; --revision pagine les nodes modifiés de cette révision, puis les calques que liste son impact (entry indique lequel) ; tracking indique quand un scope a besoin de index refresh pour enregistrer un changement. Lecture seule
watch ack --file <file>|--id ID|--workspace DIR --consumer NAME|--subscription ID --cursor C [--source ID] [--scope NODE]	Avance le checkpoint d'un consommateur jusqu'au nextCursor de la dernière page changes traitée avec les mêmes filtres ; le répéter est sans risque et il n'avance que vers l'avant, sauf qu'un curseur de reprise actuel ramène en arrière un checkpoint resté derrière une suppression pour relire les révisions conservées ; un curseur émis avant que la rétention supprime des révisions qu'il n'avait pas dépassées donne event_gap et n'écrit rien
watch run --file <file>|--id ID|--workspace DIR --scope NODE [--source ID] [--request-id R]	Tient au premier plan un lease sur un scope suivi : le runner partagé du workspace le rafraîchit à chaque enregistrement (interrogation toutes les 250 ms, vérification du contenu toutes les 60 s), donc changes montre les nouvelles révisions sans index refresh. Affiche le lease, puis une ligne de fin quand stdin se ferme, sur Ctrl-C ou SIGTERM, ou quand le scope n'est plus suivi. MCP watch start et stop tiennent des leases tant que le serveur tourne ; un lease non renouvelé prend fin après 30 s et le runner se termine après le dernier
watch status --file <file>|--id ID|--workspace DIR	Les leases du workspace (active, unauthorized, untracked, expired, ended) et son runner (running, stopping, stopped, unknown, avec son placement) ; n'écrit jamais
watch subscribe --file <file>|--id ID|--workspace DIR --consumer NAME --source ID [--scope NODE] [--node ID] [--owner NAME]	Suit une source, un scope ou un calque exact (--node) depuis sa révision la plus récente avec son propre checkpoint, lu par changes --subscription et acquitté par watch ack --subscription ; un calque absent ou ambigu donne target_missing ou identity_uncertain, jamais un calque du même nom ; --owner la rend temporaire pour cette tâche
watch subscribe --file <file>|--id ID|--workspace DIR --consumer NAME --source ID --query TEXT [--type T[,T]] [--scope NODE]	Enregistre une recherche sur le scope d'une source : ses 50 premiers sont évalués tout de suite ; changes --subscription lit les évaluations stockées et n'en calcule jamais
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]	Enregistre une recherche, ou les utilisations d'un élément de bibliothèque avec leur definitionMatch, sur un ensemble fixe d'au plus 10 sources (visible est résolu maintenant ; les sources ajoutées ensuite n'y entrent jamais) : delta.changedSourceIds nomme les sources aux octets nouveaux, corpus_changed un changement de l'ensemble, coverage.transitive vaut not_followed et delta.notFollowedSourceIds nomme les sources modifiées sans utilisation, dont les dépendants n'ont pas été revérifiés ; retirer un membre la désactive (unsubscribe, puis subscribe à nouveau)
watch evaluate --file <file>|--id ID|--workspace DIR --subscription ID	Stocke l'évaluation d'un abonnement de requête sur l'index actuel du scope, sauf s'il est déjà évalué ; un watch sur le scope le fait après chaque publication
watch list --file <file>|--id ID|--workspace DIR [--consumer NAME] [--after ID] [--subscription ID]	Liste les abonnements visibles et leur état, une page à la fois ; --subscription ne lit que celui-ci (vide s'il n'est pas visible)
watch unsubscribe --file <file>|--id ID|--workspace DIR --subscription ID|--consumer C --owner NAME	Supprime un abonnement et son checkpoint, ou les abonnements temporaires d'un owner ; le suivi et l'historique restent
watch forget --file <file>|--id ID|--workspace DIR --consumer NAME [--source ID] [--scope NODE]	Supprime les checkpoints bruts d'un consumer ; un consumer garde au plus 64 abonnements et checkpoints, un workspace 4096, et rien n'est évincé automatiquement
mcp	Serveur MCP local via stdio
update	Remplace le binaire par la dernière release

Pour les variantes de composants liées, utilisez inspect --states ou bundle --states (MCP : states: true, false par défaut ; aucun changement de configuration). Les preuves conservent les sources et les marqueurs de données inconnues ou tronquées. Les bundles ajoutent design/states.json et un résumé dans context.md. Voir la preuve des états pour le périmètre et les limites.

Comparez deux variantes du même component set avec inspect <file> <variantA> --compare-variant <variantB> (MCP compareVariant). variantComparison décrit les différences de champs et ensembles de valeurs stockés avec sources et inconnues, Les enfants sont appariés par nom unique, puis par composant principal, puis par ordre d'empilement dans des groupes de même nom et de même taille (pairedNodes, avec les changements par paire ; vérifiez pairedBy, order est l'indice le plus faible ; le reste n'est pas apparié), et les variables liées sont nommées. Voir les limites.

Pour comparer deux nœuds quelconques d'un même fichier (écran vide et rempli, breakpoints mobile et bureau, deux écrans partageant un en-tête), utilisez inspect <file> <nodeA> --compare <nodeB> (MCP compare). comparison a la même forme, plus rootDelta (taille et position relative au parent) ; les enfants sont appariés par nom unique, puis par composant principal, puis par ordre d'empilement dans des groupes de même nom et de même taille (pairedBy l'indique), le reste demeure non apparié avec reason: ambiguous-name, les instances ne sont pas développées et un nœud ne se compare pas à son propre ancêtre. --compare-variant exige toujours le même component set.

Un argument node accepte 12:345, 12-345 ou une URL Figma avec ?node-id=. <file> peut aussi être gs://bucket/object, téléchargé avec votre connexion gcloud et mis en cache. Consultez le guide des snapshots GCS pour la transmission via un objet fixe, les droits requis et les limites d’actualisation. Chaque appel de la CLI décode le fichier ; MCP ne réutilise que le dernier fichier local inchangé. Les appels distants relancent l’analyse. Lancez figlens --help ou figlens inspect --help (-h aussi) pour l’aide complète de la CLI. index add gs://bucket/object enregistre une copie épinglée de cette génération et renvoie remote {uri, generation} ; seul add lance gcloud.

inspect inclut le redimensionnement du texte, la troncature, le nombre maximal de lignes et les décorations enregistrés. Un parent sans auto-layout porte childSpacing: "derived" : les écarts entre ses enfants sont des différences de coordonnées, pas une règle d'auto-layout ; constraints peut encore les fixer. handoffDiagnostics signale les données sémantiques enregistrées mais non émises, avec des comptes, des exemples et des limites de couverture. Les sorties protègent la source et remplacent la destination après une écriture complète. MCP limite les lignes de requête à 1 MiB et les réponses complètes à 8 MiB ; un dépassement renvoie une erreur explicite. Le JSON complet reste disponible via la CLI.