pp-figma

Figma — Printing Press CLI

前提条件：CLI をインストールする

このスキルは figma-pp-cli バイナリを使用します。このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。 インストールされていない場合は、先にインストールしてください。

1. Printing Press インストーラーを使用してインストールします。macOS/Linux ではバイナリのインストール先はデフォルトで $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin です。

   npx -y @mvanhorn/printing-press-library install figma --cli-only
   

2. 確認します：figma-pp-cli --version
3. 報告されたインストールディレクトリが、このスキルを実行するエージェント／ランタイムの $PATH に含まれていることを確認します。

npx によるインストールに失敗した場合（Node がない、オフラインなど）は、Go からの直接インストールに切り替えてください（Go 1.26.6 以降が必要です）。この方法では $GOPATH/bin（デフォルトは $HOME/go/bin）にインストールされるため、代わりにそのディレクトリを $PATH に追加してください。

go install github.com/mvanhorn/printing-press-library/library/productivity/figma/cmd/figma-pp-cli@latest

インストール後に --version が「command not found」と報告する場合、ランタイムから $PATH 上のバイナリディレクトリが見えていません。確認に成功するまで、スキルのコマンドを実行しないでください。

この CLI は、オフラインファーストでエージェントネイティブな Figma オペレーターです。すべての REST エンドポイントを Cobra コマンドとして取り込み、GLips のコンパクションパイプラインを移植してフレームの抽出結果が LLM のコンテキストウィンドウに収まるようにし、さらに他のツールが統合していない分析プリミティブを追加します。これには、ファイル横断のコメント監査、古いコンポーネントの孤立項目検索、ファイルバージョン間のセマンティックトークン差分、CI 用の決定的なファイルフィンガープリント、Webhook 配信の再生が含まれます。

この CLI を使う場面

エージェントやエンジニアが、ピクセルではなくデータとして 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 が公開するすべての機能をカバーし、ダッシュボードにはないファイル横断の分析コマンドも追加します。

独自の機能

これらの機能は、この API を扱う他のツールでは利用できません。

エージェントネイティブな基盤機能

• frame extract — 単一のフレームを抽出し、簡略化したノードツリー、対象範囲内の変数、開発リソース、Code Connect マッピングを統合した、コンパクトでコード生成に使いやすいペイロードを生成します。

  AI エージェントがコード生成のために Figma フレームのコンテキストを必要とする際に、最初に呼び出します。生の 10MB ファイル応答ではなく、コンテキストウィンドウに収まるコンパクトなペイロードを返します。

  figma-pp-cli frame extract abc123 --ids 1234-5678 --depth 4 --include variables,dev-resources --json
  

• dev-mode dump — 1 つのノードについて、開発リソースへのリンク、対象範囲内の変数、レンダリングのパーマリンク、Code Connect マッピングを統合した、持ち運び可能な Markdown バンドルを出力します。

  エージェントやエンジニアが、1 つのフレームの Dev Mode コンテキスト全体を 1 つの Markdown ブロブとして必要とする場合に使用します。デスクトップとのペアリングは不要です。

  figma-pp-cli dev-mode dump abc123 --node 1234-5678 --format md
  

• webhooks test — Figma の Webhook リクエストログを取得し、保存済みのペイロードを（元のヘッダーと HMAC を含めて）任意のターゲット URL に対して再生します。

  新しい Webhook ハンドラーを反復テストする際に使用します。上流のイベントを再発生させることなく、昨日失敗した配信をローカルサーバーに対して再生できます。

  figma-pp-cli webhooks test wh_abc --replay-failed --target-url https://localhost:3000/figma
  

蓄積するローカル状態

• comments-audit — 同期済みのチームファイル全体から未解決のコメントを集約し、経過日数とグループ化によるフィルターを適用します。

  デザインレビュー前の月曜朝に実行すると、チーム全体の古い未解決スレッドをすべて表示できます。

  figma-pp-cli comments-audit --older-than 14d --group-by file,author --json
  

• orphans — チームライブラリの公開リストとライブラリアナリティクスの使用状況データを結合し、指定期間に使用されていない公開済みのライブラリエンティティ（コンポーネント、スタイル、変数）を見つけます。

  四半期ごとのデザインシステム整理で最初に実行するコマンドです。廃止しても安全なエンティティの一覧を返します。

  figma-pp-cli orphans 12345 --kind component,style,variable --window 30d --json
  

• tokens diff — 2 つのファイルバージョン間で Figma の変数をモード対応で比較し、Markdown または JSON の変更セットを出力します。

  デザイントークンの PR をマージする前に実行すると、前回のリリース以降に Figma で実際に変更された内容を確認できます。

  figma-pp-cli tokens diff abc123 --from v1.0.0 --to HEAD --format md
  

• fingerprint — Figma ファイルのトークン、コンポーネント、スタイルの構成を安定したハッシュ値にします。--expect と一致しない場合は、ゼロ以外の終了コードを返します。

  これを CI に組み込むと、上流の Figma ファイルのデザインシステム構成がコミット済みのスナップショットから変わったときに、ビルドを失敗させることができます。

  figma-pp-cli fingerprint abc123 --expect sha256:a1b2c3...
  

• variables explain — ファイル内で指定した変数を参照しているすべてのノードとコンポーネントを、フラットな一覧で表示します。

  変数の名前変更や廃止を計画する際に最初に実行します。変更に着手する前に、その影響範囲を確認できます。

  figma-pp-cli variables explain abc123 --variable color/brand/primary --json
  

コマンドリファレンス

activity-logs — 組織管理者としてアクティビティログを取得します。

• figma-pp-cli activity-logs — アクティビティログイベントの一覧を返します

component-sets — 公開済みコンポーネントセットの情報を取得します。

• figma-pp-cli component-sets <key> — キーを指定して、公開済みコンポーネントセットのメタデータを取得します。

components — 公開済みコンポーネントの情報を取得します。

• figma-pp-cli components <key> — キーを指定して、コンポーネントのメタデータを取得します。

dev-resources — Figma Dev Mode の開発リソースを操作します。

• figma-pp-cli dev-resources post — 複数のファイルにまたがる開発リソースを一括作成します。
• figma-pp-cli dev-resources put — 複数のファイルにまたがる開発リソースを一括更新します。

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 オブジェクトとして返します。

images — 画像を管理します

• figma-pp-cli images <file_key> — ファイルから画像をレンダリングします。

me — 自分の情報を管理します

• figma-pp-cli me — 現在認証されているユーザーの情報を返します。

oembed — Figma ファイルおよび公開済み Make の oEmbed データを取得します。

• figma-pp-cli oembed — [oEmbed specification](https://oembed に従って、Figma ファイルまたは公開済み Make サイトの URL の oEmbed データを返します。

payments — コミュニティリソースの購入情報を取得します。

• figma-pp-cli payments — プラグイン、ウィジェット、またはコミュニティファイルに関するユーザーの支払い情報を照会する方法は 2 つあります。

projects — チーム内のプロジェクトとファイルの情報を取得します。

styles — 公開済みスタイルの情報を取得します。

• figma-pp-cli styles <key> — キーを指定して、スタイルのメタデータを取得します。

teams — チームを管理します

webhooks — チーム管理者としてチームの Webhook を操作します。

• figma-pp-cli webhooks delete — 指定された Webhook を削除します。この操作は取り消せません。
• figma-pp-cli webhooks get — コンテキストまたはプランに対応する Webhook が存在する場合、その一覧を返します。
• figma-pp-cli webhooks get-webhookid — ID を指定して Webhook を取得します。
• figma-pp-cli webhooks post — イベントが発生したときに指定のエンドポイントを呼び出す新しい Webhook を作成します。
• figma-pp-cli webhooks put — ID を指定して Webhook を更新します。

適切なコマンドを見つける

実行したいことは分かっていても、どのコマンドを使うか分からない場合は、CLI に直接尋ねてください。

figma-pp-cli which "<capability in your own words>"

which は、自然言語による機能の問い合わせを、この CLI の厳選された機能インデックスから最適なコマンドに対応付けます。終了コード 0 は少なくとも 1 件の一致があったことを示し、終了コード 2 は確信を持てる一致がなかったことを示します。その場合は --help に切り替えるか、より絞り込んだ問い合わせを使用してください。

レシピ

AI コード生成プロンプト用にフレームを抽出する

figma-pp-cli frame extract abc123 --ids 1234-5678 --depth 4 --include variables,dev-resources --json --select 'simplifiedNodeCount,nodes,variables,devResources'

最強のコマンドです。簡略化したノードツリー、スコープ内のすべての変数、すべての開発リソースへのリンク、圧縮率を示すノード数を含むコンパクトな JSON を返します。Claude や Cursor にそのまま貼り付けられます。

2 週間以上前の未解決コメントを検索する

figma-pp-cli comments-audit --older-than 14d --group-by file,author --json --select 'file,author,count,oldest_at'

同期後、コメントテーブルを走査し、ファイルと作成者ごとに集計します。jq に渡せば、Slack 用の Markdown を作成できます。

チームライブラリ全体の孤立したエンティティをクリーンアップする

figma-pp-cli orphans 12345 --kind component,style,variable --window 30d --json

チームライブラリの公開リストと過去 30 日間の使用状況分析を結合し、公開済みで使用回数がゼロのエンティティのリストを出力します。これらが非推奨化の候補です。Enterprise ティアが必要です。

2 つのファイルバージョン間でデザイントークンを比較する

figma-pp-cli tokens diff abc123 --from v1.0.0 --to HEAD --format md

バージョン ID を解決し、それぞれの変数のスナップショットを取得して、追加・削除・名前変更・値変更されたトークンを一覧にした変更セットを Markdown で出力します。デザイントークンの PR をマージする前に実行してください。

失敗した Webhook 配信をローカルサーバーに再送する

figma-pp-cli webhooks test wh_abc --replay-failed --target-url http://localhost:3000/figma

/v2/webhooks/{id}/requests 経由でリクエストログを取得し、ステータスが 400 以上のものを絞り込み、取得したペイロードと元のヘッダーを使って各配信をローカル URL に再送します。（HMAC 署名の再付与にはまだ対応していないため、テスト時にはハンドラーが署名なしの再送を受け付ける必要があります。）

認証の設定

Figma は 2 つの認証方式をサポートしています。個人利用や自動化には Personal Access Token（ヘッダー X-Figma-Token、プレフィックス figd_）、/v1/me、/v1/activity_logs、/v1/developer_logs には OAuth 2.0（Authorization: Bearer）を使用します。FIGMA_API_TOKEN（PAT）または FIGMA_OAUTH2（OAuth Bearer）を設定すると、CLI が適切なヘッダーを自動的に選択します。OAuth を使うには figma-pp-cli auth login を実行し、PAT を保存するには設定ファイル経由で figma-pp-cli auth set-token を実行します。Doctor はレスポンスヘッダーから X-Figma-Plan-Tier と X-Figma-Rate-Limit-Type を表示します。

figma-pp-cli doctor を実行して設定を確認してください。

エージェントモード

任意のコマンドに --agent を追加します。次のオプションに展開されます：--json --compact --no-input --no-color --yes。

• パイプ可能 — JSON は stdout に、エラーは stderr に出力されます

• フィルタリング可能 — --select でフィールドを絞り込めます。ドット区切りのパスはネストされた構造をたどり、配列では各要素を順にたどります。冗長な API のコンテキストを小さく保つうえで重要です：

  figma-pp-cli activity-logs --agent --select id,name,status
  

• プレビュー可能 — --dry-run で送信せずにリクエストを表示します

• オフラインで使用可能 — sync/search コマンドは、利用可能な場合にローカルの SQLite ストアを使用できます

• 非対話型 — プロンプトを表示せず、すべての入力をフラグで指定します

• 明示的な再試行 — 既に存在するものの作成を成功として扱う場合にのみ --idempotent を使用し、削除対象が存在しない場合に成功として扱う場合にのみ --ignore-missing を使用してください

レスポンスエンベロープ

ローカルストアまたは API から読み取るコマンドは、出力を出所を示すエンベロープでラップします。

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

データの取得には .results を解析し、ライブデータかローカルデータかの確認には .meta.source を参照します。人間が読める N results (live) の要約は、stdout がターミナルであり、かつ機械処理用の形式フラグ（--json、--csv、--compact、--quiet、--plain、--select）が設定されていない場合にのみ stderr に出力されます。パイプやエージェントによる処理、および形式を明示した実行では、stdout に純粋な JSON が出力されます。

エージェントへのフィードバック

あなた（またはエージェント）がこの 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

エントリーは ~/.local/share/figma-pp-cli/feedback.jsonl にローカル保存されます。FIGMA_FEEDBACK_ENDPOINT が設定されており、かつ --send が渡されるか FIGMA_FEEDBACK_AUTO_SEND=true に設定されていない限り、POST されることはありません。デフォルトの動作はローカル保存のみです。

バグ報告ではなく、意外だったことを書いてください。短く、具体的に、1 行で。それが積み重なる部分です。

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は標準出力に加えて（または標準出力の代わりに）指定したシンクに送られるため、エージェントはコマンド結果を手動でパイプに渡さずにルーティングできます。次の3つのシンクがサポートされています。

シンク	効果
stdout	デフォルト。標準出力のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（一時ファイル＋リネーム）
webhook:<url>	出力本文を URL に POST します（--compact の場合は application/json または application/x-ndjson）

未対応のスキームは、サポート対象の一覧を示す構造化エラーとともに拒否されます。Webhook の失敗時はゼロ以外の終了コードを返し、URL と HTTP ステータスを標準エラー出力に記録します。

名前付きプロファイル

プロファイルは、複数回の実行で再利用できるフラグ値の保存セットです。スケジュールされたエージェントが、同じ設定で毎回同じコマンドを実行する場合に使用します。これは 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 の下に利用可能なすべてのプロファイルを一覧表示するため、情報を調べるエージェントは実行時にプロファイルを検出できます。

終了コード

コード	意味
0	成功
2	使用方法のエラー（引数が不正）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（上流の問題）
7	レート制限中（待機して再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します。

1. 空、help、または --help → figma-pp-cli --help の出力を表示します
2. install で始まる場合 → mcp で終わる場合は MCP のインストール。それ以外の場合は上記の「前提条件」を参照してください
3. それ以外 → 直接使用（CLI コマンドとして --agent を付けて実行します）

MCP サーバーのインストール

1. MCP サーバーをインストールします。

   go install github.com/mvanhorn/printing-press-library/library/productivity/figma/cmd/figma-pp-mcp@latest
   

2. Claude Code に登録します。

   claude mcp add figma-pp-mcp -- figma-pp-mcp
   

3. 確認します：claude mcp list

直接使用

1. インストールされているか確認します：which figma-pp-cli 見つからない場合は、インストールを提案します（このスキルの冒頭にある「前提条件」を参照してください）。
2. ユーザーの質問に最適なコマンドを、上記の「独自の機能」と「コマンドリファレンス」から選びます。
3. --agent フラグを付けて実行します。

   figma-pp-cli <command> [subcommand] [args] --agent
   

4. あいまいな場合は、サブコマンドのヘルプを確認します：figma-pp-cli <command> --help。