Back to Details

pp-figma

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
<!-- GENERATED FILE — DO NOT EDIT. This file is a verbatim mirror of library/productivity/figma/SKILL.md, regenerated post-merge by tools/generate-skills/. Hand-edits here are silently overwritten on the next regen. Edit the library/ source instead. See AGENTS.md "Generated artifacts: registry.json, cli-skills/". -->
<!-- 生成文件 — 请勿编辑。 本文件是library/productivity/figma/SKILL.md的精确镜像， 由tools/generate-skills/在合并后重新生成。此处的手动编辑会在下次生成时被自动覆盖。请修改library/下的源文件。 详见AGENTS.md中的"Generated artifacts: registry.json, cli-skills/"。 -->

Figma — Printing Press CLI

Figma — Printing Press CLI

Prerequisites: Install the CLI

前置条件：安装CLI

This skill drives the 
figma-pp-cli
binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:
  1. Install via the Printing Press installer:
    bash
    npx -y @mvanhorn/printing-press install figma --cli-only
  2. Verify: 
    figma-pp-cli --version
  3. Ensure 
    $GOPATH/bin
    (or 
    $HOME/go/bin
    ) is on 
    $PATH
    .
If the 
npx
install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):
bash
go install github.com/mvanhorn/printing-press-library/library/productivity/figma/cmd/figma-pp-cli@latest
If 
--version
reports "command not found" after install, the install step did not put the binary on 
$PATH
. Do not proceed with skill commands until verification succeeds.
本技能基于
figma-pp-cli
二进制文件运行。在调用本技能的任何命令之前，你必须确认CLI已安装。 如果未安装，请先执行以下步骤：
  1. 通过Printing Press安装器安装：
    bash
    npx -y @mvanhorn/printing-press install figma --cli-only
  2. 验证：
    figma-pp-cli --version
  3. 确保
    $GOPATH/bin
    （或
    $HOME/go/bin
    ）已添加到
    $PATH
    环境变量中。
如果
npx
安装失败（如未安装Node、离线等），可以直接通过Go安装（需要Go 1.26.3或更高版本）：
bash
go install github.com/mvanhorn/printing-press-library/library/productivity/figma/cmd/figma-pp-cli@latest
如果安装后执行
--version
提示“command not found”，说明安装步骤未将二进制文件添加到
$PATH
中。请在验证成功后再执行技能命令。

When to Use This CLI

何时使用该CLI

Use figma-pp-cli when an agent or engineer needs to reason about a Figma file as data — not pixels. It shines for codegen prompt context (
frame extract
, 
dev-mode dump
), design-system ops (
orphans
, 
tokens diff
, 
fingerprint
), comment hygiene (
comments-audit
), and webhook iteration (
webhooks test
). For interactive design work, the Figma desktop app is fine — figma-pp-cli covers everything Figma's REST API exposes and adds the cross-file analytical commands the dashboard hides.
当智能体或工程师需要将Figma文件作为数据而非像素来处理时，使用figma-pp-cli。它在代码生成提示上下文（
frame extract
、
dev-mode dump
）、设计系统运维（
orphans
、
tokens diff
、
fingerprint
）、评论管理（
comments-audit
）以及Webhook迭代（
webhooks test
）场景中表现出色。对于交互式设计工作，使用Figma桌面应用即可——figma-pp-cli覆盖了Figma REST API提供的所有功能，并添加了仪表盘隐藏的跨文件分析命令。

Unique Capabilities

独特功能

These capabilities aren't available in any other tool for this API.
这些功能是其他Figma API工具所不具备的。

Agent-native plumbing

智能体原生管道

  • frame extract
     — Extract a single frame as a compact codegen-ready payload that fuses simplified node tree, in-scope variables, dev resources, and Code Connect mappings.
    First call when an AI agent needs Figma frame context for code generation — returns a compact payload that fits in the context window instead of the raw 10MB file response.
    bash
    figma-pp-cli frame extract abc123 --ids 1234-5678 --depth 4 --include variables,dev-resources --json
  • dev-mode dump
     — Emit a portable Markdown bundle that fuses dev-resource links, variables in scope, render permalink, and Code Connect mapping for one node.
    Use when an agent or engineer needs the full Dev Mode context for one frame as a single Markdown blob — no Desktop pairing required.
    bash
    figma-pp-cli dev-mode dump abc123 --node 1234-5678 --format md
  • webhooks test
     — Pull Figma's webhook request log and replay stored payloads (with original headers and HMAC) against an arbitrary target URL.
    Use when iterating on a new webhook handler — replay yesterday's failed deliveries against your local server without re-triggering upstream events.
    bash
    figma-pp-cli webhooks test wh_abc --replay-failed --target-url https://localhost:3000/figma
  • frame extract
     —— 将单个框架提取为紧凑的、可用于代码生成的负载，融合简化的节点树、范围内的变量、开发资源和Code Connect映射。
    当AI智能体需要Figma框架上下文用于代码生成时，首先调用此命令——返回的紧凑负载可放入上下文窗口，而非原始的10MB文件响应。
    bash
    figma-pp-cli frame extract abc123 --ids 1234-5678 --depth 4 --include variables,dev-resources --json
  • dev-mode dump
     —— 生成便携的Markdown包，融合单个节点的开发资源链接、范围内的变量、渲染永久链接和Code Connect映射。
    当智能体或工程师需要单个框架的完整Dev Mode上下文作为单个Markdown blob时使用——无需依赖桌面应用。
    bash
    figma-pp-cli dev-mode dump abc123 --node 1234-5678 --format md
  • webhooks test
     —— 获取Figma的Webhook请求日志，并将存储的负载（包含原始头信息和HMAC）重放至任意目标URL。
    当迭代新的Webhook处理程序时使用——将昨天的失败请求重放至本地服务器，无需重新触发上游事件。
    bash
    figma-pp-cli webhooks test wh_abc --replay-failed --target-url https://localhost:3000/figma

Local state that compounds

可累积的本地状态

  • comments-audit
     — Aggregate unresolved comments across every synced team file with age and group-by filters.
    Run this on Monday morning before design review — surfaces every stale unresolved thread across the team.
    bash
    figma-pp-cli comments-audit --older-than 14d --group-by file,author --json
  • orphans
     — Find published library entities (components, styles, variables) with zero usage over a window by joining team-library publish list with library-analytics usage data.
    First command for the quarterly design-system cleanup — returns the list of entities safe to deprecate.
    bash
    figma-pp-cli orphans 12345 --kind component,style,variable --window 30d --json
  • tokens diff
     — Diff Figma variables across two file versions with mode-awareness; emits a Markdown or JSON change set.
    Run before merging a design-tokens PR to see what actually changed in Figma since the last release.
    bash
    figma-pp-cli tokens diff abc123 --from v1.0.0 --to HEAD --format md
  • fingerprint
     — Stable hash of a Figma file's token + component + style surface; exits non-zero if --expect doesn't match.
    Wire this into CI to fail builds when the upstream Figma file's design-system surface drifts from the committed snapshot.
    bash
    figma-pp-cli fingerprint abc123 --expect sha256:a1b2c3...
  • variables explain
     — Flat list of every node and component that references a given variable across a file.
    First call when planning a variable rename or deprecation — shows the blast radius before you touch anything.
    bash
    figma-pp-cli variables explain abc123 --variable color/brand/primary --json
  • comments-audit
     —— 聚合所有同步团队文件中未解决的评论，并支持按时间和分组筛选。
    在周一设计评审前运行此命令——可展示团队中所有未处理的陈旧评论线程。
    bash
    figma-pp-cli comments-audit --older-than 14d --group-by file,author --json
  • orphans
     —— 通过将团队库发布列表与库分析使用数据关联，查找指定时间段内零使用的已发布库实体（组件、样式、变量）。
    季度设计系统清理时首先执行此命令——返回可安全弃用的实体列表。
    bash
    figma-pp-cli orphans 12345 --kind component,style,variable --window 30d --json
  • tokens diff
     —— 对比两个文件版本间的Figma变量，支持模式识别；输出Markdown或JSON格式的变更集。
    在合并设计令牌PR前运行此命令，查看自上次发布以来Figma中的实际变更。
    bash
    figma-pp-cli tokens diff abc123 --from v1.0.0 --to HEAD --format md
  • fingerprint
     —— 生成Figma文件令牌+组件+样式表面的稳定哈希值；如果与
    --expect
    指定的值不匹配，则返回非零退出码。
    将此命令集成到CI流程中，当上游Figma文件的设计系统表面与提交的快照不一致时，使构建失败。
    bash
    figma-pp-cli fingerprint abc123 --expect sha256:a1b2c3...
  • variables explain
     —— 列出文件中引用指定变量的所有节点和组件。
    在计划变量重命名或弃用时首先调用此命令——在修改前展示影响范围。
    bash
    figma-pp-cli variables explain abc123 --variable color/brand/primary --json

Command Reference

命令参考

activity-logs — Get activity logs as an organization admin.
  • figma-pp-cli activity-logs
    — Returns a list of activity log events
component-sets — Get information about published component sets.
  • figma-pp-cli component-sets <key>
    — Get metadata on a published component set by key.
components — Get information about published components.
  • figma-pp-cli components <key>
    — Get metadata on a component by key.
dev-resources — Interact with dev resources in Figma Dev Mode.
  • figma-pp-cli dev-resources post
    — Bulk create dev resources across multiple files. Dev resources that are successfully created will show up in the...
  • figma-pp-cli dev-resources put
    — Bulk update dev resources across multiple files. Ids for dev resources that are successfully updated will show up in...
developer-logs — Get developer logs for REST API and MCP server requests in an organization.
  • figma-pp-cli developer-logs
    — Returns a list of developer log entries for REST API and MCP server requests made within the organization. This...
figma-analytics — Manage figma analytics
  • figma-pp-cli figma-analytics get-library-component-actions
    — Returns a list of library analytics component actions data broken down by the requested dimension.
  • figma-pp-cli figma-analytics get-library-component-usages
    — Returns a list of library analytics component usage data broken down by the requested dimension.
  • figma-pp-cli figma-analytics get-library-style-actions
    — Returns a list of library analytics style actions data broken down by the requested dimension.
  • figma-pp-cli figma-analytics get-library-style-usages
    — Returns a list of library analytics style usage data broken down by the requested dimension.
  • figma-pp-cli figma-analytics get-library-variable-actions
    — Returns a list of library analytics variable actions data broken down by the requested dimension.
  • figma-pp-cli figma-analytics get-library-variable-usages
    — Returns a list of library analytics variable usage data broken down by the requested dimension.
files — Get file JSON, images, and other file-related content.
  • figma-pp-cli files <file_key>
    — Returns the document identified by 
    file_key
    as a JSON object. The file key can be parsed from any Figma file url:...
images — Manage images
  • figma-pp-cli images <file_key>
    — Renders images from a file. If no error occurs, 
    'images'
    will be populated with a map from node IDs to URLs of the...
me — Manage me
  • figma-pp-cli me
    — Returns the user information for the currently authenticated user.
oembed — Get oEmbed data for Figma files and published Makes.
  • figma-pp-cli oembed
    — Returns oEmbed data for a Figma file or published Make site URL, following the [oEmbed...
payments — Get purchase information for your Community resources.
  • figma-pp-cli payments
    — There are two methods to query for a user's payment information on a plugin, widget, or Community file. The first...
projects — Get information about projects and files in teams.
styles — Get information about published styles.
  • figma-pp-cli styles <key>
    — Get metadata on a style by key.
teams — Manage teams
webhooks — Interact with team webhooks as a team admin.
  • figma-pp-cli webhooks delete
    — Deletes the specified webhook. This operation cannot be reversed.
  • figma-pp-cli webhooks get
    — Returns a list of webhooks corresponding to the context or plan provided, if they exist. For plan, the webhooks for...
  • figma-pp-cli webhooks get-webhookid
    — Get a webhook by ID.
  • figma-pp-cli webhooks post
    — Create a new webhook which will call the specified endpoint when the event triggers. By default, this webhook will...
  • figma-pp-cli webhooks put
    — Update a webhook by ID.
activity-logs —— 作为组织管理员获取活动日志。
  • figma-pp-cli activity-logs
    —— 返回活动日志事件列表
component-sets —— 获取已发布组件集的信息。
  • figma-pp-cli component-sets <key>
    —— 通过key获取已发布组件集的元数据。
components —— 获取已发布组件的信息。
  • figma-pp-cli components <key>
    —— 通过key获取组件的元数据。
dev-resources —— 与Figma Dev Mode中的开发资源交互。
  • figma-pp-cli dev-resources post
    —— 在多个文件中批量创建开发资源。创建成功的开发资源将显示在……
  • figma-pp-cli dev-resources put
    —— 在多个文件中批量更新开发资源。更新成功的开发资源ID将显示在……
developer-logs —— 获取组织中REST API和MCP服务器请求的开发者日志。
  • figma-pp-cli developer-logs
    —— 返回组织内发起的REST API和MCP服务器请求的开发者日志条目列表。此……
figma-analytics —— 管理Figma分析数据
  • figma-pp-cli figma-analytics get-library-component-actions
    —— 返回按请求维度拆分的库分析组件操作数据列表。
  • figma-pp-cli figma-analytics get-library-component-usages
    —— 返回按请求维度拆分的库分析组件使用数据列表。
  • figma-pp-cli figma-analytics get-library-style-actions
    —— 返回按请求维度拆分的库分析样式操作数据列表。
  • figma-pp-cli figma-analytics get-library-style-usages
    —— 返回按请求维度拆分的库分析样式使用数据列表。
  • figma-pp-cli figma-analytics get-library-variable-actions
    —— 返回按请求维度拆分的库分析变量操作数据列表。
  • figma-pp-cli figma-analytics get-library-variable-usages
    —— 返回按请求维度拆分的库分析变量使用数据列表。
files —— 获取文件JSON、图片及其他文件相关内容。
  • figma-pp-cli files <file_key>
    —— 返回由
    file_key
    标识的文档，格式为JSON对象。文件key可从任意Figma文件URL中解析：……
images —— 管理图片
  • figma-pp-cli images <file_key>
    —— 从文件中渲染图片。如果无错误发生，
    'images'
    将填充节点ID到图片URL的映射……
me —— 管理当前用户信息
  • figma-pp-cli me
    —— 返回当前已认证用户的信息。
oembed —— 获取Figma文件和已发布Makes的oEmbed数据。
  • figma-pp-cli oembed
    —— 返回Figma文件或已发布Make站点URL的oEmbed数据，遵循[oEmbed……
payments —— 获取社区资源的购买信息。
  • figma-pp-cli payments
    —— 有两种方法查询用户对插件、组件或社区文件的支付信息。第一种……
projects —— 获取团队中的项目和文件信息。
styles —— 获取已发布样式的信息。
  • figma-pp-cli styles <key>
    —— 通过key获取样式的元数据。
teams —— 管理团队
webhooks —— 作为团队管理员与团队Webhook交互。
  • figma-pp-cli webhooks delete
    —— 删除指定的Webhook。此操作不可撤销。
  • figma-pp-cli webhooks get
    —— 返回与提供的上下文或计划对应的Webhook列表（如果存在）。对于计划，Webhook……
  • figma-pp-cli webhooks get-webhookid
    —— 通过ID获取Webhook。
  • figma-pp-cli webhooks post
    —— 创建新的Webhook，当事件触发时将调用指定的端点。默认情况下，此Webhook将……
  • figma-pp-cli webhooks put
    —— 通过ID更新Webhook。

Finding the right command

查找合适的命令

When you know what you want to do but not which command does it, ask the CLI directly:
bash
figma-pp-cli which "<capability in your own words>"
which
resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 
0
means at least one match; exit code 
2
means no confident match — fall back to 
--help
or use a narrower query.
当你知道要执行的操作但不知道对应的命令时，可直接询问CLI：
bash
figma-pp-cli which "<用你自己的话描述功能>"
which
命令会将自然语言的功能查询解析为CLI精选功能索引中最匹配的命令。退出码
0
表示至少有一个匹配项；退出码
2
表示没有确定的匹配项——此时可使用
--help
或缩小查询范围。

Recipes

使用示例

Extract a frame for an AI codegen prompt

为AI代码生成提示提取框架

bash
figma-pp-cli frame extract abc123 --ids 1234-5678 --depth 4 --include variables,dev-resources --json --select 'simplifiedNodeCount,nodes,variables,devResources'
The killer command. Returns a compact JSON with the simplified node tree, every variable in scope, every dev-resource link, and a node count showing the compression ratio — paste it directly into Claude or Cursor.
bash
figma-pp-cli frame extract abc123 --ids 1234-5678 --depth 4 --include variables,dev-resources --json --select 'simplifiedNodeCount,nodes,variables,devResources'
核心命令。返回包含简化节点树、所有范围内变量、所有开发资源链接以及显示压缩比的节点计数的紧凑JSON——可直接粘贴到Claude或Cursor中。

Find unresolved comments older than two weeks

查找超过两周未解决的评论

bash
figma-pp-cli comments-audit --older-than 14d --group-by file,author --json --select 'file,author,count,oldest_at'
After sync, walks the comments table and aggregates by file and author. Pipe through jq for Slack-ready Markdown.
bash
figma-pp-cli comments-audit --older-than 14d --group-by file,author --json --select 'file,author,count,oldest_at'
同步后，遍历评论表并按文件和作者聚合。可通过jq管道转换为适合Slack的Markdown格式。

Cleanup orphans across a team library

清理团队库中的孤立元素

bash
figma-pp-cli orphans 12345 --kind component,style,variable --window 30d --json
Joins team-library publish list with 30-day usage analytics; emits the list of entities published but with zero usages — your deprecation candidates. Enterprise-tier required.
bash
figma-pp-cli orphans 12345 --kind component,style,variable --window 30d --json
将团队库发布列表与30天使用分析数据关联；输出已发布但零使用的实体列表——这些是可弃用的候选对象。需要企业版权限。

Diff design tokens between two file versions

对比两个文件版本间的设计令牌

bash
figma-pp-cli tokens diff abc123 --from v1.0.0 --to HEAD --format md
Resolves the version ids, snapshots variables at each, and emits a Markdown change-set listing added/removed/renamed/value-changed tokens. Run before merging a design-tokens PR.
bash
figma-pp-cli tokens diff abc123 --from v1.0.0 --to HEAD --format md
解析版本ID，在每个版本处快照变量，输出Markdown格式的变更集，列出新增/删除/重命名/值变更的令牌。在合并设计令牌PR前运行此命令。

Replay failed webhook deliveries against a local server

将失败的Webhook请求重放至本地服务器

bash
figma-pp-cli webhooks test wh_abc --replay-failed --target-url http://localhost:3000/figma
Fetches the request log via /v2/webhooks/{id}/requests, filters status >= 400, and replays each delivery against your local URL with the original headers and HMAC re-signed under the webhook's passcode.
bash
figma-pp-cli webhooks test wh_abc --replay-failed --target-url http://localhost:3000/figma
通过/v2/webhooks/{id}/requests获取请求日志，筛选状态码>=400的请求，并将每个请求重放至本地URL，同时保留原始头信息和通过Webhook密码重新签名的HMAC。

Auth Setup

认证设置

Figma supports two auth modes: Personal Access Token (header X-Figma-Token, prefix figd_) for personal/automation use, and OAuth 2.0 (Authorization: Bearer) for /v1/me, /v1/activity_logs, and /v1/developer_logs. Set FIGMA_API_TOKEN (PAT) or FIGMA_OAUTH2 (OAuth Bearer); the CLI auto-routes to the right header. Run 
figma-pp-cli auth login
for OAuth, or just figma-pp-cli auth login for PAT. Doctor surfaces X-Figma-Plan-Tier and X-Figma-Rate-Limit-Type from response headers.
Run 
figma-pp-cli doctor
to verify setup.
Figma支持两种认证模式：个人访问令牌（请求头X-Figma-Token，前缀figd_）用于个人/自动化场景，OAuth 2.0（Authorization: Bearer）用于/v1/me、/v1/activity_logs和/v1/developer_logs接口。设置FIGMA_API_TOKEN（PAT）或FIGMA_OAUTH2（OAuth Bearer令牌）；CLI会自动选择正确的请求头。执行
figma-pp-cli auth login
进行OAuth认证，或直接执行
figma-pp-cli auth login
进行PAT认证。Doctor命令会从响应头中显示X-Figma-Plan-Tier和X-Figma-Rate-Limit-Type信息。
执行
figma-pp-cli doctor
验证设置。

Agent Mode

智能体模式

Add 
--agent
to any command. Expands to: 
--json --compact --no-input --no-color --yes
.
  • Pipeable — JSON on stdout, errors on stderr
  • Filterable — 
    --select
    keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:
    bash
    figma-pp-cli activity-logs --agent --select id,name,status
  • Previewable — 
    --dry-run
    shows the request without sending
  • Offline-friendly — sync/search commands can use the local SQLite store when available
  • Non-interactive — never prompts, every input is a flag
  • Explicit retries — use 
    --idempotent
    only when an already-existing create should count as success, and 
    --ignore-missing
    only when a missing delete target should count as success
在任何命令后添加
--agent
参数。等效于：
--json --compact --no-input --no-color --yes
。
  • 可管道化 —— 标准输出为JSON，错误输出到标准错误
  • 可筛选 —— 
    --select
    参数保留字段子集。点路径可深入嵌套结构；数组可遍历元素。对于冗长的API，这是保持上下文精简的关键：
    bash
    figma-pp-cli activity-logs --agent --select id,name,status
  • 可预览 —— 
    --dry-run
    参数显示请求但不发送
  • 离线友好 —— 同步/搜索命令在本地SQLite存储可用时可使用该存储
  • 非交互式 —— 从不提示，所有输入均通过标志参数提供
  • 显式重试 —— 仅当已存在的创建操作应视为成功时使用
    --idempotent
    ，仅当缺失的删除目标应视为成功时使用
    --ignore-missing

Response envelope

响应信封

Commands that read from the local store or the API wrap output in a provenance envelope:
json
{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}
Parse 
.results
for data and 
.meta.source
to know whether it's live or local. A human-readable 
N results (live)
summary is printed to stderr only when stdout is a terminal — piped/agent consumers get pure JSON on stdout.
从本地存储或API读取数据的命令会将输出包装在溯源信封中：
json
{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}
解析
.results
获取数据，
.meta.source
用于判断数据是实时的还是本地的。仅当标准输出为终端时，才会向标准错误输出人类可读的
N results (live)
摘要——管道/智能体消费者仅会在标准输出获取纯JSON。

Agent Feedback

智能体反馈

When you (or the agent) notice something off about this CLI, record it:
figma-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
figma-pp-cli feedback --stdin < notes.txt
figma-pp-cli feedback list --json --limit 10
Entries are stored locally at 
~/.figma-pp-cli/feedback.jsonl
. They are never POSTed unless 
FIGMA_FEEDBACK_ENDPOINT
is set AND either 
--send
is passed or 
FIGMA_FEEDBACK_AUTO_SEND=true
. Default behavior is local-only.
Write what surprised you, not a bug report. Short, specific, one line: that is the part that compounds.
当你（或智能体）发现该CLI存在问题时，可记录反馈：
figma-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
figma-pp-cli feedback --stdin < notes.txt
figma-pp-cli feedback list --json --limit 10
反馈条目存储在本地
~/.figma-pp-cli/feedback.jsonl
文件中。除非设置了
FIGMA_FEEDBACK_ENDPOINT
且传递了
--send
参数或
FIGMA_FEEDBACK_AUTO_SEND=true
，否则不会自动发送。默认行为仅存储在本地。
写下让你感到意外的点，而非正式的Bug报告。简短、具体、单行描述：这样的反馈才更有价值。

Output Delivery

输出交付

Every command accepts 
--deliver <sink>
. The output goes to the named sink in addition to (or instead of) stdout, so agents can route command results without hand-piping. Three sinks are supported:
SinkEffect
stdout
Default; write to stdout only
file:<path>
Atomically write output to 
<path>
(tmp + rename)
webhook:<url>
POST the output body to the URL (
application/json
or 
application/x-ndjson
when 
--compact
)
Unknown schemes are refused with a structured error naming the supported set. Webhook failures return non-zero and log the URL + HTTP status on stderr.
每个命令都支持
--deliver <sink>
参数。输出会除了（或替代）标准输出外，发送到指定的接收器，以便智能体无需手动管道即可路由命令结果。支持三种接收器：
接收器效果
stdout
默认值；仅写入标准输出
file:<path>
原子性地将输出写入
<path>
（先写入临时文件再重命名）
webhook:<url>
将输出体POST到指定URL（当使用
--compact
时，格式为
application/json
或
application/x-ndjson
）
不支持的协议会返回结构化错误，并列出支持的接收器类型。Webhook失败时返回非零退出码，并在标准错误中记录URL和HTTP状态码。

Named Profiles

命名配置文件

A profile is a saved set of flag values, reused across invocations. Use it when a scheduled agent calls the same command every run with the same configuration - HeyGen's "Beacon" pattern.
figma-pp-cli profile save briefing --json
figma-pp-cli --profile briefing activity-logs
figma-pp-cli profile list --json
figma-pp-cli profile show briefing
figma-pp-cli profile delete briefing --yes
Explicit flags always win over profile values; profile values win over defaults. 
agent-context
lists all available profiles under 
available_profiles
so introspecting agents discover them at runtime.
配置文件是一组保存的标志值，可在多次调用中复用。当定时智能体每次运行都使用相同配置调用同一命令时使用——即HeyGen的“Beacon”模式。
figma-pp-cli profile save briefing --json
figma-pp-cli --profile briefing activity-logs
figma-pp-cli profile list --json
figma-pp-cli profile show briefing
figma-pp-cli profile delete briefing --yes
显式标志始终优先于配置文件值；配置文件值优先于默认值。
agent-context
命令会在
available_profiles
下列出所有可用配置文件，以便智能体在运行时发现它们。

Exit Codes

退出码

CodeMeaning
0Success
2Usage error (wrong arguments)
3Resource not found
4Authentication required
5API error (upstream issue)
7Rate limited (wait and retry)
10Config error
代码含义
0成功
2使用错误（参数错误）
3资源未找到
4需要认证
5API错误（上游问题）
7速率限制（等待后重试）
10配置错误

Argument Parsing

参数解析

Parse 
$ARGUMENTS
:
  1. Empty, 
    help
    , or 
    --help
     → show 
    figma-pp-cli --help
    output
  2. Starts with 
    install
     → ends with 
    mcp
    → MCP installation; otherwise → see Prerequisites above
  3. Anything else → Direct Use (execute as CLI command with 
    --agent
    )
解析
$ARGUMENTS
：
  1. 为空、
    help
    或
    --help
     → 显示
    figma-pp-cli --help
    输出
  2. 以
    install
    开头     → 以
    mcp
    结尾 → MCP安装；否则 → 参见上方前置条件
  3. 其他情况 → 直接使用（添加
    --agent
    参数执行CLI命令）

MCP Server Installation

MCP服务器安装

Install the MCP binary from this CLI's published public-library entry or pre-built release, then register it:
bash
claude mcp add figma-pp-mcp -- figma-pp-mcp
Verify: 
claude mcp list
从该CLI的已发布公共库条目或预构建版本安装MCP二进制文件，然后注册：
bash
claude mcp add figma-pp-mcp -- figma-pp-mcp
验证：
claude mcp list

Direct Use

直接使用

  1. Check if installed: 
    which figma-pp-cli
    If not found, offer to install (see Prerequisites at the top of this skill).
  2. Match the user query to the best command from the Unique Capabilities and Command Reference above.
  3. Execute with the 
    --agent
    flag:
    bash
    figma-pp-cli <command> [subcommand] [args] --agent
  4. If ambiguous, drill into subcommand help: 
    figma-pp-cli <command> --help
    .
  1. 检查是否已安装：
    which figma-pp-cli
    如果未找到，提供安装选项（参见顶部的前置条件）。
  2. 将用户查询与上方独特功能和命令参考中最匹配的命令关联。
  3. 添加
    --agent
    参数执行：
    bash
    figma-pp-cli <command> [subcommand] [args] --agent
  4. 如果存在歧义，查看子命令帮助：
    figma-pp-cli <command> --help
    。

Known Gaps

已知局限

The following are documented limitations from Phase 5 live dogfood (152/165 = 92% pass), all environmental — the CLI itself is correct.
  • OAuth-only endpoints: 
    activity-logs
    , 
    developer-logs
    , and (in some scopes) 
    me
    require OAuth Bearer auth, not PAT. Set 
    FIGMA_OAUTH2
    to your OAuth Bearer token to use these. The CLI surfaces the API's 401 with a clear message.
  • oembed
    , 
    payments
    , 
    webhooks get
     require runtime parameters the printed-CLI dogfood matrix cannot synthesize (
    --url
    , 
    --user-id
    , 
    --context
    ). They work correctly when invoked with proper arguments.
  • comments-audit
     requires a populated local cache: run 
    figma-pp-cli sync --resources comments
    against a known file before invoking it. Returns an honest empty-store error otherwise.
  • orphans
     depends on Figma's Library Analytics API (Enterprise tier). On non-Enterprise plans it returns exit 0 with a clear "analytics data is empty" message rather than failing.
以下是Phase 5内部测试（152/165 = 92%通过率）中记录的局限性，均为环境因素导致——CLI本身功能正常。
  • 仅支持OAuth的端点：
    activity-logs
    、
    developer-logs
    以及（某些范围内的）
    me
    需要OAuth Bearer认证，而非PAT。设置
    FIGMA_OAUTH2
    为你的OAuth Bearer令牌即可使用这些端点。CLI会显示API返回的401错误及清晰提示信息。
  • oembed
    、
    payments
    、
    webhooks get
     需要运行时参数，而打印版CLI测试矩阵无法生成这些参数（
    --url
    、
    --user-id
    、
    --context
    ）。当使用正确参数调用时，它们可正常工作。
  • comments-audit
     需要填充本地缓存：在调用前，针对已知文件执行
    figma-pp-cli sync --resources comments
    。否则会返回明确的空存储错误。
  • orphans
     依赖Figma的库分析API（企业版）。在非企业版计划中，它会返回退出码0并显示清晰的“分析数据为空”消息，而非直接失败。