@todoforai/figma-api 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TODOforAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# figma-api
+
+Figma CLI — a subcommand-per-endpoint wrapper of the official **Figma REST API**,
+plus a **plugin bridge** for the canvas writes the REST API can't do.
+
+```bash
+figma-api auth figd_xxx                 # personal access token (or FIGMA_TOKEN env)
+figma-api me
+figma-api file https://figma.com/design/AbC123/My-File
+figma-api comment-add AbC123 "looks great" --node 1:2
+```
+
+Inspired by the Figma MCP servers (read design context) but extended to the full
+REST surface **and** to live canvas manipulation through a companion plugin.
+
+## Install
+
+```bash
+npm i -g @todoforai/figma-api    # or: bun add -g @todoforai/figma-api
+figma-api --help
+```
+
+## Auth
+
+Personal Access Token, stored in `~/.config/figma-api/credentials.json`, or passed
+via `FIGMA_TOKEN` (`FIGMA_API_TOKEN`) env. OAuth bearer tokens also work.
+
+```bash
+# https://www.figma.com/settings → Personal access tokens → Generate
+figma-api auth figd_xxx
+```
+
+Scopes: reads need `file_content:read`; writes need the matching scope
+(`file_comments:write`, `file_dev_resources:write`, `webhooks:write`,
+`file_variables:*` is Enterprise-only).
+
+## REST commands
+
+Every file command takes a raw file key **or** a Figma URL (`node-id` is parsed
+from the URL).
+
+Read: `me`, `file`, `nodes`, `file-meta`, `versions`, `images`, `image-fills`,
+`comments`, `reactions`, `projects`, `project-files`, `components`/`team-components`/
+`component`, `component-sets`/`team-component-sets`, `styles`/`team-styles`/`style`,
+`variables-local`/`variables-published`, `dev-resources`, `webhooks`/`webhook`/
+`webhook-requests`, `analytics`, `activity-logs`, `payments`, `oembed`.
+
+Write: `comment-add`/`comment-delete`, `reaction-add`/`reaction-delete`,
+`variables-modify`, `dev-resource-add`/`dev-resources-bulk-add`/`dev-resources-update`/
+`dev-resource-delete`, `webhook-create`/`webhook-update`/`webhook-delete`.
+
+Run `figma-api <command> --help` for parameters, scopes and examples.
+
+## Plugin bridge — canvas writes
+
+The REST API **cannot create canvas nodes** (frames/text/shapes) or edit variables
+off-Enterprise. The Figma **Plugin API** can. The bridge lets the CLI drive a small
+companion plugin:
+
+```
+figma-api run '...'  ──POST──▶  relay (figma-api bridge)  ◀──poll──  Figma plugin
+                                                          ──result─▶  (runs on canvas)
+```
+
+Setup:
+
+1. `figma-api bridge` — start the relay (keep it running).
+2. Figma **desktop** → Plugins → Development → **Import plugin from manifest** →
+   `plugin/manifest.json`. Run it, paste the relay URL, click **Connect**.
+3. Drive it from the CLI:
+
+```bash
+figma-api ping
+figma-api run 'const t = figma.createText(); await figma.loadFontAsync({family:"Inter",style:"Regular"}); t.characters="Hi from the CLI"; figma.currentPage.appendChild(t); return t'
+figma-api run @make-card.js
+```
+
+`run` executes arbitrary Figma Plugin API code (`figma` in scope, `await` and
+`return` supported), so it subsumes any draw/create helper.
+
+Cross-machine: `cloudflared tunnel --url http://localhost:8917` and paste that
+https URL into the plugin.
+
+> ⚠️ **Security:** the relay has no auth and `run` executes arbitrary code in your
+> Figma document. Only use it on a trusted machine/network; don't expose the tunnel
+> URL publicly or run code you don't trust.
+
+> Note: development (unpublished) plugins can only be imported in the **Figma
+> desktop app**, not the browser. Once published, the browser works too.
+
+## Why both REST and a plugin?
+
+| | REST API | Plugin bridge |
+|---|----------|---------------|
+| Files / nodes / images (read) | ✅ | ✅ |
+| Comments, dev resources, webhooks | ✅ | — |
+| Create frames / text / shapes | ❌ (no endpoint) | ✅ |
+| Edit variables off-Enterprise | ❌ (403) | ✅ |
+| Works headless / CI | ✅ | needs Figma open |
+
+## Reference
+
+- [figma/rest-api-spec](https://github.com/figma/rest-api-spec) — authoritative endpoint list.
+- [GLips/Figma-Context-MCP](https://github.com/GLips/Figma-Context-MCP) — read design-context MCP.
+- [Official Figma MCP](https://help.figma.com/hc/en-us/articles/32132100833559) — `mcp.figma.com`.
+- The bridge mirrors the architecture of community plugin bridges (e.g.
+  southleft/figma-console-mcp) but driven by a plain CLI instead of MCP.
+
+## Dev
+
+```bash
+bun install
+bun src/index.ts --help
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@todoforai/figma-api",
+  "version": "1.0.0",
+  "description": "Figma CLI — full REST API wrapper (files, comments, variables, webhooks…) plus a plugin bridge for canvas writes.",
+  "type": "module",
+  "bin": {
+    "figma-api": "src/index.ts"
+  },
+  "files": ["src", "plugin", "README.md", "LICENSE"],
+  "keywords": ["figma", "figma-api", "cli", "rest", "design", "plugin", "mcp"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/todoforai/figma-api.git"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
+  }
+}

package/plugin/code.js

@@ -0,0 +1,48 @@
+// figma-api bridge plugin. The UI (ui.html) long-polls the relay, forwards each
+// command here, this runs it and returns the result. The REST API can't create
+// canvas nodes or edit variables off-Enterprise — the Plugin API can, and the
+// figma-api CLI drives it through `figma-api run`.
+
+// Serialize a value for JSON transport: Figma nodes → {id,type,name}, recurse
+// plain objects/arrays, guard against cycles and unstringifiable values.
+function serialize(v, seen) {
+  if (v == null || typeof v === "boolean" || typeof v === "number" || typeof v === "string") return v;
+  if (typeof v === "bigint") return v.toString();
+  if (typeof v === "function" || typeof v === "symbol" || typeof v === "undefined") return undefined;
+  if (typeof v.id === "string" && typeof v.type === "string") return { id: v.id, type: v.type, name: v.name };
+  seen = seen || new Set();
+  if (seen.has(v)) return "[circular]";
+  seen.add(v);
+  if (Array.isArray(v)) return v.map((x) => serialize(x, seen));
+  const o = {};
+  for (const k of Object.keys(v)) { try { o[k] = serialize(v[k], seen); } catch (_) {} }
+  return o;
+}
+
+async function exec(cmd) {
+  if (cmd.op === "ping") {
+    return { pong: true, page: figma.currentPage.name, selection: figma.currentPage.selection.map((n) => n.id) };
+  }
+  if (cmd.op === "eval") {
+    // Run arbitrary Plugin API code. `figma` is in scope; code may use await
+    // and `return` a value. WARNING: this executes whatever the relay delivers.
+    const AsyncFunction = Object.getPrototypeOf(async function () {}).constructor;
+    const out = await new AsyncFunction("figma", cmd.code || "")(figma);
+    return { value: serialize(out) };
+  }
+  return { error: "unknown op: " + cmd.op };
+}
+
+figma.showUI(__html__, { width: 340, height: 320 });
+
+figma.ui.onmessage = async (msg) => {
+  if (msg.type === "exec") {
+    let result;
+    try { result = await exec(msg.cmd); }
+    catch (e) { result = { error: String((e && e.message) || e) }; }
+    figma.ui.postMessage({ type: "result", id: msg.cmd.id, result });
+    figma.notify(result.error ? "⚠️ " + result.error : "✅ " + msg.cmd.op);
+  } else if (msg.type === "close") {
+    figma.closePlugin();
+  }
+};

package/plugin/manifest.json

@@ -0,0 +1,13 @@
+{
+  "name": "figma-api bridge",
+  "id": "figma-api-bridge-todoforai",
+  "api": "1.0.0",
+  "main": "code.js",
+  "ui": "ui.html",
+  "editorType": ["figma"],
+  "documentAccess": "dynamic-page",
+  "networkAccess": {
+    "allowedDomains": ["*"],
+    "reasoning": "Long-polls the local figma-api relay to receive drawing commands from the CLI."
+  }
+}

package/plugin/ui.html

@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8" /></head>
+<body style="font:13px -apple-system,Segoe UI,Roboto,sans-serif;margin:0;padding:14px;color:#1a1a1a">
+  <h3 style="margin:0 0 6px">figma-api bridge</h3>
+  <p style="margin:0 0 10px;color:#666">Connect to the relay, then drive drawing from the <code>figma-api</code> CLI.</p>
+
+  <label style="display:block;margin:6px 0 2px;font-weight:600">Relay URL</label>
+  <input id="relay" value="http://localhost:8917" style="width:100%;box-sizing:border-box;padding:7px;border:1px solid #ccc;border-radius:6px" />
+
+  <div style="display:flex;gap:8px;margin-top:10px">
+    <button id="connect" style="flex:1;padding:9px;background:#1F6FEB;color:#fff;border:0;border-radius:8px;font-weight:600;cursor:pointer">Connect</button>
+    <button id="stop" style="flex:1;padding:9px;background:#eee;color:#333;border:0;border-radius:8px;font-weight:600;cursor:pointer">Stop</button>
+  </div>
+
+  <div id="status" style="margin-top:10px;color:#666;min-height:18px">Idle.</div>
+  <pre id="log" style="margin-top:8px;background:#0d1117;color:#8b949e;padding:8px;border-radius:6px;height:120px;overflow:auto;font-size:11px"></pre>
+
+  <script>
+    const $ = (id) => document.getElementById(id);
+    let running = false;
+    const log = (m) => { const l = $("log"); l.textContent += m + "\n"; l.scrollTop = l.scrollHeight; };
+
+    let resolveResult = null;
+    // plugin code → result → resolve the pending exec
+    onmessage = (e) => {
+      const m = e.data.pluginMessage;
+      if (m && m.type === "result" && resolveResult) { const r = resolveResult; resolveResult = null; r(m); }
+    };
+
+    async function loop() {
+      const relay = $("relay").value.replace(/\/$/, "");
+      $("status").textContent = "🟢 Connected — polling " + relay;
+      while (running) {
+        let cmd;
+        try {
+          cmd = await (await fetch(relay + "/poll")).json();
+        } catch (_) {
+          $("status").textContent = "🔴 Relay unreachable — retrying";
+          await new Promise((res) => setTimeout(res, 1500));
+          continue;
+        }
+        if (!cmd || !cmd.op) continue;
+        log("◀ " + cmd.op + " (" + cmd.id + ")");
+        // Run one command at a time and wait for its result (no overlap).
+        const m = await new Promise((resolve) => {
+          resolveResult = resolve;
+          parent.postMessage({ pluginMessage: { type: "exec", cmd } }, "*");
+        });
+        let bodyResult = m.result;
+        try { JSON.stringify(bodyResult); } catch (_) { bodyResult = { error: "result not serializable" }; }
+        log("▶ " + m.id + " " + JSON.stringify(bodyResult).slice(0, 60));
+        try {
+          await fetch(relay + "/result", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ id: m.id, result: bodyResult }) });
+        } catch (_) { log("⚠ result POST failed"); }
+      }
+      $("status").textContent = "⏹ Stopped.";
+    }
+
+    $("connect").onclick = () => { if (!running) { running = true; loop(); } };
+    $("stop").onclick = () => { running = false; };
+  </script>
+</body>
+</html>

package/src/api.ts

@@ -0,0 +1,105 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+const BASE = "https://api.figma.com";
+const CONFIG_DIR = join(homedir(), ".config", "figma-api");
+const CREDENTIALS_FILE = join(CONFIG_DIR, "credentials.json");
+
+export interface Credentials {
+  token: string;
+}
+
+export function saveCredentials(creds: Credentials): void {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CREDENTIALS_FILE, JSON.stringify(creds, null, 2) + "\n");
+}
+
+export function loadCredentials(): Credentials | null {
+  if (!existsSync(CREDENTIALS_FILE)) return null;
+  return JSON.parse(readFileSync(CREDENTIALS_FILE, "utf-8"));
+}
+
+export function credentialsExist(): boolean {
+  return existsSync(CREDENTIALS_FILE) || !!(process.env.FIGMA_TOKEN || process.env.FIGMA_API_TOKEN);
+}
+
+/** Resolve token from env (FIGMA_TOKEN / FIGMA_API_TOKEN) or saved credentials. */
+export function loadToken(): string {
+  const env = process.env.FIGMA_TOKEN || process.env.FIGMA_API_TOKEN;
+  if (env) return env;
+  const creds = loadCredentials();
+  if (!creds?.token) {
+    console.error("No token found. Run: figma-api auth <personal-access-token>");
+    console.error("Or set FIGMA_TOKEN env var. Create a token at https://www.figma.com/settings (Personal access tokens).");
+    process.exit(1);
+  }
+  return creds.token;
+}
+
+/** OAuth bearer tokens start with "figo"/"figu"; PATs use the X-Figma-Token header. */
+function authHeaders(): Record<string, string> {
+  const token = loadToken();
+  if (token.startsWith("Bearer ") || /^fig[ou]/.test(token)) {
+    return { Authorization: token.startsWith("Bearer ") ? token : `Bearer ${token}` };
+  }
+  return { "X-Figma-Token": token };
+}
+
+function buildUrl(path: string, params?: Record<string, unknown>): string {
+  const url = new URL(`${BASE}${path}`);
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      if (v === undefined || v === null || v === "") continue;
+      url.searchParams.set(k, String(v));
+    }
+  }
+  return url.toString();
+}
+
+async function request(method: string, path: string, params?: Record<string, unknown>, body?: unknown): Promise<Response> {
+  const init: RequestInit = { method, headers: { ...authHeaders() } };
+  if (body !== undefined) {
+    (init.headers as Record<string, string>)["Content-Type"] = "application/json";
+    init.body = JSON.stringify(body);
+  }
+  return fetch(buildUrl(path, params), init);
+}
+
+export const get = (path: string, params?: Record<string, unknown>) => request("GET", path, params);
+export const post = (path: string, body?: unknown, params?: Record<string, unknown>) => request("POST", path, params, body ?? {});
+export const put = (path: string, body?: unknown, params?: Record<string, unknown>) => request("PUT", path, params, body ?? {});
+export const del = (path: string, params?: Record<string, unknown>) => request("DELETE", path, params);
+
+/** Print a Response as pretty JSON (or raw text), exit non-zero on HTTP error. */
+export async function output(res: Response): Promise<void> {
+  const text = await res.text();
+  let data: unknown = text;
+  try { data = JSON.parse(text); } catch { /* keep raw */ }
+  if (!res.ok) {
+    console.error(`HTTP ${res.status} ${res.statusText}`);
+    console.error(typeof data === "string" ? data : JSON.stringify(data, null, 2));
+    process.exit(1);
+  }
+  console.log(typeof data === "string" ? data : JSON.stringify(data, null, 2));
+}
+
+/**
+ * Accept a raw file key or a Figma URL and return { fileKey, nodeId? }.
+ * URLs: https://www.figma.com/file|design|board/<KEY>/<name>?node-id=1-2
+ * node-id query uses "1-2" form; the API expects "1:2".
+ */
+export function parseFigmaTarget(input: string): { fileKey: string; nodeId?: string } {
+  const urlMatch = input.match(/figma\.com\/(?:file|design|board|proto)\/([A-Za-z0-9]+)/);
+  const fileKey = urlMatch ? urlMatch[1] : input;
+  let nodeId: string | undefined;
+  const nodeMatch = input.match(/[?&]node-id=([^&]+)/);
+  if (nodeMatch) nodeId = decodeURIComponent(nodeMatch[1]).replace(/-/g, ":");
+  return { fileKey, nodeId };
+}
+
+/** Read JSON from an inline string or a @file.json path. */
+export function readJsonArg(arg: string): unknown {
+  const raw = arg.startsWith("@") ? readFileSync(arg.slice(1), "utf-8") : arg;
+  return JSON.parse(raw);
+}

package/src/bridge.ts

@@ -0,0 +1,96 @@
+// Relay/bridge between the figma-api CLI and the Figma plugin.
+// The plugin can't be addressed directly, but it can poll over HTTP — so the CLI
+// enqueues commands here, the plugin long-polls /poll, executes them on the
+// canvas, and posts the result back to /result.
+//
+//   figma-api draw-* ──POST /cmd──▶  relay  ◀──GET /poll──  plugin
+//                                          ──POST /result─▶ (draws, returns ids)
+
+interface Cmd { id: string; op: string; [k: string]: unknown }
+
+const queue: Cmd[] = [];
+const resultWaiters = new Map<string, (v: unknown) => void>();
+const pollWaiters: ((c: Cmd | null) => void)[] = [];
+let lastSeen = 0;
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", "access-control-allow-origin": "*", "access-control-allow-headers": "*" },
+  });
+}
+
+export function startBridge(port: number): void {
+  Bun.serve({
+    port,
+    async fetch(req) {
+      const url = new URL(req.url);
+      if (req.method === "OPTIONS") return json({}, 204);
+
+      // Health / status
+      if (url.pathname === "/health") {
+        return json({ ok: true, queued: queue.length, pluginSeenMsAgo: lastSeen ? Date.now() - lastSeen : null });
+      }
+
+      // CLI → enqueue a command and wait for the plugin's result
+      if (url.pathname === "/cmd" && req.method === "POST") {
+        const body = (await req.json()) as Record<string, unknown>;
+        const id = crypto.randomUUID().slice(0, 8);
+        const cmd: Cmd = { id, op: String(body.op), ...body };
+        const waiter = pollWaiters.shift();
+        if (waiter) waiter(cmd);
+        else queue.push(cmd);
+        const result = await new Promise((resolve) => {
+          resultWaiters.set(id, resolve);
+          setTimeout(() => { if (resultWaiters.delete(id)) resolve({ timeout: true }); }, 30000);
+        });
+        return json({ id, result });
+      }
+
+      // Plugin → long-poll for the next command
+      if (url.pathname === "/poll") {
+        lastSeen = Date.now();
+        const next = queue.shift();
+        if (next) return json(next);
+        const cmd = await new Promise<Cmd | null>((resolve) => {
+          pollWaiters.push(resolve);
+          setTimeout(() => {
+            const i = pollWaiters.indexOf(resolve);
+            if (i >= 0) { pollWaiters.splice(i, 1); resolve(null); }
+          }, 25000);
+        });
+        return json(cmd ?? {});
+      }
+
+      // Plugin → post a command result
+      if (url.pathname === "/result" && req.method === "POST") {
+        const body = (await req.json()) as { id: string; result: unknown };
+        const w = resultWaiters.get(body.id);
+        if (w) { resultWaiters.delete(body.id); w(body.result); }
+        return json({ ok: true });
+      }
+
+      return json({ error: "not found" }, 404);
+    },
+  });
+  console.log(`figma-api bridge listening on http://localhost:${port}`);
+  console.log("Endpoints: POST /cmd  GET /poll  POST /result  GET /health");
+  console.log("Point the plugin at this URL (or a cloudflared tunnel of it), then run draw-* commands.");
+}
+
+/** CLI helper: push a command to a running bridge and return the plugin's result. */
+export async function sendCommand(relay: string, op: string, params: Record<string, unknown>): Promise<void> {
+  const res = await fetch(`${relay.replace(/\/$/, "")}/cmd`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ op, ...params }),
+  }).catch((e) => { console.error(`Bridge not reachable at ${relay}: ${e.message}\nStart it with: figma-api bridge`); process.exit(1); });
+  const data = (await (res as Response).json()) as { result?: { timeout?: boolean; error?: string } };
+  const result = data.result;
+  if (result?.timeout) {
+    console.error("Timed out waiting for the plugin. Is it open and Connected to the relay?");
+    process.exit(1);
+  }
+  console.log(JSON.stringify(result ?? data, null, 2));
+  if (result?.error) process.exit(1);
+}

package/src/index.ts

@@ -0,0 +1,645 @@
+#!/usr/bin/env bun
+import { program } from "commander";
+import { readFileSync } from "fs";
+import {
+  saveCredentials, loadCredentials,
+  get, post, put, del, output, parseFigmaTarget, readJsonArg,
+} from "./api";
+import { startBridge, sendCommand } from "./bridge";
+
+const DEFAULT_RELAY = process.env.FIGMA_RELAY || "http://localhost:8917";
+
+program
+  .name("figma-api")
+  .description(
+    "Figma REST API CLI — raw read+write wrapper for files, nodes, images, comments,\n" +
+    "components, styles, variables, dev resources, webhooks, projects and analytics.\n" +
+    "Auth: figma-api auth <personal-access-token>   (or FIGMA_TOKEN env var)\n" +
+    "Token: create at https://www.figma.com/settings → Personal access tokens\n" +
+    "Most commands accept a file URL or a raw file key. node-id is read from the URL too.\n\n" +
+    "NOTE: Creating canvas layers (frames/shapes/text) is NOT in the REST API — that\n" +
+    "lives in the Figma plugin/MCP runtime. Writable here: comments, reactions,\n" +
+    "variables, dev resources and webhooks (token needs the matching write scopes)."
+  )
+  .version("1.0.0")
+  .addHelpText("after", `
+Examples:
+  figma-api auth figd_xxx
+  figma-api me
+  figma-api file https://www.figma.com/design/AbC123/My-File
+  figma-api nodes AbC123 --ids 1:2,3:4
+  figma-api images AbC123 --ids 1:2 --format svg --scale 2
+  figma-api comments AbC123
+  figma-api comment-add AbC123 "Looks great!" --x 100 --y 200 --node 1:2
+  figma-api variables-local AbC123
+  figma-api webhook-create FILE_UPDATE https://my.app/hook --context file --context-id AbC123
+
+Run 'figma-api <command> --help' for per-command details, parameters and examples.`);
+
+// ── auth ───────────────────────────────────────────────────────────────────
+program
+  .command("auth [token]")
+  .description("Save a personal access token, or show auth status")
+  .addHelpText("after", `
+Get a token:
+  1. Open https://www.figma.com/settings
+  2. Scroll to "Personal access tokens" → Generate new token
+  3. Pick scopes: file_content:read is enough for reads. For writes also add
+     file_comments:write, file_variables:write, file_dev_resources:write,
+     webhooks:write (some scopes need a paid/Enterprise plan).
+
+Examples:
+  figma-api auth                 # show current status + instructions
+  figma-api auth figd_abc123     # save token to ~/.config/figma-api/credentials.json
+
+You can also skip saving and pass the token via env:
+  FIGMA_TOKEN=figd_abc123 figma-api me`)
+  .action((token?: string) => {
+    if (token) {
+      saveCredentials({ token });
+      console.log("✅ Token saved to ~/.config/figma-api/credentials.json");
+      return;
+    }
+    console.log("Figma REST API — Personal Access Token auth\n");
+    console.log("How to get a token:");
+    console.log("  1. https://www.figma.com/settings → Personal access tokens");
+    console.log("  2. Generate, choose scopes (reads: file_content:read; writes need more)");
+    console.log("  3. Save it:  figma-api auth <token>\n");
+    const env = process.env.FIGMA_TOKEN || process.env.FIGMA_API_TOKEN;
+    const creds = loadCredentials();
+    if (env) console.log(`Current status:\n  ✅ FIGMA_TOKEN env set (${env.slice(0, 8)}...)`);
+    else if (creds?.token) console.log(`Current status:\n  ✅ Saved token ${creds.token.slice(0, 8)}...`);
+    else console.log("Current status:\n  ❌ No token saved and no FIGMA_TOKEN env var");
+  });
+
+// ── user ─────────────────────────────────────────────────────────────────────
+program
+  .command("me")
+  .description("Get the authenticated user (whoami)")
+  .addHelpText("after", `\nExample:\n  figma-api me`)
+  .action(async () => output(await get("/v1/me")));
+
+// ── files ─────────────────────────────────────────────────────────────────────
+program
+  .command("file <key-or-url>")
+  .description("Get the full document JSON for a file")
+  .option("--ids <ids>", "comma-separated node IDs to limit the returned tree (e.g. 1:2,3:4)")
+  .option("--depth <n>", "how deep to traverse the document tree (1 = pages only)")
+  .option("--version <id>", "a specific version ID (default: current)")
+  .option("--geometry <mode>", "set to 'paths' to include vector geometry")
+  .option("--branch-data", "include branch metadata")
+  .addHelpText("after", `
+Examples:
+  figma-api file https://www.figma.com/design/AbC123/My-File
+  figma-api file AbC123 --depth 2
+  figma-api file AbC123 --ids 1:2,3:4 --geometry paths
+
+Tip: pipe to jq, e.g.  figma-api file AbC123 --depth 1 | jq '.document.children[].name'`)
+  .action(async (input: string, o: any) => {
+    const { fileKey, nodeId } = parseFigmaTarget(input);
+    const ids = o.ids ?? nodeId;
+    await output(await get(`/v1/files/${fileKey}`, {
+      ids, depth: o.depth, version: o.version, geometry: o.geometry,
+      branch_data: o.branchData ? true : undefined,
+    }));
+  });
+
+program
+  .command("nodes <key-or-url>")
+  .description("Get document JSON for specific nodes only (lighter than 'file')")
+  .option("--ids <ids>", "comma-separated node IDs (required unless node-id is in the URL)")
+  .option("--depth <n>", "traversal depth within each node")
+  .option("--version <id>", "a specific version ID")
+  .option("--geometry <mode>", "set to 'paths' to include vector geometry")
+  .addHelpText("after", `
+Examples:
+  figma-api nodes AbC123 --ids 1:2,3:4
+  figma-api nodes "https://www.figma.com/design/AbC123/x?node-id=1-2"   # ids from URL`)
+  .action(async (input: string, o: any) => {
+    const { fileKey, nodeId } = parseFigmaTarget(input);
+    const ids = o.ids ?? nodeId;
+    if (!ids) { console.error("Provide --ids or a URL containing node-id"); process.exit(1); }
+    await output(await get(`/v1/files/${fileKey}/nodes`, {
+      ids, depth: o.depth, version: o.version, geometry: o.geometry,
+    }));
+  });
+
+program
+  .command("file-meta <key-or-url>")
+  .description("Get lightweight file metadata (name, last touched, editor type, thumbnail)")
+  .addHelpText("after", `\nExample:\n  figma-api file-meta AbC123`)
+  .action(async (input: string) => {
+    const { fileKey } = parseFigmaTarget(input);
+    await output(await get(`/v1/files/${fileKey}/meta`));
+  });
+
+program
+  .command("versions <key-or-url>")
+  .description("List the version history of a file")
+  .addHelpText("after", `\nExample:\n  figma-api versions AbC123`)
+  .action(async (input: string) => {
+    const { fileKey } = parseFigmaTarget(input);
+    await output(await get(`/v1/files/${fileKey}/versions`));
+  });
+
+// ── images ────────────────────────────────────────────────────────────────────
+program
+  .command("images <key-or-url>")
+  .description("Render nodes to images and return their URLs")
+  .option("--ids <ids>", "comma-separated node IDs to render (or from URL node-id)")
+  .option("--format <fmt>", "jpg | png | svg | pdf", "png")
+  .option("--scale <n>", "scale factor 0.01–4 (raster only)")
+  .option("--version <id>", "a specific version ID")
+  .option("--svg-include-id", "include id attributes in SVG output")
+  .option("--svg-include-node-id", "include node id attributes in SVG output")
+  .option("--no-svg-outline-text", "keep SVG text as <text> instead of vector outlines")
+  .option("--no-svg-simplify-stroke", "do not simplify inside/outside strokes in SVG")
+  .option("--no-contents-only", "include content that overlaps the rendered node")
+  .option("--use-absolute-bounds", "render full node dimensions ignoring clipping")
+  .addHelpText("after", `
+Returns a JSON map of node-id → rendered image URL (valid for a short time).
+Examples:
+  figma-api images AbC123 --ids 1:2 --format svg
+  figma-api images AbC123 --ids 1:2,3:4 --format png --scale 2`)
+  .action(async (input: string, o: any) => {
+    const { fileKey, nodeId } = parseFigmaTarget(input);
+    const ids = o.ids ?? nodeId;
+    if (!ids) { console.error("Provide --ids or a URL containing node-id"); process.exit(1); }
+    await output(await get(`/v1/images/${fileKey}`, {
+      ids, format: o.format, scale: o.scale, version: o.version,
+      svg_include_id: o.svgIncludeId ? true : undefined,
+      svg_include_node_id: o.svgIncludeNodeId ? true : undefined,
+      svg_outline_text: o.svgOutlineText === false ? false : undefined,
+      svg_simplify_stroke: o.svgSimplifyStroke === false ? false : undefined,
+      contents_only: o.contentsOnly === false ? false : undefined,
+      use_absolute_bounds: o.useAbsoluteBounds ? true : undefined,
+    }));
+  });
+
+program
+  .command("image-fills <key-or-url>")
+  .description("Get download URLs for all images placed as fills in a file")
+  .addHelpText("after", `\nExample:\n  figma-api image-fills AbC123`)
+  .action(async (input: string) => {
+    const { fileKey } = parseFigmaTarget(input);
+    await output(await get(`/v1/files/${fileKey}/images`));
+  });
+
+// ── comments (read + write) ────────────────────────────────────────────────────
+program
+  .command("comments <key-or-url>")
+  .description("List comments in a file")
+  .option("--as-md", "return comment bodies as Markdown")
+  .addHelpText("after", `\nExample:\n  figma-api comments AbC123`)
+  .action(async (input: string, o: any) => {
+    const { fileKey } = parseFigmaTarget(input);
+    await output(await get(`/v1/files/${fileKey}/comments`, { as_md: o.asMd ? true : undefined }));
+  });
+
+program
+  .command("comment-add <key-or-url> <message>")
+  .description("Add a comment to a file (write)")
+  .option("--x <px>", "pin x coordinate on the canvas")
+  .option("--y <px>", "pin y coordinate on the canvas")
+  .option("--node <id>", "anchor the pin to a node id (with optional --x/--y offset)")
+  .option("--reply-to <comment-id>", "reply to an existing comment instead of a new pin")
+  .addHelpText("after", `
+Pin placement: use --x/--y for an absolute canvas pin, optionally --node to anchor
+to a node, or --reply-to to thread under an existing comment.
+Examples:
+  figma-api comment-add AbC123 "Tighten this spacing" --x 120 --y 240
+  figma-api comment-add AbC123 "On this frame" --node 1:2
+  figma-api comment-add AbC123 "Agreed" --reply-to 99887766`)
+  .action(async (input: string, message: string, o: any) => {
+    const { fileKey } = parseFigmaTarget(input);
+    const body: Record<string, unknown> = { message };
+    if (o.replyTo) body.comment_id = o.replyTo;
+    else if (o.node) {
+      body.client_meta = { node_id: o.node, node_offset: { x: Number(o.x ?? 0), y: Number(o.y ?? 0) } };
+    } else if (o.x !== undefined || o.y !== undefined) {
+      if (o.x === undefined || o.y === undefined) {
+        console.error("A canvas pin needs both --x and --y (or use --node).");
+        process.exit(1);
+      }
+      body.client_meta = { x: Number(o.x), y: Number(o.y) };
+    }
+    await output(await post(`/v1/files/${fileKey}/comments`, body));
+  });
+
+program
+  .command("comment-delete <key-or-url> <comment-id>")
+  .description("Delete a comment (write)")
+  .addHelpText("after", `\nExample:\n  figma-api comment-delete AbC123 99887766`)
+  .action(async (input: string, commentId: string) => {
+    const { fileKey } = parseFigmaTarget(input);
+    await output(await del(`/v1/files/${fileKey}/comments/${commentId}`));
+  });
+
+program
+  .command("reactions <key-or-url> <comment-id>")
+  .description("List reactions on a comment")
+  .option("--cursor <c>", "pagination cursor")
+  .addHelpText("after", `\nExample:\n  figma-api reactions AbC123 99887766`)
+  .action(async (input: string, commentId: string, o: any) => {
+    const { fileKey } = parseFigmaTarget(input);
+    await output(await get(`/v1/files/${fileKey}/comments/${commentId}/reactions`, { cursor: o.cursor }));
+  });
+
+program
+  .command("reaction-add <key-or-url> <comment-id> <emoji>")
+  .description("Add an emoji reaction to a comment (write)")
+  .addHelpText("after", `
+Emoji must be a supported shortcode, e.g. :eyes:, :heart_eyes:, :+1:.
+Example:
+  figma-api reaction-add AbC123 99887766 :eyes:`)
+  .action(async (input: string, commentId: string, emoji: string) => {
+    const { fileKey } = parseFigmaTarget(input);
+    await output(await post(`/v1/files/${fileKey}/comments/${commentId}/reactions`, { emoji }));
+  });
+
+program
+  .command("reaction-delete <key-or-url> <comment-id> <emoji>")
+  .description("Remove an emoji reaction from a comment (write)")
+  .addHelpText("after", `\nExample:\n  figma-api reaction-delete AbC123 99887766 :eyes:`)
+  .action(async (input: string, commentId: string, emoji: string) => {
+    const { fileKey } = parseFigmaTarget(input);
+    await output(await del(`/v1/files/${fileKey}/comments/${commentId}/reactions`, { emoji }));
+  });
+
+// ── projects ────────────────────────────────────────────────────────────────
+program
+  .command("projects <team-id>")
+  .description("List projects in a team")
+  .addHelpText("after", `
+team-id is in the team URL: figma.com/files/team/<TEAM_ID>/...
+Example:
+  figma-api projects 1101234567890`)
+  .action(async (teamId: string) => output(await get(`/v1/teams/${teamId}/projects`)));
+
+program
+  .command("project-files <project-id>")
+  .description("List files in a project")
+  .option("--branch-data", "include branch metadata for each file")
+  .addHelpText("after", `\nExample:\n  figma-api project-files 55512345`)
+  .action(async (projectId: string, o: any) =>
+    output(await get(`/v1/projects/${projectId}/files`, { branch_data: o.branchData ? true : undefined })));
+
+// ── components & styles ───────────────────────────────────────────────────────
+program
+  .command("components <key-or-url>")
+  .description("List published components in a file")
+  .addHelpText("after", `\nExample:\n  figma-api components AbC123`)
+  .action(async (input: string) => {
+    const { fileKey } = parseFigmaTarget(input);
+    await output(await get(`/v1/files/${fileKey}/components`));
+  });
+
+program
+  .command("team-components <team-id>")
+  .description("List published components in a team library (paginated)")
+  .option("--page-size <n>", "results per page")
+  .option("--after <cursor>", "pagination cursor")
+  .addHelpText("after", `\nExample:\n  figma-api team-components 1101234567890 --page-size 50`)
+  .action(async (teamId: string, o: any) =>
+    output(await get(`/v1/teams/${teamId}/components`, { page_size: o.pageSize, after: o.after })));
+
+program
+  .command("component <key>")
+  .description("Get a single published component by its key")
+  .addHelpText("after", `\nExample:\n  figma-api component 8f2c...`)
+  .action(async (key: string) => output(await get(`/v1/components/${key}`)));
+
+program
+  .command("component-sets <key-or-url>")
+  .description("List published component sets (variants) in a file")
+  .addHelpText("after", `\nExample:\n  figma-api component-sets AbC123`)
+  .action(async (input: string) => {
+    const { fileKey } = parseFigmaTarget(input);
+    await output(await get(`/v1/files/${fileKey}/component_sets`));
+  });
+
+program
+  .command("team-component-sets <team-id>")
+  .description("List published component sets in a team library (paginated)")
+  .option("--page-size <n>", "results per page")
+  .option("--after <cursor>", "pagination cursor")
+  .addHelpText("after", `\nExample:\n  figma-api team-component-sets 1101234567890`)
+  .action(async (teamId: string, o: any) =>
+    output(await get(`/v1/teams/${teamId}/component_sets`, { page_size: o.pageSize, after: o.after })));
+
+program
+  .command("styles <key-or-url>")
+  .description("List published styles in a file")
+  .addHelpText("after", `\nExample:\n  figma-api styles AbC123`)
+  .action(async (input: string) => {
+    const { fileKey } = parseFigmaTarget(input);
+    await output(await get(`/v1/files/${fileKey}/styles`));
+  });
+
+program
+  .command("team-styles <team-id>")
+  .description("List published styles in a team library (paginated)")
+  .option("--page-size <n>", "results per page")
+  .option("--after <cursor>", "pagination cursor")
+  .addHelpText("after", `\nExample:\n  figma-api team-styles 1101234567890`)
+  .action(async (teamId: string, o: any) =>
+    output(await get(`/v1/teams/${teamId}/styles`, { page_size: o.pageSize, after: o.after })));
+
+program
+  .command("style <key>")
+  .description("Get a single published style by its key")
+  .addHelpText("after", `\nExample:\n  figma-api style 1a2b...`)
+  .action(async (key: string) => output(await get(`/v1/styles/${key}`)));
+
+// ── variables (read + write, Enterprise) ──────────────────────────────────────
+program
+  .command("variables-local <key-or-url>")
+  .description("Get local variables and collections in a file (Enterprise)")
+  .addHelpText("after", `
+Requires file_variables:read scope and an Enterprise plan.
+Example:
+  figma-api variables-local AbC123`)
+  .action(async (input: string) => {
+    const { fileKey } = parseFigmaTarget(input);
+    await output(await get(`/v1/files/${fileKey}/variables/local`));
+  });
+
+program
+  .command("variables-published <key-or-url>")
+  .description("Get published variables from a library file (Enterprise)")
+  .addHelpText("after", `\nExample:\n  figma-api variables-published AbC123`)
+  .action(async (input: string) => {
+    const { fileKey } = parseFigmaTarget(input);
+    await output(await get(`/v1/files/${fileKey}/variables/published`));
+  });
+
+program
+  .command("variables-modify <key-or-url> <json>")
+  .description("Create / update / delete variables and collections in bulk (write, Enterprise)")
+  .addHelpText("after", `
+Requires file_variables:write scope + Enterprise. <json> is a payload object (or
+@file.json) with any of: variableCollections, variableModes, variables,
+variableModeValues. Each entry has an "action" of CREATE | UPDATE | DELETE.
+
+Example (inline):
+  figma-api variables-modify AbC123 '{"variableCollections":[{"action":"CREATE","name":"Tokens"}]}'
+Example (from file):
+  figma-api variables-modify AbC123 @payload.json
+
+Docs: https://www.figma.com/developers/api#post-variables-endpoint`)
+  .action(async (input: string, json: string) => {
+    const { fileKey } = parseFigmaTarget(input);
+    await output(await post(`/v1/files/${fileKey}/variables`, readJsonArg(json)));
+  });
+
+// ── dev resources (read + write) ──────────────────────────────────────────────
+program
+  .command("dev-resources <key-or-url>")
+  .description("List dev resources (links) attached to nodes in a file")
+  .option("--node-ids <ids>", "comma-separated node IDs to filter by")
+  .addHelpText("after", `\nExample:\n  figma-api dev-resources AbC123 --node-ids 1:2,3:4`)
+  .action(async (input: string, o: any) => {
+    const { fileKey } = parseFigmaTarget(input);
+    await output(await get(`/v1/files/${fileKey}/dev_resources`, { node_ids: o.nodeIds }));
+  });
+
+program
+  .command("dev-resource-add <key-or-url> <name> <url>")
+  .description("Attach a dev resource link to a node (write)")
+  .requiredOption("--node <id>", "node id to attach the link to")
+  .addHelpText("after", `
+Example:
+  figma-api dev-resource-add AbC123 "PR #42" https://github.com/org/repo/pull/42 --node 1:2
+
+Bulk: use 'dev-resources-bulk-add' with a JSON array for multiple at once.`)
+  .action(async (input: string, name: string, url: string, o: any) => {
+    const { fileKey } = parseFigmaTarget(input);
+    const body = { dev_resources: [{ name, url, file_key: fileKey, node_id: o.node }] };
+    await output(await post(`/v1/dev_resources`, body));
+  });
+
+program
+  .command("dev-resources-bulk-add <json>")
+  .description("Create multiple dev resources from a JSON array (write)")
+  .addHelpText("after", `
+<json> (or @file.json) is an array of { name, url, file_key, node_id }.
+Example:
+  figma-api dev-resources-bulk-add '[{"name":"Docs","url":"https://x","file_key":"AbC123","node_id":"1:2"}]'`)
+  .action(async (json: string) => {
+    const arr = readJsonArg(json);
+    await output(await post(`/v1/dev_resources`, { dev_resources: arr }));
+  });
+
+program
+  .command("dev-resources-update <json>")
+  .description("Update existing dev resources by id from a JSON array (write)")
+  .addHelpText("after", `
+<json> (or @file.json) is an array of { id, name?, url? }.
+Example:
+  figma-api dev-resources-update '[{"id":"abc","name":"Renamed"}]'`)
+  .action(async (json: string) => {
+    const arr = readJsonArg(json);
+    await output(await put(`/v1/dev_resources`, { dev_resources: arr }));
+  });
+
+program
+  .command("dev-resource-delete <key-or-url> <dev-resource-id>")
+  .description("Delete a dev resource from a file (write)")
+  .addHelpText("after", `\nExample:\n  figma-api dev-resource-delete AbC123 abc-id`)
+  .action(async (input: string, id: string) => {
+    const { fileKey } = parseFigmaTarget(input);
+    await output(await del(`/v1/files/${fileKey}/dev_resources/${id}`));
+  });
+
+// ── webhooks v2 (read + write) ─────────────────────────────────────────────────
+program
+  .command("webhooks")
+  .description("List webhooks (by context or for the whole plan)")
+  .option("--context <type>", "team | project | file")
+  .option("--context-id <id>", "id matching the context type")
+  .option("--plan-api-id <id>", "list all webhooks for a plan")
+  .option("--cursor <c>", "pagination cursor")
+  .addHelpText("after", `
+Examples:
+  figma-api webhooks --context file --context-id AbC123
+  figma-api webhooks --context team --context-id 1101234567890`)
+  .action(async (o: any) =>
+    output(await get(`/v2/webhooks`, { context: o.context, context_id: o.contextId, plan_api_id: o.planApiId, cursor: o.cursor })));
+
+program
+  .command("webhook <webhook-id>")
+  .description("Get a single webhook by id")
+  .addHelpText("after", `\nExample:\n  figma-api webhook 1234567`)
+  .action(async (id: string) => output(await get(`/v2/webhooks/${id}`)));
+
+program
+  .command("webhook-create <event> <endpoint>")
+  .description("Create a webhook (write)")
+  .requiredOption("--context <type>", "team | project | file")
+  .requiredOption("--context-id <id>", "id matching the context type")
+  .requiredOption("--passcode <code>", "passcode echoed back in each request for verification")
+  .option("--status <status>", "ACTIVE | PAUSED", "ACTIVE")
+  .option("--description <text>", "human description of the webhook")
+  .addHelpText("after", `
+event: PING | FILE_UPDATE | FILE_VERSION_UPDATE | FILE_DELETE | LIBRARY_PUBLISH
+       | FILE_COMMENT | DEV_MODE_STATUS_UPDATE
+Requires webhooks:write scope. Figma sends a PING to the endpoint on creation.
+Example:
+  figma-api webhook-create FILE_UPDATE https://my.app/hook --context file --context-id AbC123 --passcode s3cret`)
+  .action(async (event: string, endpoint: string, o: any) => {
+    const body: Record<string, unknown> = {
+      event_type: event, endpoint, context: o.context, context_id: o.contextId,
+      passcode: o.passcode, status: o.status,
+    };
+    if (o.description) body.description = o.description;
+    await output(await post(`/v2/webhooks`, body));
+  });
+
+program
+  .command("webhook-update <webhook-id>")
+  .description("Update a webhook's event, endpoint, status, passcode or description (write)")
+  .option("--event <event>", "new event type")
+  .option("--endpoint <url>", "new endpoint URL")
+  .option("--passcode <code>", "new passcode")
+  .option("--status <status>", "ACTIVE | PAUSED")
+  .option("--description <text>", "new description")
+  .addHelpText("after", `\nExample:\n  figma-api webhook-update 1234567 --status PAUSED`)
+  .action(async (id: string, o: any) => {
+    const body: Record<string, unknown> = {};
+    if (o.event) body.event_type = o.event;
+    if (o.endpoint) body.endpoint = o.endpoint;
+    if (o.passcode) body.passcode = o.passcode;
+    if (o.status) body.status = o.status;
+    if (o.description) body.description = o.description;
+    await output(await put(`/v2/webhooks/${id}`, body));
+  });
+
+program
+  .command("webhook-delete <webhook-id>")
+  .description("Delete a webhook (write)")
+  .addHelpText("after", `\nExample:\n  figma-api webhook-delete 1234567`)
+  .action(async (id: string) => output(await del(`/v2/webhooks/${id}`)));
+
+program
+  .command("webhook-requests <webhook-id>")
+  .description("Get recent delivery attempts (requests + responses) for a webhook")
+  .addHelpText("after", `\nExample:\n  figma-api webhook-requests 1234567`)
+  .action(async (id: string) => output(await get(`/v2/webhooks/${id}/requests`)));
+
+// ── library analytics (Enterprise) ─────────────────────────────────────────────
+program
+  .command("analytics <key-or-url> <asset> <kind>")
+  .description("Library analytics: asset=component|style|variable, kind=actions|usages (Enterprise)")
+  .requiredOption("--group-by <field>", "actions: component|style|variable | team ; usages: component|style|variable | file")
+  .option("--start-date <YYYY-MM-DD>", "range start (actions only)")
+  .option("--end-date <YYYY-MM-DD>", "range end (actions only)")
+  .option("--order <dir>", "asc | desc")
+  .option("--cursor <c>", "pagination cursor")
+  .addHelpText("after", `
+Requires library_analytics:read + Enterprise.
+Examples:
+  figma-api analytics AbC123 component usages --group-by file
+  figma-api analytics AbC123 style actions --group-by team --start-date 2024-01-01 --end-date 2024-02-01`)
+  .action(async (input: string, asset: string, kind: string, o: any) => {
+    const { fileKey } = parseFigmaTarget(input);
+    if (!["component", "style", "variable"].includes(asset)) { console.error("asset must be component|style|variable"); process.exit(1); }
+    if (!["actions", "usages"].includes(kind)) { console.error("kind must be actions|usages"); process.exit(1); }
+    await output(await get(`/v1/analytics/libraries/${fileKey}/${asset}/${kind}`, {
+      group_by: o.groupBy, start_date: o.startDate, end_date: o.endDate, order: o.order, cursor: o.cursor,
+    }));
+  });
+
+// ── activity / payments / oembed ────────────────────────────────────────────────
+program
+  .command("activity-logs")
+  .description("Get activity logs for an organization (Enterprise, org token)")
+  .option("--events <list>", "comma-separated event types to filter")
+  .option("--start-time <unix>", "range start (epoch seconds)")
+  .option("--end-time <unix>", "range end (epoch seconds)")
+  .option("--limit <n>", "max events")
+  .option("--order <dir>", "asc | desc")
+  .addHelpText("after", `\nExample:\n  figma-api activity-logs --limit 100 --order desc`)
+  .action(async (o: any) => output(await get(`/v1/activity_logs`, {
+    events: o.events, start_time: o.startTime, end_time: o.endTime, limit: o.limit, order: o.order,
+  })));
+
+program
+  .command("payments")
+  .description("Get payment information for a plugin/widget/community-file user")
+  .option("--token <plugin_payment_token>", "plugin payment token (from plugin runtime; alternative to --user-id)")
+  .option("--user-id <id>", "the Figma user id (use with one of --plugin-id/--widget-id/--community-file-id)")
+  .option("--plugin-id <id>", "plugin resource id")
+  .option("--widget-id <id>", "widget resource id")
+  .option("--community-file-id <id>", "community file resource id")
+  .addHelpText("after", `
+Provide either --token, or --user-id together with one of --plugin-id / --widget-id
+/ --community-file-id.
+Examples:
+  figma-api payments --token <plugin_payment_token>
+  figma-api payments --user-id 12345 --plugin-id 67890`)
+  .action(async (o: any) => output(await get(`/v1/payments`, {
+    plugin_payment_token: o.token, user_id: o.userId,
+    plugin_id: o.pluginId, widget_id: o.widgetId, community_file_id: o.communityFileId,
+  })));
+
+program
+  .command("oembed <url>")
+  .description("Get oEmbed metadata for a public Figma file/prototype URL")
+  .addHelpText("after", `\nExample:\n  figma-api oembed https://www.figma.com/design/AbC123/My-File`)
+  .action(async (url: string) => output(await get(`/v1/oembed`, { url })));
+
+// ── plugin bridge (canvas writes the REST API can't do) ───────────────────────
+program
+  .command("bridge")
+  .description("Start the relay that lets the figma-api CLI drive the Figma plugin (canvas writes)")
+  .option("--port <n>", "port to listen on", "8917")
+  .addHelpText("after", `
+The Figma REST API cannot create canvas nodes (frames/text/shapes) or edit
+variables off-Enterprise. This relay bridges the CLI and the companion Figma
+plugin (see plugin/ folder), which can.
+
+Flow:
+  1. figma-api bridge                       # start this relay (keep running)
+  2. In Figma desktop: Plugins → Development → Import plugin from manifest →
+     api-apps/figma-api/plugin/manifest.json, run it, Connect to the relay URL.
+  3. figma-api run '...'                     # CLI → relay → plugin runs it
+
+Cross-machine: expose the relay with 'cloudflared tunnel --url http://localhost:8917'
+and paste that https URL into the plugin's Relay field.
+
+⚠️  Security: the relay has no auth and 'run' executes arbitrary code in your
+Figma document. Only run it on a trusted machine/network; do not expose the
+tunnel URL publicly or run code you don't trust.`)
+  .action((o: any) => startBridge(Number(o.port)));
+
+program
+  .command("run <code-or-@file>")
+  .description("Run arbitrary Figma Plugin API code in the connected plugin (full canvas + variables write)")
+  .option("--relay <url>", "relay URL", DEFAULT_RELAY)
+  .addHelpText("after", `
+Whatever the Figma Plugin API can do, this can do — create frames/text/shapes,
+edit variables (no Enterprise paywall, unlike REST), read selection, etc.
+\`figma\` is in scope; you may use await and \`return\` a value (nodes come back as
+{id,type,name}).
+
+Pass code inline or as @file.js. Requires a running bridge + Connected plugin.
+
+⚠️  Executes arbitrary code in your Figma document — only run code you trust.
+
+Examples:
+  figma-api run 'return figma.currentPage.selection.map(n => ({id:n.id, type:n.type, name:n.name}))'
+  figma-api run 'const t = figma.createText(); await figma.loadFontAsync({family:"Inter",style:"Regular"}); t.characters="Hi from CLI"; figma.currentPage.appendChild(t); return t'
+  figma-api run @make-card.js`)
+  .action(async (codeArg: string, o: any) => {
+    const code = codeArg.startsWith("@") ? readFileSync(codeArg.slice(1), "utf-8") : codeArg;
+    await sendCommand(o.relay, "eval", { code });
+  });
+
+program
+  .command("ping")
+  .description("Ping the connected plugin to verify the bridge round-trip")
+  .option("--relay <url>", "relay URL", DEFAULT_RELAY)
+  .addHelpText("after", `\nReturns the plugin's current page name and selection.\nExample:\n  figma-api ping`)
+  .action(async (o: any) => sendCommand(o.relay, "ping", {}));
+
+program.parse();