CLI 参考

命令	输出
tree <file> [node] [--depth N] [--json]	节点 id、REST 类型（与 nodes 相同）和名称；缩进文本，或附带每个节点尺寸、隐藏状态与 auto layout 模式的嵌套 JSON；页面或 section 下的节点另附 firstText（第一段可见文字）
tree <file> [node] --top-frames [--json]	只列出画面，每行一个，可直接传给 --frames -：页面或其 section 下的 frame、component、component set 与 instance（跳过 group 与内部页面）；--json 附上 page 与 section id，以及每个画面第一段可见文字（firstText），可用来区分画布标签与画面
find <file> <query> [--type TYPE] [--node ID] [--limit N]	不区分大小写地搜索图层名称和文字；返回路径、尺寸和预览。默认 20 条结果（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]	对图层名称和完整文字做排序搜索，已套用 instance override、文字/布尔属性和 swap；返回精确节点引用（包括可用于 inspect 的 I…;… 子图层 id）、匹配原因、UTF-16 范围、覆盖情况和 cursor 分页。默认 20 条（1-200）；隐藏图层和内部页面需加对应 flag。以 --file/--workspace/--id 取代 <file> 时，读取 workspace 已准备的索引（见 index） --mode semantic|hybrid 需要已配置的模型，参见可选的语义搜索。
models list|status|configure <profile> --model DIR [--runtime FILE]|remove <profile>	语义搜索用的本地文本模型（bge-m3，实验性）与图片搜索用的图像模型（siglip-base，实验性）；configure 校验你自行下载的文件，从不下载；remove 保留文件。参见可选的语义搜索。
usages <file> <node|resource> [--scope ID] [--relation R[,R]] [--out] [--snapshot S] [--include-hidden] [--limit N] [--cursor C]	在一个已保存范围内返回图层或资源（VariableID:…、StyleKey:…、image:…）的精确关系，包括嵌套 instance 和 swap：默认返回组件、组件集、变量、样式或图片被使用的位置，--out 返回图层指向的目标。每个结果保留精确引用、关系、状态（resolved、missing、unresolved 等）、依据和证据；名称从不算作同一身份。不返回总数，coverage 说明完整或部分。默认 50 条（1-200）。用 --file/--workspace/--id 代替 <file> 时读取 workspace 已准备好的 --scope 索引。使用 --out 时，缓存库副本的使用也会给出其 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]	返回使用某个库组件、样式或变量（kind）的图层，依据各文件缓存副本的记录，范围是所有来源已准备好的 --scope（--source 限定为一个）。定义保持 unresolved（以三个 --definition-* 按精确引用选定时为 selected，keyEvidence: unverified）；coverage 列出每个来源的状态和部分的原因。参数取自对使用它的图层执行 usages --out 时的 library 字段
diff <old.fig> <new.fig> [--node ID] [--limit N] [--cursor C] [--json]	两个已保存版本之间的变更：每个有变更的顶层 frame 一行，按 facet（文本、布局、外观、属性、结构、绑定）计数；--json 另含新旧字段值与 edge 变更。图层只按完全相同的 id 与类型匹配；同名或同位置的 frame 只标为 possible match，中途停止的一侧，或唯一差异是无法读取的字段的图层，报告 unknown，绝不当作删除或变更。每页 100 条（1-500）有一侧在上限处停止时，打印 stopped early 而不是 no changes；用 --node 缩小范围。
inspect <file> <node> [--depth N] [--images] [--states] [--compare-variant ID] [--compare ID] [--flat] [--full-text] [--colors]	展开后的精简布局/文字摘要，最多 200 个节点。--images 会加上位图尺寸和裁切范围。--flat 改为每个节点一行：相对该节点的位置、尺寸、文字、字体、填充、描边、圆角、auto-layout、对齐、fixed/fill 尺寸、阴影与模糊 --full-text 返回每段文字的完整内容（最多 10,000 字符）；--colors 加入可见的纯色填充（hex、不透明度、绑定变量），--flat 也适用；不含渐变、图片或描边。
nodes <file> <node>	REST nodes 响应中单个节点的对象（document、components、componentSets、styles）：展开的 instance 与覆写、auto-layout、文字样式、填充、效果、绑定变量、组件属性、渲染边界
nodes <file> --frames <list>, --frames - (stdin), --ids <node>...	一次解码读取多个节点：列表中每个 id 一行 JSON（带 nodeId 的 nodes 输出，或 {nodeId, error}）
variables <file> [node] variables <file.fig> --format dtcg --collection ID --mode ID --out FILE	默认的 REST 格式绑定变量／本地变量输出保持不变。DTCG 2025.10 导出须指定准确的 collection 和 mode ID，不可指定 node；仅支持颜色和无单位数值。请先创建输出目录；任何诊断都会使整个导出失败，输出文件保持不变。library collection 会从文件中缓存的副本导出（libraryCopy: true）。指向其他 collection 的 alias 会导出该 collection 的值并记录在 aliasOf；该 collection 有多个 mode 时，用 --alias-mode COLLECTION=MODE 指定。
bundle <file> <node> <out.zip> [--states]	单个 frame 的设计 bundle；输出 {nodeId, path, warnings}
bundle <file> --frames <list> --out-dir <dir> [--jobs N] [--states], --frames - (stdin)	一次解码，并行生成多个 bundle
verify <bundle> [--fonts <dir>]	按 manifest 检查 bundle（.zip 或解压后的目录）：已验证、缺失和被改动的文件，缺失的素材，需要在项目中确认的字体，以及 findings：每项缺失、不支持或未验证的 handoff 输入，附节点、证据和下一步；在本机或 --fonts <dir>（项目文件夹，同时生成 @font-face）中找到字体文件的字体为 local_file，不代表浏览器能加载
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 或 AVIF；不超过 4,194,304 像素的 PNG 自动进行无损优化，解码后的 RGBA 不变，若未变小则保留原始编码字节，更大的 PNG 使用常规编码；--max-kb 会降低有损质量直到符合大小（PNG 若仍超限则失败，不会回退为有损编码）；--bounds layout 按 layout box 而不是 render bounds 导出；--match-dir DIR（仅 SVG，含子文件夹）列出绘制相同轮廓的 SVG（matches），以及最多 10 个带分数的相似形状（similar）；--hide ID[,ID] 把 node 内的这些图层当作隐藏、在相同范围内绘制，与正常导出对比即可看出 figlens 画出的这个图层改变了结果的哪些地方（没有差异不代表未渲染的调整没有影响）
export <file> --frames <list> --out-dir <dir> [--format F] [--scale N] ..., --frames - (stdin)	一次解码导出多个节点（默认 png）：写入 <dir>/<nodeId>.<format>，每个 id 一行 JSON（带 nodeId 的 export 输出，或 {nodeId, error}）
export <file> --batch <items.json>, --batch - (stdin)	一次解码导出多个节点，每项各有自己的选项：1-64 个 {node, out, bounds?, scale?, quality?, maxKb?, maxSize?, hide?} 的 JSON 数组（MCP export_batch）。输出一份 manifest {count, failed, items}：每项为 export 输出或 {error}（其余照常导出）；条目格式错误或 out 重复会在写入任何文件前失败
preview <file> [node] [--out preview.html] [--port N] [--bind IP]	从不写入设计的本地 viewer；按 Enable index 后可用语义/混合搜索；--out 写出独立的离线快照；结果与复制的 context 会标明页面，live 时也标明已加载文件的路径、source 的 snapshot 与本地 revision（离线时未知，且绝不嵌入路径）；context 也带有参考 scope 的 coverage，未检查时为 complete: null. Visual／Hybrid 可使用参考 PNG 或所选图层，并按像素裁剪。请明确启用视觉索引；查询图片不会保存。
compare <file> <nodes.json> <node>	与同一 frame 的 REST 导出做差异比较
compare-image <file> <node> <screenshot.png>	把实现画面的截图与按其缩放渲染的 node 比较（--scale、--limit、--out diff.png、--full-page 用于比 frame 短的整页截图；MCP compare_image）。输出 mismatch、nonTextMismatch 和差异最大的区域（node 像素坐标），每个区域附其下最深的图层；text: true 表示区域位于文字上（多为字体替代，需逐一检查）
node <file> <node>	单个原始 .fig 节点
index prepare|refresh|rebuild|clear|status|add|remove|relocate|reset|track|untrack|embed|visual	用户 figlens state 目录中的本地 workspace，或位于 workspace 之后会记住的 --storage DIR 下。prepare <file> --scope NODE 为该范围建立一次搜索索引；之后 search --file <file>（或 --workspace DIR）不再解析文件，跨 workspace 的所有来源统一排序作答。refresh 重建有变更的文件，rebuild 重建全部或单一 --source/--scope，clear 删除未使用的索引；新索引就绪前继续使用旧索引。reset 只删除 workspace 数据库，不会删除设计、导出或记住的位置。track --scope NODE 从 baseline 构建开始记录该范围的变更；untrack 停止记录并保留历史。 embed 用已配置的模型嵌入已发布的范围（占用 CPU 和内存）；仅在需要 workspace 语义搜索时运行。 visual --scope NODE 为图片搜索渲染该已发布范围的画面与组件，配置视觉模型时一并嵌入；仅在需要 workspace 视觉搜索时运行。
jobs status|cancel <jobId>	查看或取消索引构建；cancel 在构建停止后才返回
changes --file <file>|--id ID|--workspace DIR [--source ID] [--scope NODE] [--consumer NAME|--subscription ID|--cursor C] [--revision R] [--limit N]	已跟踪范围记录的变更，从最旧开始：每次发布的构建一个修订（baseline 或 changes），含覆盖情况及按变更类型与 facet 的计数；每个 changes 修订都有 impact 摘要，说明变更波及的图层（schema 7 之前为 null）；--revision 分页列出该修订变更的节点，再列出 impact 列出的图层（entry 标明是哪一种）；tracking 指出哪些范围需要 index refresh 才能记录变更。只读
watch ack --file <file>|--id ID|--workspace DIR --consumer NAME|--subscription ID --cursor C [--source ID] [--scope NODE]	把 consumer 的检查点移到它以相同筛选条件处理完的最后一页 changes 的 nextCursor；重复执行是安全的，而且只会前进；唯一例外是当前的 recovery cursor 会把落在删除之后的检查点退回，以重读保留的 revision；在保留策略删除它尚未经过的 revision 之前发出的 cursor 会得到 event_gap，不写入任何内容
watch run --file <file>|--id ID|--workspace DIR --scope NODE [--source ID] [--request-id R]	在前台持有一个已跟踪 scope 的 lease：workspace 共享的 runner 在每次保存时刷新它（每 250 ms 轮询，每 60 s 校验内容），因此 changes 无需 index refresh 就会出现新 revision。先输出 lease，在 stdin 关闭、收到 Ctrl-C 或 SIGTERM、或 scope 被取消跟踪时输出一行结束信息。MCP watch 的 start 与 stop 在服务器运行期间持有 lease；未续期的 lease 30 s 后结束，最后一个 lease 结束后 runner 退出
watch status --file <file>|--id ID|--workspace DIR	workspace 的 lease（active、unauthorized、untracked、expired、ended）与 runner（running、stopping、stopped、unknown，附放置方式）；从不写入
watch subscribe --file <file>|--id ID|--workspace DIR --consumer NAME --source ID [--scope NODE] [--node ID] [--owner NAME]	从最新修订开始跟随一个源、scope 或确切图层（--node），使用它自己的检查点，用 changes --subscription 读取、watch ack --subscription 确认；不存在或有歧义的图层为 target_missing 或 identity_uncertain，绝不换成同名图层；--owner 让它只在该任务内临时存在
watch subscribe --file <file>|--id ID|--workspace DIR --consumer NAME --source ID --query TEXT [--type T[,T]] [--scope NODE]	保存对一个来源 scope 的搜索：立即评估其前 50 名；changes --subscription 只读取已保存的评估，从不计算
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]	对最多 10 个来源的固定集合保存搜索，或保存库项目的使用处及其 definitionMatch（visible 在此时解析，之后新增的来源不会加入）：delta.changedSourceIds 列出字节有变的来源，corpus_changed 表示集合有变，coverage.transitive 为 not_followed，delta.notFollowedSourceIds 列出没有使用处的已变更来源（其下游未重新检查）；移除成员会停用它（先 unsubscribe，再重新 subscribe）
watch evaluate --file <file>|--id ID|--workspace DIR --subscription ID	按 scope 当前的索引评估并保存查询订阅，已评估则不做任何事；该 scope 处于 watch 时，每次发布后会自动进行
watch list --file <file>|--id ID|--workspace DIR [--consumer NAME] [--after ID] [--subscription ID]	分页列出可见的订阅及其状态；--subscription 只读取该订阅（不可见时为空）
watch unsubscribe --file <file>|--id ID|--workspace DIR --subscription ID|--consumer C --owner NAME	删除一个订阅及其检查点，或某个 owner 的临时订阅；tracking 和历史保留
watch forget --file <file>|--id ID|--workspace DIR --consumer NAME [--source ID] [--scope NODE]	删除 consumer 的原始检查点；每个 consumer 最多保留 64 个订阅与检查点，整个 workspace 4096 个，不会自动淘汰
mcp	通过 stdio 运行的本地 MCP server
update	用最新 release 替换可执行文件

需要相关组件 variants 时，使用 inspect --states 或 bundle --states（MCP 传入 states: true，默认 false；无需修改配置）。证据保留来源、未知及截断标记。Bundle 会添加 design/states.json 和 context.md 摘要。范围与限制参见状态证据。

比较同一 component set 的两个 variants：inspect <file> <variantA> --compare-variant <variantB>（MCP compareVariant）。variantComparison 列出原始字段及值集合差异，保留来源和未知标记；子节点依唯一名称、主组件、同数量同名分组内的堆叠顺序配对（pairedNodes，附逐对差异；请检查 pairedBy，order 证据最弱；其余不配对），并标出绑定变量的名称。详见比较限制。

要比较同一文件中的任意两个节点（空白与已填内容的画面、手机与桌面断点、共用页头的两个画面），请使用 inspect <file> <nodeA> --compare <nodeB>（MCP compare）。comparison 格式相同，另有 rootDelta（尺寸与相对于父级的位置）；子节点依唯一名称、主组件、同数量同名分组内的堆叠顺序配对（pairedBy 标明方式），其余不配对并标注 reason: ambiguous-name；instance 不会展开，节点也不能与自己的祖先比较。--compare-variant 仍要求同一个 component set。

node 参数接受 12:345、12-345，或带 ?node-id= 的 Figma URL。<file> 也可以是 gs://bucket/object，通过你的 gcloud 登录下载并缓存。固定 object 交接、所需访问权限与更新限制，请参阅 GCS 快照操作说明。每次 CLI 调用都会解码文件；MCP 只复用最后读取且未变更的本地文件，远程输入仍会重新解析。运行 figlens --help 或 figlens inspect --help（也可用 -h）查看完整 CLI 用法。index add gs://bucket/object 会登记该 generation 的固定副本并报告 remote {uri, generation}；只有 add 会运行 gcloud。

inspect 包含已记录的文字尺寸调整、截断、最大行数与装饰。没有 auto-layout 的父层会带 childSpacing: "derived"：子层之间的间距是坐标差，不是 auto-layout 规则；constraints 仍可能固定它们。handoffDiagnostics 会列出已保存但尚未输出的语义、数量、示例及覆盖限制。输出会保护源文件，完整写入后才替换目标。MCP 请求行上限为 1 MiB，完整响应上限为 8 MiB，超限会明确报错；CLI 仍可输出完整 JSON。