Referência da CLI

Comando	Saída
tree <file> [node] [--depth N] [--json]	IDs, tipos REST (como em nodes) e nomes dos nós; texto indentado, ou JSON aninhado com o tamanho de cada nó, se está oculto e o modo de auto layout, mais firstText (primeiro texto visível) nos nós de uma página ou seção
tree <file> [node] --top-frames [--json]	Só as telas, uma por linha, prontas para --frames -: frames, componentes, conjuntos de componentes e instâncias de uma página ou de suas seções (grupos e páginas internas ignorados); --json acrescenta os ids de página e seção e o primeiro texto visível de cada tela (firstText), que separa os rótulos do canvas das telas
find <file> <query> [--type TYPE] [--node ID] [--limit N]	Busca sem diferenciar maiúsculas em nomes de camadas e textos; caminhos, tamanhos e prévias. Padrão de 20 resultados (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]	Busca ranqueada em nomes de camadas e texto completo com overrides de instância, propriedades de texto/booleanas e swaps aplicados; referências exatas de nós (incluindo ids de subcamadas I…;… para inspect), motivos de correspondência, intervalos UTF-16, cobertura e páginas por cursor. Padrão de 20 (1-200); camadas ocultas e páginas internas exigem sua flag. Com --file/--workspace/--id em vez de <file>, lê o índice preparado do workspace (veja index) --mode semantic|hybrid precisa de um modelo configurado: veja Busca semântica opcional.
models list|status|configure <profile> --model DIR [--runtime FILE]|remove <profile>	Modelo de texto local para a busca semântica (bge-m3, experimental) e modelo de imagem para a busca por imagem (siglip-base, experimental); configure confere os arquivos que você baixou e nunca baixa; remove os mantém. Veja Busca semântica opcional.
usages <file> <node|resource> [--scope ID] [--relation R[,R]] [--out] [--snapshot S] [--include-hidden] [--limit N] [--cursor C]	Relações exatas de uma camada ou recurso (VariableID:…, StyleKey:…, image:…) em um escopo salvo, com instâncias aninhadas e swaps: onde um componente, set, variável, estilo ou imagem é usado (padrão) ou para o que uma camada aponta (--out). Cada resultado mantém a referência exata, relação, estado (resolved, missing, unresolved, …), base e evidência; um nome nunca conta como identidade. Sem totais: a cobertura diz completa ou parcial. Padrão 50 (1-200). Com --file/--workspace/--id no lugar de <file>, lê o índice preparado de --scope do workspace. Com --out, um uso de uma cópia de biblioteca em cache também informa sua 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]	Camadas que usam um componente, estilo ou variável de biblioteca (kind), conforme a cópia em cache de cada arquivo registra, no --scope preparado de todas as fontes (--source restringe a uma). A definição fica unresolved, salvo se as três opções --definition-* a selecionarem por referência exata (selected, keyEvidence: unverified); a cobertura informa o estado de cada fonte e por que é parcial. Tome-a do campo library de usages --out numa camada que a use.
diff <old.fig> <new.fig> [--node ID] [--limit N] [--cursor C] [--json]	O que mudou entre duas revisões salvas: uma linha por frame de nível superior alterado, com contagens por faceta (texto, layout, aparência, propriedades, estrutura, vínculos); --json adiciona valores de campo antigos/novos e mudanças de edges. Camadas só correspondem por id e tipo exatos; um frame com o mesmo nome ou posição é apenas um possible match rotulado, e um lado que parou antes, ou uma camada cuja única diferença é um campo que não pôde ser lido, informa unknown, nunca removido nem alterado. Páginas de 100 mudanças (1-500) Um lado que parou num limite imprime stopped early em vez de no changes; restrinja com --node.
inspect <file> <node> [--depth N] [--images] [--states] [--compare-variant ID] [--compare ID] [--flat] [--full-text] [--colors]	Resumo compacto de layout/texto expandido, no máximo 200 nós. --images adiciona dimensões de bitmap e áreas de recorte. --flat imprime uma linha por nó: posição relativa ao nó, tamanho, texto, fonte, preenchimento, traço, raio, auto-layout, alinhamento, tamanho fixed/fill, sombras e desfoques --full-text devolve cada texto completo (até 10.000 caracteres); --colors adiciona os preenchimentos sólidos visíveis (hex, opacidade, variável vinculada), também com --flat; sem gradientes, imagens ou traços.
nodes <file> <node>	O objeto por nó de uma resposta REST de nodes (document, components, componentSets, styles): instâncias e overrides expandidos, auto-layout, estilos de texto, preenchimentos, efeitos, variáveis vinculadas, propriedades de componentes, limites de renderização
nodes <file> --frames <list>, --frames - (stdin), --ids <node>...	Uma decodificação, muitos nós: uma linha JSON por id listado, a saída de nodes com seu nodeId, ou {nodeId, error}
variables <file> [node] variables <file.fig> --format dtcg --collection ID --mode ID --out FILE	Padrão: variáveis vinculadas/locais no formato REST, sem alterações. Exportação DTCG 2025.10: IDs exatos de coleção e modo, sem nó; apenas cores e números sem unidade. Crie primeiro o diretório de saída; qualquer diagnóstico cancela toda a exportação sem alterar o arquivo de saída. Uma coleção de biblioteca é exportada das cópias em cache no arquivo (libraryCopy: true). Um alias para outra coleção exporta o valor dessa coleção, registrado em aliasOf; se ela tiver vários modos, informe --alias-mode COLLECTION=MODE.
bundle <file> <node> <out.zip> [--states]	Um bundle de design de um frame; imprime {nodeId, path, warnings}
bundle <file> --frames <list> --out-dir <dir> [--jobs N] [--states], --frames - (stdin)	Vários bundles a partir de uma decodificação, em paralelo
verify <bundle> [--fonts <dir>]	Confere um bundle (.zip ou diretório extraído) com o manifesto: arquivos verificados, ausentes e alterados, assets ausentes, as fontes a confirmar no projeto e findings: cada entrada de handoff ausente, não suportada ou não verificada, com nós, evidência e próxima ação; uma fonte com arquivo nesta máquina ou em --fonts <dir> (pasta do projeto, que também gera um @font-face) é local_file, sem provar que o navegador a carrega
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; PNGs de até 4.194.304 pixels são otimizados automaticamente sem perda, sem alterar os valores RGBA decodificados; os bytes codificados originais são mantidos se o resultado não for menor, e PNGs maiores usam a codificação normal; --max-kb reduz a qualidade com perda até caber (PNG falha se ainda exceder o limite, sem alternativa com perda); --bounds layout exporta a caixa de layout em vez dos limites de renderização; --match-dir DIR (só SVG, com subpastas) lista os SVGs que desenham os mesmos contornos (matches) e até 10 formas parecidas com pontuação (similar); --hide ID[,ID] desenha essas camadas do nó como ocultas na mesma área, então comparar com a exportação normal mostra onde essa camada, como o figlens a desenha, muda o resultado (nenhuma diferença não prova que o que foi pulado é inofensivo)
export <file> --frames <list> --out-dir <dir> [--format F] [--scale N] ..., --frames - (stdin)	Uma decodificação, muitas exportações (padrão png): grava <dir>/<nodeId>.<format>, uma linha JSON por id, a saída de export com seu nodeId, ou {nodeId, error}
export <file> --batch <items.json>, --batch - (stdin)	Uma decodificação, várias exportações, cada uma com suas opções: um array JSON de 1-64 {node, out, bounds?, scale?, quality?, maxKb?, maxSize?, hide?} (MCP export_batch). Imprime um manifesto {count, failed, items}: por item, a saída de export ou {error} (os demais são exportados mesmo assim); um item malformado ou um out repetido falha antes de qualquer escrita
preview <file> [node] [--out preview.html] [--port N] [--bind IP]	Viewer local que nunca grava o design; busca semântica/híbrida após Enable index; --out grava um snapshot offline independente; resultados e o context copiado indicam a página e, ao vivo, o caminho do arquivo, o snapshot do source carregado e a revision local (desconhecidos offline, onde o caminho nunca é incorporado); o context também traz a coverage do scope de referência, complete: null quando não verificada. Visual/Hybrid aceita um PNG de referência ou uma camada selecionada com recorte em pixels. Ative o índice visual explicitamente; imagens de consulta não são armazenadas.
compare <file> <nodes.json> <node>	Diferenças em relação a uma exportação REST do mesmo frame
compare-image <file> <node> <screenshot.png>	Compara uma captura da tela construída com o node renderizado na escala dela (--scale, --limit, --out diff.png, --full-page para uma captura de página inteira mais curta que o frame; MCP compare_image). Imprime mismatch, nonTextMismatch e as maiores regiões diferentes em pixels do node, cada uma com as camadas mais profundas sob ela; text: true indica regiões sobre texto (muitas vezes fonte substituta; revise cada uma)
node <file> <node>	Um nó .fig bruto
index prepare|refresh|rebuild|clear|status|add|remove|relocate|reset|track|untrack|embed|visual	Workspace local no diretório de estado do figlens do usuário, ou em um --storage DIR que o workspace passa a lembrar. prepare <file> --scope NODE cria uma vez o índice de busca desse escopo; depois search --file <file> (ou --workspace DIR) responde sem reanalisar, com ranking conjunto das fontes do workspace. refresh recria os arquivos alterados, rebuild todos ou uma --source/--scope, clear remove índices sem uso; o índice anterior continua servindo até o novo ficar pronto. reset remove apenas o banco de dados do workspace, nunca designs, exportações ou o local lembrado. track --scope NODE registra as mudanças desse scope a partir de um build baseline; untrack para e mantém o histórico. embed incorpora os escopos publicados com o modelo configurado (CPU e memória); execute só se quiser busca semântica no workspace. visual --scope NODE renderiza as telas e componentes desse escopo publicado para busca por imagem e os incorpora se houver um perfil de visão configurado; execute só se quiser busca visual no workspace.
jobs status|cancel <jobId>	Ver ou cancelar a criação de um índice; cancel retorna depois que a criação parou
changes --file <file>|--id ID|--workspace DIR [--source ID] [--scope NODE] [--consumer NAME|--subscription ID|--cursor C] [--revision R] [--limit N]	Mudanças registradas dos scopes acompanhados, da mais antiga para a mais recente: uma revisão por build publicado (baseline ou changes) com cobertura e contagens por tipo de mudança e faceta; cada revisão changes tem um resumo impact das camadas que suas mudanças alcançam (null antes do schema 7); --revision pagina os nodes alterados dessa revisão e depois as camadas que seu impacto lista (entry diz qual); tracking informa quando um scope precisa de index refresh para registrar uma mudança. Somente leitura
watch ack --file <file>|--id ID|--workspace DIR --consumer NAME|--subscription ID --cursor C [--source ID] [--scope NODE]	Move o checkpoint de um consumidor para o nextCursor da última página de changes processada com os mesmos filtros; repetir é seguro e ele só avança, exceto que um cursor de recuperação atual volta um checkpoint que ficou atrás de uma exclusão para reler as revisões mantidas; um cursor emitido antes de a retenção apagar revisões que ele não tinha passado é event_gap e não grava nada
watch run --file <file>|--id ID|--workspace DIR --scope NODE [--source ID] [--request-id R]	Mantém em primeiro plano um lease sobre um scope rastreado: o runner compartilhado do workspace o atualiza a cada salvamento (consulta a cada 250 ms, verificação de conteúdo a cada 60 s), então changes mostra novas revisões sem index refresh. Imprime o lease e depois uma linha final quando o stdin fecha, com Ctrl-C ou SIGTERM, ou quando o scope deixa de ser rastreado. MCP watch start e stop mantêm leases enquanto o servidor roda; um lease não renovado termina após 30 s e o runner sai depois do último
watch status --file <file>|--id ID|--workspace DIR	Os leases do workspace (active, unauthorized, untracked, expired, ended) e seu runner (running, stopping, stopped, unknown, com o posicionamento); nunca escreve
watch subscribe --file <file>|--id ID|--workspace DIR --consumer NAME --source ID [--scope NODE] [--node ID] [--owner NAME]	Acompanha uma fonte, um scope ou uma camada exata (--node) a partir da revisão mais recente com checkpoint próprio, lido com changes --subscription e confirmado com watch ack --subscription; uma camada ausente ou ambígua é target_missing ou identity_uncertain, nunca outra de mesmo nome; --owner a torna temporária para essa tarefa
watch subscribe --file <file>|--id ID|--workspace DIR --consumer NAME --source ID --query TEXT [--type T[,T]] [--scope NODE]	Salva uma busca no scope de uma fonte: seus 50 primeiros são avaliados na hora; changes --subscription lê as avaliações salvas e nunca calcula uma
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]	Salva uma busca, ou os usos de um item de biblioteca com seu definitionMatch, sobre um conjunto fixo de até 10 fontes (visible é resolvido agora; fontes adicionadas depois nunca entram): delta.changedSourceIds nomeia as fontes com bytes novos, corpus_changed uma mudança do conjunto, coverage.transitive é not_followed e delta.notFollowedSourceIds nomeia as fontes alteradas sem usos, cujos dependentes não foram reverificados; remover um membro a desativa (unsubscribe e depois subscribe de novo)
watch evaluate --file <file>|--id ID|--workspace DIR --subscription ID	Salva a avaliação de uma assinatura de consulta sobre o índice atual do scope, a menos que já esteja avaliada; um watch no scope faz isso após cada publicação
watch list --file <file>|--id ID|--workspace DIR [--consumer NAME] [--after ID] [--subscription ID]	Lista as assinaturas visíveis e seu estado, uma página por vez; --subscription lê só aquela (vazio quando não visível)
watch unsubscribe --file <file>|--id ID|--workspace DIR --subscription ID|--consumer C --owner NAME	Remove uma assinatura e seu checkpoint, ou as temporárias de um owner; o tracking e o histórico permanecem
watch forget --file <file>|--id ID|--workspace DIR --consumer NAME [--source ID] [--scope NODE]	Remove os checkpoints avulsos de um consumer; um consumer mantém no máximo 64 assinaturas e checkpoints e um workspace 4096, e nada é removido automaticamente
mcp	Servidor MCP local por stdio
update	Substitui o binário pela release mais recente

Para variantes de componentes relacionadas, use inspect --states ou bundle --states (MCP: states: true, false por padrão; sem alterar a configuração). As evidências preservam origem, valores desconhecidos e marcações de truncamento. Os bundles adicionam design/states.json e um resumo em context.md. Consulte o escopo e os limites em evidências de estados.

Compare duas variantes do mesmo component set com inspect <file> <variantA> --compare-variant <variantB> (MCP compareVariant). variantComparison mostra diferenças dos campos e conjuntos de valores armazenados, com IDs de origem e valores desconhecidos, Nós filhos são pareados por nome único, depois por componente principal e depois por ordem de empilhamento em grupos de mesmo nome e tamanho (pairedNodes, com mudanças por par; confira pairedBy, order é a evidência mais fraca; o resto fica sem par), e variáveis vinculadas são nomeadas. Consulte os limites.

Para comparar dois nós quaisquer do mesmo arquivo (tela vazia e preenchida, breakpoints mobile e desktop, duas telas com o mesmo cabeçalho), use inspect <file> <nodeA> --compare <nodeB> (MCP compare). comparison tem o mesmo formato mais rootDelta (tamanho e posição relativa ao pai); os filhos são pareados por nome único, depois por componente principal e depois por ordem de empilhamento em grupos de mesmo nome e tamanho (pairedBy informa qual), o resto fica sem par com reason: ambiguous-name, as instâncias não são expandidas e um nó não pode ser comparado com seu próprio ancestral. --compare-variant continua exigindo o mesmo component set.

Um argumento de nó aceita 12:345, 12-345 ou uma URL do Figma com ?node-id=. <file> também pode ser gs://bucket/object, baixado com seu login do gcloud e armazenado em cache. Consulte o guia de snapshots do GCS para a troca por um objeto fixo, as permissões necessárias e os limites de atualização. Cada chamada da CLI decodifica o arquivo; MCP reutiliza apenas o último arquivo local sem alterações. Chamadas remotas analisam o arquivo novamente. Execute figlens --help ou figlens inspect --help (também -h) para ver o uso completo da CLI. index add gs://bucket/object registra uma cópia fixada dessa geração e informa remote {uri, generation}; só add executa o gcloud.

inspect inclui redimensionamento do texto, truncamento, máximo de linhas e decoração registrados. Um pai sem auto-layout traz childSpacing: "derived": os espaços entre os filhos são diferenças de coordenadas, não uma regra de auto-layout; constraints ainda pode fixá-los. handoffDiagnostics informa semântica salva, mas não emitida, com contagens, exemplos e limites de cobertura. As saídas protegem a origem e substituem o destino após a escrita completa. MCP limita as linhas de requisição a 1 MiB e as respostas completas a 8 MiB; exceder o limite gera um erro explícito. O JSON completo continua disponível pela CLI.