CLI 레퍼런스

명령어	출력
tree <file> [node] [--depth N] [--json]	노드 ID, REST 유형(nodes와 동일), 이름. 들여쓰기 텍스트, 또는 각 노드의 크기, 숨김 여부, 오토 레이아웃 모드을 담은 중첩 JSON. 페이지나 섹션 바로 아래 노드에는 firstText(첫 번째 보이는 텍스트)도 포함
tree <file> [node] --top-frames [--json]	화면만 한 줄에 하나씩, --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로 남고(세 --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) 한도에서 멈춘 쪽이 있으면 no changes 대신 stopped early를 출력합니다. --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): 펼쳐진 인스턴스와 재정의, 자동 레이아웃, 텍스트 스타일, 채우기, 효과, 연결 변수, 컴포넌트 속성, 렌더링 경계
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는 생략합니다. 색상과 단위 없는 숫자만 지원합니다. 출력 디렉터리를 먼저 만드세요. 진단이 있으면 전체 내보내기가 실패하며 출력 파일은 변경되지 않습니다. 라이브러리 collection은 파일에 캐시된 사본에서 내보냅니다(libraryCopy: true). 다른 collection을 가리키는 alias는 그 collection의 값으로 내보내고 aliasOf에 기록합니다. 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>]	bundle(.zip 또는 압축을 푼 디렉터리)을 manifest와 대조: 검증·누락·변경된 파일, 누락된 asset, 프로젝트에서 확인할 폰트, 그리고 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)	한 번 디코딩해 여러 개 내보내기(기본 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). 매니페스트 {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, frame보다 짧은 전체 페이지 캡처에는 --full-page; 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가 이후 기억하는 --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]	추적 중인 스코프에 기록된 변경을 오래된 순으로 반환합니다. 게시된 빌드마다 리비전 하나(baseline 또는 changes)와 커버리지, 변경 종류·facet별 개수를 포함합니다. 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로 consumer의 체크포인트를 옮깁니다. 반복해도 안전하며 앞으로만 움직입니다. 다만 삭제 뒤에 남은 체크포인트는 현재 복구 커서가 되돌려 보존된 리비전을 다시 읽게 합니다. 아직 지나지 않은 리비전을 보존 정책이 삭제하기 전에 발급된 커서는 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 추적이 해제되면 종료 줄을 한 줄 출력합니다. MCP watch start와 stop은 서버가 실행되는 동안 lease를 유지하고, 갱신되지 않은 lease는 30 s 후 끝나며 runner는 마지막 lease 뒤에 종료됩니다
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]	한 소스의 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의 임시 구독을 삭제합니다. 트래킹과 기록은 남습니다
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의 두 variants는 inspect <file> <variantA> --compare-variant <variantB>(MCP compareVariant)로 비교합니다. variantComparison은 저장된 필드와 값 집합의 차이, 출처 ID, 알 수 없는 항목을 반환하며 자식 노드는 고유한 이름, 메인 컴포넌트, 같은 개수의 동명 그룹 안의 쌓임 순서 순으로 짝짓고(pairedNodes, 쌍별 변경 포함. pairedBy를 확인하며 order가 가장 약한 근거, 나머지는 짝 없음), 바인딩된 variables는 이름을 표시합니다. 비교 제한을 참조하세요.

한 파일의 임의의 두 노드(빈 화면과 채워진 화면, 모바일과 데스크톱 브레이크포인트, 헤더를 공유하는 두 화면 등)는 inspect <file> <nodeA> --compare <nodeB>(MCP compare)로 비교할 수 있습니다. comparison은 같은 형태에 rootDelta(크기와 부모 기준 위치)를 더해 반환합니다. 자식은 고유한 이름, 메인 컴포넌트, 같은 개수의 동명 그룹 안의 쌓임 순서 순으로 짝지어지며(pairedBy가 방법을 알려 줍니다) 나머지는 reason: ambiguous-name과 함께 짝지어지지 않습니다. 인스턴스는 펼쳐지지 않고 노드와 그 조상은 비교할 수 없습니다. --compare-variant는 여전히 같은 component set이 필요합니다.

노드 인수는 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는 해당 generation의 고정된 사본을 등록하고 remote {uri, generation}을 보고하며, gcloud는 add만 실행합니다.

inspect에는 기록된 텍스트 크기 조정, 잘림, 최대 줄 수와 장식이 포함됩니다. auto-layout이 없는 부모에는 childSpacing: "derived"가 붙습니다. 자식 사이의 간격은 좌표 차이이며 auto-layout 규칙이 아닙니다. constraints가 고정할 수는 있습니다. handoffDiagnostics는 저장되었지만 출력되지 않는 의미 정보를 개수, 예시, 범위 제한과 함께 보고합니다. 출력은 원본을 보호하고 쓰기가 완료된 뒤 대상을 교체합니다. MCP 요청 행은 1 MiB, 전체 응답은 8 MiB로 제한되며 초과하면 명시적인 오류를 반환합니다. CLI에서는 전체 JSON을 계속 출력할 수 있습니다.