CLI リファレンス

コマンド	出力
tree <file> [node] [--depth N] [--json]	ノード ID、REST タイプ（nodes と同じ）、名前。インデント付きテキスト、または各ノードのサイズ、非表示状態、オートレイアウトのモードを含むネストした JSON。ページやセクション直下のノードには firstText（最初の表示テキスト）も付く
tree <file> [node] --top-frames [--json]	画面だけを 1 行に 1 つ、--frames - にそのまま渡せる形で出力。ページまたはそのセクション直下のフレーム、コンポーネント、コンポーネントセット、インスタンス（グループと内部ページは除外）。--json はページとセクションの 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]	インスタンスのオーバーライド、テキスト/ブーリアンプロパティ、スワップを適用したレイヤー名と全文のランク付き検索。正確なノード参照（inspect で使える I…;… サブレイヤー ID を含む）、一致理由、UTF-16 範囲、カバレッジ、カーソルによるページ送り。デフォルト 20 件（1-200）。非表示レイヤーと内部ページはそれぞれのフラグが必要。<file> の代わりに --file/--workspace/--id を使うと、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:…）の正確な関係を返します。ネストしたインスタンスとスワップも含みます。既定ではコンポーネント、セット、変数、スタイル、画像が使われている場所を、--out ではレイヤーが指す先を返します。各結果は正確な参照、関係、状態（resolved、missing、unresolved など）、根拠、証拠を持ち、名前は同一性として扱いません。総数は返さず、coverage が完全か部分的かを示します。既定 50 件（1-200）。<file> の代わりに --file/--workspace/--id を使うと、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 のままで（3 つの --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 と報告します。1 ページ 100 件（1-500）上限で止まった側があると no changes ではなく stopped early と表示します。--node で範囲を絞ってください。
inspect <file> <node> [--depth N] [--images] [--states] [--compare-variant ID] [--compare ID] [--flat] [--full-text] [--colors]	展開済みレイアウト/テキストのコンパクトな要約（最大 200 ノード）。--images でビットマップの寸法とクロップ範囲を追加。--flat は代わりに 1 ノード 1 行で出力（ノード基準の位置、サイズ、テキスト、フォント、塗り、線、角丸、auto-layout、整列、fixed/fill サイズ、シャドウとブラー） --full-text は各テキストを全文で返し（最大 10,000 文字）、--colors は表示中のソリッド塗り（hex、不透明度、バインドされた変数）を追加します（--flat でも有効）。グラデーション、画像、線は含みません。
nodes <file> <node>	REST nodes レスポンスのノードごとのオブジェクト（document、components、componentSets、styles）：展開済みインスタンスとオーバーライド、auto-layout、テキストスタイル、フィル、エフェクト、バインドされた variables、コンポーネントプロパティ、レンダリング bounds
nodes <file> --frames <list>, --frames - (stdin), --ids <node>...	1 回のデコードで複数ノード：リストの id ごとに 1 行の JSON（nodeId 付きの nodes 出力、または {nodeId, error}）
variables <file> [node] variables <file.fig> --format dtcg --collection ID --mode ID --out FILE	既定の REST 形式のバインド済み／ローカル variables は変更なし。DTCG 2025.10 エクスポートは正確な collection／mode ID を指定し、node は指定不可。色と単位なしの数値のみ対応。出力先ディレクトリを先に作成してください。診断があれば全体が失敗し、出力ファイルは変更されません。ライブラリの collection はファイル内のキャッシュされたコピーから書き出します（libraryCopy: true）。別の collection への alias はその collection の値を書き出し、aliasOf に記録します。mode が複数ある場合は --alias-mode COLLECTION=MODE を指定します。
bundle <file> <node> <out.zip> [--states]	1 つの frame の design bundle。{nodeId, path, warnings} を出力
bundle <file> --frames <list> --out-dir <dir> [--jobs N] [--states], --frames - (stdin)	1 回のデコードから複数の bundle を並列生成
verify <bundle> [--fonts <dir>]	bundle（.zip または展開したディレクトリ）を manifest と照合：検証済み・欠落・変更されたファイル、欠落アセット、プロジェクトで確認すべきフォント、および 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 は render bounds ではなく layout box で書き出す。--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)	1 回のデコードで複数を書き出し（既定は png）：<dir>/<nodeId>.<format> に書き、id ごとに 1 行の JSON（nodeId 付きの export 出力、または {nodeId, error}）
export <file> --batch <items.json>, --batch - (stdin)	1 回のデコードで複数を書き出し、項目ごとにオプションを指定：1-64 個の {node, out, bounds?, scale?, quality?, maxKb?, maxSize?, hide?} の JSON 配列（MCP export_batch）。マニフェスト {count, failed, items} を 1 つ出力し、各項目は 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、frame より短いフルページキャプチャには --full-page、MCP compare_image）。mismatch、nonTextMismatch と、差分の大きい領域を node のピクセル座標で出力し、各領域の下にある最も深いレイヤーを示します。text: true はテキスト上の領域です（多くはフォント代替。各領域を確認してください）
node <file> <node>	.fig の生ノード 1 つ
index prepare|refresh|rebuild|clear|status|add|remove|relocate|reset|track|untrack|embed|visual	ユーザーごとの figlens state ディレクトリ、または workspace が以後記憶する --storage DIR の下にあるローカル workspace。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]	追跡中のスコープで記録された変更を古い順に返します。公開されたビルドごとに 1 リビジョン（baseline または changes）で、カバレッジと変更種別・ファセットごとの件数を含みます。changes リビジョンには変更が及ぶレイヤーの impact 要約があります（スキーマ 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]	同じフィルターで処理した最後の changes ページの nextCursor まで、コンシューマーのチェックポイントを進めます。繰り返しても安全で、通常は前にしか進みません。ただし削除の後ろに残ったチェックポイントは、現在のリカバリーカーソルで戻され、保持されたリビジョンを読み直します。まだ通過していないリビジョンを保持期間の削除より前に発行したカーソルは 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 ごとに内容を確認）、index refresh なしで changes に新しい revision が出ます。lease を出力し、stdin が閉じたとき、Ctrl-C や SIGTERM、または scope の追跡解除で終了行を 1 行出力します。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]	ソース、スコープ、または特定のレイヤー（--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]	1 つのソースの 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	サブスクリプション 1 件とそのチェックポイント、または owner の一時的なものを削除します。トラッキングと履歴は残ります
watch forget --file <file>|--id ID|--workspace DIR --consumer NAME [--source ID] [--scope NODE]	consumer の素のチェックポイントを削除します。consumer ごとにサブスクリプションとチェックポイントは最大 64、ワークスペース全体で 4096 で、自動で追い出されることはありません
mcp	stdio 経由のローカル MCP サーバー
update	バイナリを最新リリースに置き換え

関連するコンポーネント variants には inspect --states または bundle --states を使用します（MCP は states: true、既定は false、設定変更は不要）。証拠にはソース、不明点、省略のマーカーが残ります。Bundle には design/states.json と context.md の要約が追加されます。範囲と制限は状態の証拠を参照してください。

同じ component set の 2 つの variants は inspect <file> <variantA> --compare-variant <variantB>（MCP compareVariant）で比較できます。variantComparison は保存フィールドと値集合の差、ソース ID、不明点を返します。子ノードは一意な名前、メインコンポーネント、同数の同名グループ内の重なり順の順に対応付け（pairedNodes、ペアごとの差分付き。pairedBy を確認し、order が最も弱い根拠。残りは未対応）、バインドされた variables は名前を示します。比較の制限を参照してください。

1 つのファイル内の任意の 2 ノード（空の画面と入力済みの画面、モバイルとデスクトップのブレークポイント、ヘッダーを共有する 2 画面など）は inspect <file> <nodeA> --compare <nodeB>（MCP compare）で比較できます。comparison は同じ形式で、さらに rootDelta（サイズと親基準の位置）を返します。子は一意な名前、メインコンポーネント、同数の同名グループ内の重なり順の順に対応付けされ（pairedBy が方法を示します）、残りは reason: ambiguous-name 付きで未対応のままです。インスタンスは展開されず、ノードとその祖先は比較できません。--compare-variant は引き続き同じ component set を必要とします。

node 引数には 12:345、12-345、または ?node-id= 付きの Figma URL を指定できます。<file> には gs://bucket/object も指定でき、gcloud ログインでダウンロードしてキャッシュします。固定オブジェクトでの受け渡し、必要なアクセス権、更新の制限は GCS スナップショットガイドを参照してください。CLI は呼び出しごとにファイルをデコードします。MCP が再利用するのは最後に読み取った変更のないローカルファイルだけです。リモート入力は毎回解析し直します。CLI の全使用法は figlens --help または figlens inspect --help（-h も可）で確認できます。index add gs://bucket/object はその世代のピン留めしたコピーを登録し、remote {uri, generation} を返します。gcloud を実行するのは add だけです。

inspect は記録済みのテキストのリサイズ、切り詰め、最大行数、装飾を含みます。auto-layout のない親には childSpacing: "derived" が付きます。子要素の間隔は座標の差で、auto-layout のルールではありません。constraints で固定されている場合もあります。handoffDiagnostics は保存済みでも未出力の意味情報を件数、例、対象範囲の制限とともに示します。出力は元ファイルを保護し、書き込み完了後に保存先を置き換えます。MCP のリクエスト行は 1 MiB、完全な応答は 8 MiB が上限で、超過時は明示的なエラーを返します。CLI では引き続き完全な JSON を出力できます。