feat: read comment threads with figma-cli comments (opt-in REST, the Plugin API can't)

[Konstantinos019]

Hi Sil, thanks for figma-cli. We use it every day in Safe Mode to build and audit screens from code, and it has held up really well.

The problem

Design review on our side happens in Figma comments. An agent driving figma-cli had no way to see them: the Plugin API exposes annotations, stickies and layers, but not comment threads, and that is true in every connection mode (Yolo, Browser and Safe). We checked the offline figma-cli api index (no comment interface), the command list, and this repo's issues and PRs (nothing on comments), so as far as we can tell the CLI can't reach them today.

The only way to read comments is Figma's REST API, which is why this PR uses a personal access token. We know "no token needed" is a core point of figma-cli, so the change is strictly opt-in: nothing else in the CLI touches the token, and without one nothing is sent anywhere.

What it adds

figma-cli comments token set                  # hidden prompt, stored via credentials.js
figma-cli comments token status               # masked, never prints the token
figma-cli comments token clear
figma-cli comments list                       # unresolved threads, "screen › layer" per pin
figma-cli comments list --node <id> --all --json
figma-cli comments list --file <key or figma.com URL>

• Pins resolve to the real layer. A REST pin is usually the outermost frame plus an offset, so "pinned to Frame X" rarely says which screen a comment is about. The command asks the plugin to walk the offset down to the deepest visible layer under it (one eval for all pins).
• Works without a connection when --file is given: it still lists the threads, with node ids instead of layer names.

Security

• Uses the existing credentials.js helpers (saveKey / getKey / promptKeySecure / maskKey), the same way plugin keys are handled. FIGMA_ACCESS_TOKEN in the environment also works.
• The token is only sent to api.figma.com, only when comments list runs, and the only scopes needed are File content: Read and Comments: Read.
• SECURITY.md's "No Figma API key is involved" line is updated to describe this one exception honestly, and the README gets a short "The one exception: reading comments" section next to the MCP comparison.

One thing to check with you

plugin/manifest.json gets "enablePrivatePluginApi": true so that figma.fileKey is readable in Safe Mode, and comments list can find the open file on its own. If you'd rather not add that flag, it can go: --file covers the same case.

Tests

tests/comments.test.js covers the pure helpers (file-key parsing, threading, pins, labels, the generated plugin code). npm test: 555 passing. Also tried end to end in Safe Mode against a real file with ten comment threads.

If you'd prefer this outside core (say, as an optional plugin under plugins/), or with different naming, I'm happy to rework it.

🤖 Generated with Claude Code

[Konstantinos019]

Superseded by silships#55.