Referencia de la CLI

Comando	Salida
tree <file> [node] [--depth N] [--json]	Ids, tipos REST (como en nodes) y nombres de nodos; texto con sangría, o JSON anidado con el tamaño de cada nodo, si está oculto y el modo de auto layout, más firstText (primer texto visible) en los nodos de una página o sección
tree <file> [node] --top-frames [--json]	Solo las pantallas, una por línea, listas para --frames -: frames, componentes, conjuntos de componentes e instancias de una página o de sus secciones (se omiten grupos y páginas internas); --json añade los ids de página y sección y el primer texto visible de cada pantalla (firstText), que distingue las etiquetas del lienzo de las pantallas
find <file> <query> [--type TYPE] [--node ID] [--limit N]	Búsqueda sin distinguir mayúsculas en nombres de capas y texto; rutas, tamaños y vistas previas. 20 resultados por defecto (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]	Búsqueda clasificada en nombres de capas y texto completo con overrides de instancias, propiedades de texto/booleanas y swaps aplicados; referencias exactas de nodos (incluidos ids de subcapas I…;… para inspect), motivos de coincidencia, rangos UTF-16, cobertura y páginas con cursor. 20 por defecto (1-200); las capas ocultas y las páginas internas necesitan su flag. Con --file/--workspace/--id en lugar de <file> lee el índice preparado del workspace (ver index) --mode semantic|hybrid necesita un modelo configurado: consulta Búsqueda semántica opcional.
models list|status|configure <profile> --model DIR [--runtime FILE]|remove <profile>	Modelo de texto local para la búsqueda semántica (bge-m3, experimental) y modelo de imagen para la búsqueda por imagen (siglip-base, experimental); configure comprueba los archivos que descargaste y nunca descarga; remove los conserva. Consulta Búsqueda semántica opcional.
usages <file> <node|resource> [--scope ID] [--relation R[,R]] [--out] [--snapshot S] [--include-hidden] [--limit N] [--cursor C]	Relaciones exactas de una capa o recurso (VariableID:…, StyleKey:…, image:…) en un ámbito guardado, con instancias anidadas y swaps: dónde se usa un componente, set, variable, estilo o imagen (por defecto) o a qué apunta una capa (--out). Cada resultado conserva su referencia exacta, relación, estado (resolved, missing, unresolved, …), base y evidencia; un nombre nunca cuenta como identidad. Sin totales: la cobertura dice completa o parcial. Por defecto 50 (1-200). Con --file/--workspace/--id en lugar de <file> lee el índice preparado de --scope del workspace. Con --out, un uso de una copia en caché de biblioteca también indica su 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]	Capas que usan un componente, estilo o variable de biblioteca (kind), tal como lo registra la copia en caché de cada archivo, en el --scope preparado de todas las fuentes (--source limita a una). La definición queda unresolved salvo que las tres opciones --definition-* la seleccionen por referencia exacta (selected, keyEvidence: unverified); la cobertura indica el estado de cada fuente y por qué es parcial. Tómala del campo library de usages --out sobre una capa que la use.
diff <old.fig> <new.fig> [--node ID] [--limit N] [--cursor C] [--json]	Qué cambió entre dos revisiones guardadas: una línea por cada frame de primer nivel con cambios, con recuentos por faceta (texto, layout, apariencia, propiedades, estructura, vinculaciones); --json añade valores de campo antiguos/nuevos y cambios de edges. Las capas solo coinciden por id y tipo exactos; un frame con el mismo nombre o posición es solo un possible match etiquetado, y un lado que se detuvo antes, o una capa cuya única diferencia es un campo que no se pudo leer, informa unknown, nunca eliminado ni cambiado. Páginas de 100 cambios (1-500) Si un lado se detiene en un límite, imprime stopped early en vez de no changes; acótalo con --node.
inspect <file> <node> [--depth N] [--images] [--states] [--compare-variant ID] [--compare ID] [--flat] [--full-text] [--colors]	Resumen compacto de layout/texto expandido, como máximo 200 nodos. --images añade dimensiones de bitmap y áreas de recorte. --flat imprime en su lugar una línea por nodo: posición relativa al nodo, tamaño, texto, fuente, relleno, trazo, radio, auto-layout, alineación, tamaño fixed/fill, sombras y desenfoques --full-text devuelve cada texto completo (hasta 10 000 caracteres); --colors añade los rellenos sólidos visibles (hex, opacidad, variable enlazada), también con --flat; sin degradados, imágenes ni trazos.
nodes <file> <node>	El objeto por nodo de una respuesta REST de nodes (document, components, componentSets, styles): instancias expandidas y overrides, auto-layout, estilos de texto, fills, efectos, variables enlazadas, propiedades de componentes, render bounds
nodes <file> --frames <list>, --frames - (stdin), --ids <node>...	Una decodificación, muchos nodos: una línea JSON por id listado, la salida de nodes con su nodeId, o {nodeId, error}
variables <file> [node] variables <file.fig> --format dtcg --collection ID --mode ID --out FILE	Por defecto: variables vinculadas/locales en formato REST sin cambios. Exportación DTCG 2025.10: IDs exactos de colección y modo, sin nodo; solo colores y números sin unidad. Crea primero el directorio de salida; cualquier diagnóstico cancela la exportación completa sin modificar el archivo de salida. Una colección de biblioteca se exporta desde las copias guardadas en el archivo (libraryCopy: true). Un alias a otra colección exporta el valor de esa colección, registrado en aliasOf; si tiene varios modos, indica --alias-mode COLLECTION=MODE.
bundle <file> <node> <out.zip> [--states]	Un bundle de diseño para un frame; imprime {nodeId, path, warnings}
bundle <file> --frames <list> --out-dir <dir> [--jobs N] [--states], --frames - (stdin)	Muchos bundles a partir de una sola decodificación, en paralelo
verify <bundle> [--fonts <dir>]	Comprueba un bundle (.zip o su directorio extraído) contra su manifiesto: archivos verificados, ausentes y modificados, assets que faltan, las fuentes que hay que confirmar en el proyecto y findings: cada entrada de handoff ausente, no soportada o no verificada, con sus nodos, evidencia y siguiente acción; una fuente con archivo en este equipo o en --fonts <dir> (carpeta del proyecto, que además da un @font-face) es local_file, sin probar que el navegador la cargue
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 o AVIF; los PNG de hasta 4.194.304 píxeles se optimizan automáticamente sin pérdida, sin cambiar los valores RGBA decodificados; se conservan los bytes codificados originales si no se reduce el tamaño, y los PNG mayores usan la codificación habitual; --max-kb reduce la calidad con pérdida hasta que quepa (PNG falla si aún supera el límite, sin alternativa con pérdida); --bounds layout exporta la caja de layout en lugar de los límites de render; --match-dir DIR (solo SVG, con subcarpetas) lista los SVG que dibujan los mismos contornos (matches) y hasta 10 formas similares con puntuación (similar); --hide ID[,ID] dibuja esas capas del nodo como ocultas sobre la misma área, así que compararlo con la exportación normal muestra dónde esa capa, tal como la dibuja figlens, cambia el resultado (que no haya diferencia no prueba que lo omitido sea inocuo)
export <file> --frames <list> --out-dir <dir> [--format F] [--scale N] ..., --frames - (stdin)	Una decodificación, muchas exportaciones (por defecto png): escribe <dir>/<nodeId>.<format>, una línea JSON por id, la salida de export con su nodeId, o {nodeId, error}
export <file> --batch <items.json>, --batch - (stdin)	Una decodificación, muchas exportaciones, cada una con sus opciones: un array JSON de 1-64 {node, out, bounds?, scale?, quality?, maxKb?, maxSize?, hide?} (MCP export_batch). Imprime un manifiesto {count, failed, items}: por elemento, la salida de export o {error} (los demás se exportan igualmente); un elemento mal formado o un out repetido falla antes de escribir nada
preview <file> [node] [--out preview.html] [--port N] [--bind IP]	Viewer local que nunca escribe el diseño; búsqueda semántica/híbrida tras Enable index; --out escribe un snapshot offline independiente; los resultados y el context copiado indican la página y, en vivo, la ruta del archivo, el snapshot del source cargado y la revision local (desconocidos offline, donde la ruta nunca se incrusta); el context incluye también la coverage del scope de referencia, complete: null si no se comprobó. Visual/Hybrid acepta un PNG de referencia o una capa seleccionada con recorte en píxeles. Activa el índice visual explícitamente; las imágenes de consulta no se guardan.
compare <file> <nodes.json> <node>	Diff contra una exportación REST del mismo frame
compare-image <file> <node> <screenshot.png>	Compara una captura de la pantalla construida con el nodo renderizado a su escala (--scale, --limit, --out diff.png, --full-page para una captura de página completa más corta que el frame; MCP compare_image). Imprime mismatch, nonTextMismatch y las mayores regiones distintas en píxeles del nodo, cada una con las capas más profundas debajo; text: true indica regiones sobre texto (a menudo fuente sustituta; revisa cada una)
node <file> <node>	Un nodo .fig sin procesar
index prepare|refresh|rebuild|clear|status|add|remove|relocate|reset|track|untrack|embed|visual	Workspace local en el directorio de estado de figlens del usuario, o bajo un --storage DIR que el workspace recuerda después. prepare <file> --scope NODE construye una vez el índice de búsqueda de ese ámbito; luego search --file <file> (o --workspace DIR) responde sin volver a analizar, con ranking conjunto de las fuentes del workspace. refresh reconstruye los archivos cambiados, rebuild todos o una --source/--scope, clear elimina índices sin uso; el índice anterior sigue sirviendo hasta que el nuevo está listo. reset elimina solo la base de datos del workspace, nunca diseños, exportaciones ni la ubicación recordada. track --scope NODE registra los cambios de ese scope desde un build baseline; untrack lo detiene y conserva el historial. embed incrusta los ámbitos publicados con el modelo configurado (CPU y memoria); ejecútalo solo si quieres búsqueda semántica en el workspace. visual --scope NODE renderiza las pantallas y componentes de ese ámbito publicado para la búsqueda por imagen y los incrusta si hay un perfil de visión configurado; ejecútalo solo si quieres búsqueda visual en el workspace.
jobs status|cancel <jobId>	Ver o cancelar una construcción de índice; cancel vuelve cuando la construcción se detuvo
changes --file <file>|--id ID|--workspace DIR [--source ID] [--scope NODE] [--consumer NAME|--subscription ID|--cursor C] [--revision R] [--limit N]	Cambios registrados de los scopes seguidos, del más antiguo al más reciente: una revisión por build publicado (baseline o changes) con cobertura y recuentos por tipo de cambio y faceta; cada revisión changes tiene un resumen impact de las capas que alcanzan sus cambios (null antes del esquema 7); --revision pagina los nodos cambiados de esa revisión y luego las capas que lista su impacto (entry indica cuál); tracking indica cuándo un scope necesita index refresh para registrar un cambio. Solo lectura
watch ack --file <file>|--id ID|--workspace DIR --consumer NAME|--subscription ID --cursor C [--source ID] [--scope NODE]	Mueve el checkpoint de un consumidor al nextCursor de la última página de changes que procesó con los mismos filtros; repetirlo es seguro y solo avanza, salvo que un cursor de recuperación actual retrocede un checkpoint que quedó tras un borrado para releer las revisiones conservadas; un cursor emitido antes de que la retención borrara revisiones que no había pasado es event_gap y no escribe nada
watch run --file <file>|--id ID|--workspace DIR --scope NODE [--source ID] [--request-id R]	Mantiene en primer plano un lease sobre un scope rastreado: el runner compartido del workspace lo actualiza en cada guardado (sondeo cada 250 ms, verificación de contenido cada 60 s), así changes muestra revisiones nuevas sin index refresh. Imprime el lease y luego una línea final cuando se cierra stdin, con Ctrl-C o SIGTERM, o cuando el scope deja de rastrearse. MCP watch start y stop mantienen leases mientras el servidor se ejecuta; un lease sin renovar termina a los 30 s y el runner sale tras el último
watch status --file <file>|--id ID|--workspace DIR	Los leases del workspace (active, unauthorized, untracked, expired, ended) y su runner (running, stopping, stopped, unknown, con su ubicación); nunca escribe
watch subscribe --file <file>|--id ID|--workspace DIR --consumer NAME --source ID [--scope NODE] [--node ID] [--owner NAME]	Sigue una fuente, un scope o una capa exacta (--node) desde su revisión más reciente con su propio checkpoint, leído con changes --subscription y confirmado con watch ack --subscription; una capa ausente o ambigua es target_missing o identity_uncertain, nunca otra con el mismo nombre; --owner la hace temporal para esa tarea
watch subscribe --file <file>|--id ID|--workspace DIR --consumer NAME --source ID --query TEXT [--type T[,T]] [--scope NODE]	Guarda una búsqueda sobre el scope de una fuente: sus 50 primeros se evalúan ya; changes --subscription lee las evaluaciones guardadas y nunca calcula una
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]	Guarda una búsqueda, o los usos de un elemento de biblioteca con su definitionMatch, sobre un conjunto fijo de hasta 10 fuentes (visible se resuelve ahora; nunca se añaden fuentes posteriores): delta.changedSourceIds nombra las fuentes con bytes nuevos, corpus_changed un cambio del conjunto, coverage.transitive es not_followed y delta.notFollowedSourceIds nombra las fuentes cambiadas sin usos, cuyos dependientes no se revisaron; eliminar un miembro la desactiva (unsubscribe y luego subscribe de nuevo)
watch evaluate --file <file>|--id ID|--workspace DIR --subscription ID	Guarda la evaluación de una suscripción de consulta sobre el índice actual del scope, salvo que ya esté evaluada; un watch sobre el scope lo hace tras cada publicación
watch list --file <file>|--id ID|--workspace DIR [--consumer NAME] [--after ID] [--subscription ID]	Lista las suscripciones visibles y su estado, una página cada vez; --subscription lee solo esa (vacío si no es visible)
watch unsubscribe --file <file>|--id ID|--workspace DIR --subscription ID|--consumer C --owner NAME	Quita una suscripción y su checkpoint, o las temporales de un owner; el tracking y el historial se mantienen
watch forget --file <file>|--id ID|--workspace DIR --consumer NAME [--source ID] [--scope NODE]	Quita los checkpoints sueltos de un consumer; un consumer guarda como máximo 64 suscripciones y checkpoints y un workspace 4096, y nada se desaloja automáticamente
mcp	Servidor MCP local por stdio
update	Reemplaza el binario por la última release

Para variantes de componentes relacionadas, usa inspect --states o bundle --states (MCP: states: true, false por defecto; sin cambiar la configuración). La evidencia conserva marcas de origen, datos desconocidos y truncamiento. Los bundles añaden design/states.json y un resumen en context.md. Consulta el alcance y los límites en evidencia de estados.

Compara dos variantes del mismo component set con inspect <file> <variantA> --compare-variant <variantB> (MCP compareVariant). variantComparison muestra diferencias de campos y conjuntos de valores almacenados, con IDs de origen y datos desconocidos, Los hijos se emparejan por nombre único, luego por componente principal y luego por orden de apilado en grupos del mismo nombre y tamaño (pairedNodes, con cambios por par; revisa pairedBy, order es la evidencia más débil; el resto queda sin emparejar), y las variables enlazadas se nombran. Consulta los límites.

Para comparar dos nodos cualesquiera de un mismo archivo (pantalla vacía y rellena, breakpoints móvil y escritorio, dos pantallas con la misma cabecera), usa inspect <file> <nodeA> --compare <nodeB> (MCP compare). comparison tiene la misma forma más rootDelta (tamaño y posición relativa al padre); los hijos se emparejan por nombre único, luego por componente principal y luego por orden de apilado en grupos del mismo nombre y tamaño (pairedBy indica cuál), el resto queda sin emparejar con reason: ambiguous-name, las instancias no se expanden y un nodo no se puede comparar con su propio ancestro. --compare-variant sigue exigiendo el mismo component set.

Un argumento de nodo acepta 12:345, 12-345 o una URL de Figma con ?node-id=. <file> también puede ser gs://bucket/object, descargado con tu login de gcloud y guardado en caché. Consulta la guía de snapshots en GCS para la entrega mediante un objeto fijo, los permisos necesarios y los límites de actualización. Cada llamada a la CLI decodifica el archivo; MCP solo reutiliza el último archivo local sin cambios. Las llamadas remotas vuelven a analizarlo. Ejecuta figlens --help o figlens inspect --help (también -h) para ver el uso completo de la CLI. index add gs://bucket/object registra una copia fijada de esa generación e informa remote {uri, generation}; solo add ejecuta gcloud.

inspect incluye el ajuste de tamaño del texto, el truncamiento, el máximo de líneas y la decoración registrados. Un padre sin auto-layout lleva childSpacing: "derived": los espacios entre sus hijos son diferencias de coordenadas, no una regla de auto-layout; constraints aún puede fijarlos. handoffDiagnostics informa de semántica guardada pero no emitida, con recuentos, ejemplos y límites de cobertura. Las salidas protegen el origen y reemplazan el destino tras completar la escritura. MCP limita las líneas de solicitud a 1 MiB y las respuestas completas a 8 MiB; si se supera el límite, devuelve un error explícito. El JSON completo sigue disponible mediante la CLI.