figma-inspect-cli

Node.js CLI for inspecting Figma API resources and exporting AI-friendly contracts for component sets, frames, and standalone components.

Setup

npm install
npm run build

Set the environment variables needed by API-backed commands:

export FIGMA_API_TOKEN="figd_..."
export FIGMA_TEAMS='{"design":"<team_id>","marketing":"<team_id>"}'

The token must include folders:read for team discovery and index refreshes. FIGMA_TEAM_ID=<team_id> remains supported for existing single-team setups. FIGMA_TEAMS enables aliases and all-team index commands; aliases are chosen by the user and have no built-in meaning.

From the repository, run the compiled CLI with npx .:

npx . --help

For source-mode development, use npm run dev -- <flags>.

Commands

Only one command can be passed per invocation. FIGMA_API_TOKEN is required for all API-backed commands and verification. Team-scoped commands use the legacy FIGMA_TEAM_ID, the only FIGMA_TEAMS entry, or a --team <alias> selection. Managed index commands without --team operate on every FIGMA_TEAMS entry.

| Command | Main arguments | Output | |---|---|---| | --version | none | CLI package version | | --list-team-projects | none | Team projects | | --list-project-files | --project-id <id> | Files in one project | | --list-team-project-files | none | Files across team projects | | --export-team-index | --output-dir <dir> | Created or updated figma-index.sqlite3 | | --refresh-index | optional --team <alias> | Updated persistent indexes for one or all configured teams | | --index-status | optional --team <alias> | Index timestamps, ages, counts, and files that could not be indexed | | --search-components | --name <query>; optional --team <alias> | Component sets and standalone components matching a name substring | | --preflight | optional --team <alias> | Token access, team access, and index-root validation | | --list-team-component-sets | none | Published team component sets | | --list-component-set-usages | --index-dir <dir> plus component set key/name | Compact screens/usages where a component set is used | | --inspect-component-set-responsive-usage | --index-dir <dir> plus component set key/name | Compact responsive usage groups and layout risks | | --list-file-pages | --file-key <key> | Pages in one file | | --list-file-component-sets | --file-key <key> | Component sets in one file | | --inspect-component-set-properties | --url <figma-url> or --file-key <key> --node-id <id> plus component set key/name | Nested component-set properties | | --inspect-component-set | --url <figma-url> or --file-key <key> --node-id <id> plus component set key/name | Raw COMPONENT_SET node | | --inspect-team-component-set | --component-set-key <key> or --component-set-name <name> | Raw published component set | | --inspect-file-node | --url <figma-url> or --file-key <key> --node-id <id> | Raw file node | | --build-component-set-spec | --input <path> | Compact local component-set spec | | --build-component-set-pseudocode | --input <path> | Local component-set contract files | | --export-contract | --output-dir <dir> plus URL or file/node ref | Auto-detected section index or component-set, frame, or component contracts | | --export-component-set | --output-dir <dir> plus URL or component set key/name | Component-set contracts | | --export-node-contract | --output-dir <dir> plus URL or file/node ref | Frame or standalone component contracts | | --verify-component-contract | --contract-dir <dir> | Component-set lock verification | | --verify-component-lock | --lock-file <path> | Single component-set lock verification without contract artifacts | | --verify-node-contract | --contract-dir <dir> | Frame/component lock verification |

Common optional flags:

• --json prints JSON instead of YAML, or writes JSON data artifacts for export commands. Lock files remain YAML and structure files remain DSL. --json is not supported with --export-team-index.
• --team-components <path> is supported by local component-set build commands.
• --variables <path> resolves Figma variable aliases. Without it, exports still succeed and print a warning that aliases remain unresolved.
• --team <alias> selects one entry from FIGMA_TEAMS. Omit it on managed index commands to operate on every configured team.
• --index-root <dir> overrides FIGMA_INDEX_ROOT for managed indexes.
• --export-preview, --preview-format png|svg, and --preview-scale <scale> write a root preview image next to exported contracts.
• --export-assets attempts to write one SVG per component-set variant. It is supported by --export-component-set and by --export-contract when the target is a COMPONENT_SET. Runtime component sets with text, boolean, or instance-swap props are exported as normal contracts and print a warning instead of failing. With --export-contract, the flag is ignored for FRAME and standalone COMPONENT targets.
• --export-nested-assets writes selected nested nodes as sidecar assets. Use --asset-node-id <id> or --asset-include-regex <regex> to choose nodes. --asset-format svg|png, --asset-scale <scale>, --asset-node-types <csv>, and --asset-max <number> refine nested asset export.
• --screen-similarity-threshold <number> and --screen-size-tolerance <px> refine screen grouping for --export-team-index.
• --index-dir <dir> is required by local component usage lookup commands.
• --screen-group <name-or-id> filters local usage lookup to one responsive screen group.
• --full prints full local usage records for lookup commands. By default, lookup output is compacted for LLM context and omits verbose ancestor chains and risk evidence messages.

Discovery

npx . --list-team-projects
npx . --list-project-files --project-id <project_id>
npx . --list-team-project-files
npx . --export-team-index --output-dir tmp/figma-index
npx . --refresh-index
npx . --index-status --json
npx . --search-components --name Button --json
npx . --preflight --json
npx . --list-team-component-sets
npx . --list-component-set-usages --index-dir tmp/figma-index --component-set-name RatingsDivider
npx . --inspect-component-set-responsive-usage --index-dir tmp/figma-index --component-set-name RatingsDivider
npx . --list-file-pages --file-key <file_key>
npx . --list-file-component-sets --file-key <file_key>

--export-team-index writes a compact SQLite database at <output-dir>/figma-index.sqlite3. The database includes component sets, standalone components, screens, screen groups, component-set usages, ancestor layout context, and layout risks, with indexes optimized for local lookup commands. Rerunning it updates the database in place, as described under index refreshes. Local lookup commands print compact summaries by default; pass --full when you need the raw stored usage records. If the file is committed in a consuming repo, store it in Git LFS:

.agents/design/figma-index/*.sqlite3 filter=lfs diff=lfs merge=lfs -text

Detailed contracts are exported later with --export-contract, --export-component-set, or --export-node-contract. Component-set exports also write <Name>.component-set.layout-risks.{yaml,json} when the exported set contains constrained fill/stretch patterns that need manual layout review.

Persistent multi-team indexes

--refresh-index stores one figma-index.sqlite3 per configured team under FIGMA_INDEX_ROOT, which defaults to ~/.figma-inspect-cli/indexes. This path is outside the npm package, so package upgrades and reinstalls do not remove the indexes. Each database records generatedAt when a refresh finishes; an index without it is still being built or was interrupted and holds the files indexed so far.

Index refreshes

Both index commands update an existing database in place. A file is downloaded only when its name, project, or Figma modification time changed; every file is downloaded again when the screen-grouping options or the CLI's indexed rows changed. Files removed from the team are dropped. Each file is written in its own transaction, so an interrupted refresh keeps every completed file and the next run continues with the rest. Progress lines on stderr name each downloaded file.

Figma rate-limits file downloads (Tier 1 of its REST API limits, 10–20 requests per minute for Dev and Full seats), so the first build of a large team can take tens of minutes; the CLI waits out 429 responses. A file over 128 MiB, or one Figma refuses as too large, is downloaded page by page and then in batches of child nodes, which keeps memory use bounded.

Files that Figma's file endpoint cannot read, such as FigJam boards or files whose owner disabled exporting, are recorded without content and skipped until they change. A file that still fails keeps its previous rows and is retried by the next refresh. With several teams, a team whose refresh fails is reported with error and the remaining teams continue. Failed files appear under failedFiles in the JSON output, on stderr, and in --index-status; the command exits with status 1 after indexing everything else.

The CLI does not run a scheduler. Callers can check ageSeconds and run --refresh-index when an index is missing or older than their freshness policy (the companion plugin uses 24 hours). --search-components searches the local indexes only, using a case-insensitive name substring across every configured team unless --team narrows the search.

Inspect

npx . --inspect-component-set-properties --file-key <file_key> --node-id <node_id> --component-set-name Cell
npx . --inspect-component-set --file-key <file_key> --node-id <node_id> --component-set-key <component_set_key>
npx . --inspect-component-set --url "https://www.figma.com/design/<file_key>/<name>?node-id=<node_id>"
npx . --inspect-team-component-set --component-set-name Toast
npx . --inspect-file-node --file-key <file_key> --node-id <node_id>
npx . --inspect-file-node --url "https://www.figma.com/design/<file_key>/<name>?node-id=<node_id>"

Local Build

Build local artifacts from a saved raw COMPONENT_SET JSON file:

npx . --inspect-component-set ... --json > tmp/Toast.json
npx . --build-component-set-spec --input tmp/Toast.json --variables tmp/cp-ds-styles-variables-local.json
npx . --build-component-set-spec --input tmp/Toast.json --variables tmp/cp-ds-styles-variables-local.json --team-components tmp/ComponentSets.json
npx . --build-component-set-pseudocode --input tmp/Toast.json --variables tmp/cp-ds-styles-variables-local.json --output-dir tmp

Export

Exports by URL or file/node reference use the selected node directly and do not require a team or scan team projects. Team selection is needed only to discover a component set by name or key. Component metadata includes source file/project locations only when those are known; remote dependencies are never assigned the selected node's file location.

--export-contract auto-detects supported node types:

• SECTION writes section.index.yaml with every direct child's identity, bounds, and contract directory where supported. Frames, components, component sets, and nested sections get separate contracts in node-ID directories. section.source.json preserves the complete original node response, including annotations and other children without contracts. Nested indexes reference that same source. --json writes JSON indexes and child data artifacts. Preview and nested-asset options apply to the selected section once.

• COMPONENT_SET writes <Name>.component-set.{visuals,geometry,meta}.yaml, <Name>.component-set.structure.dsl, and <Name>.component-set.lock.yaml.

• FRAME writes <Name>.frame.{visuals,geometry,meta}.yaml, <Name>.frame.structure.dsl, and <Name>.frame.lock.yaml.

• Standalone COMPONENT writes <Name>.component.{visuals,geometry,meta}.yaml, <Name>.component.structure.dsl, and <Name>.component.lock.yaml.

npx . --export-contract --output-dir tmp --variables tmp/cp-ds-styles-variables-local.json --url "https://www.figma.com/design/<file_key>/<name>?node-id=<node_id>"
npx . --export-contract --output-dir tmp --variables tmp/cp-ds-styles-variables-local.json --file-key <file_key> --node-id <node_id>
npx . --export-component-set --output-dir tmp --variables tmp/cp-ds-styles-variables-local.json --component-set-name RoadmapHeader
npx . --export-component-set --output-dir tmp --variables tmp/cp-ds-styles-variables-local.json --url "<component_set_url>"
npx . --export-node-contract --output-dir tmp --variables tmp/cp-ds-styles-variables-local.json --url "<frame_or_component_url>"

URL-based exports also write import-notes.md.

Assets And Previews

npx . --export-contract --output-dir tmp --variables tmp/cp-ds-styles-variables-local.json --url "<figma_url>" --export-preview
npx . --export-contract --output-dir tmp --variables tmp/cp-ds-styles-variables-local.json --url "<figma_url>" --export-preview --preview-format svg
npx . --export-component-set --output-dir tmp --variables tmp/cp-ds-styles-variables-local.json --component-set-name ProfileStreakIcon --export-assets
npx . --export-node-contract --output-dir tmp --variables tmp/cp-ds-styles-variables-local.json --url "<frame_url>" --export-nested-assets --asset-node-id <nested_node_id>
npx . --export-node-contract --output-dir tmp --variables tmp/cp-ds-styles-variables-local.json --url "<frame_url>" --export-nested-assets --asset-include-regex "icon|logo" --asset-node-types INSTANCE,VECTOR --asset-format svg --asset-format png

Variant asset export writes <Name>.assets/*.svg and references those paths from meta.assets when the component set can be flattened to variant SVGs. Nested asset export writes <Name>.assets/*.{svg,png} plus <Name>.<kind>.nested-assets.yaml.

Verify

npx . --verify-component-contract --contract-dir tmp
npx . --verify-component-contract --contract-dir tmp --component-name Cell --json
npx . --verify-component-lock --lock-file tmp/Cell.component-set.lock.yaml --json
npx . --verify-node-contract --contract-dir tmp
npx . --verify-node-contract --contract-dir tmp --node-name Settings --json