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 與 override、auto-layout、文字樣式、填色、效果、綁定的 variables、元件屬性、渲染邊界
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 伺服器
update	將執行檔換成最新發行版

需要相關元件 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。