figcli

figcli is a fast, compiled, standalone CLI tool for driving Figma Desktop locally — no API key, no internet, no external dependencies.

It communicates directly with your running Figma Desktop process via two modes: a plugin bridge (Safe Mode, default) or a direct CDP connection (Wizard Mode).

Figma Desktop must be running in both modes. figcli talks to a live local Figma process, not the cloud.

---

Why figcli instead of Figma MCP?

	figcli	Figma MCP
Internet	❌ Not needed	✅ Required (API calls to cloud)
API Key	❌ Not needed	✅ Required
Speed	~50–150ms (Wizard)	~500–2000ms (network latency)
Works offline	✅ Yes	❌ No
Data leaves your machine	❌ Never	✅ Yes (sent to Figma servers)
Full Figma JS access	✅ Direct V8 eval	❌ Limited API surface
Screenshot/capture	✅ Local PNG	❌ Not supported
Render JSX live	✅ Direct to canvas	❌ Not supported
Modify Figma canvas	✅ Yes	❌ Read-only
Setup	One command	Need API key + config
Works behind firewall	✅ Yes	❌ Depends on network

When to use figcli

• You need speed (AI agent loops, rapid iteration)
• You need to write to Figma (render components, modify canvas)
• You're in a restricted network (corporate, air-gapped)
• You want privacy — data never leaves your machine
• You need screenshot/capture of nodes locally

Token efficiency (AI/LLM)

figcli is significantly more token-efficient because:

• Figma MCP returns full verbose JSON from the API — every property, every nested node, every style. A single node response can be 500+ tokens.
• figcli lets you run custom JS eval that returns ONLY what you need:

# MCP returns the entire node tree (~500+ tokens)
# figcli returns just what you ask for (~30-50 tokens)
figcli eval "JSON.stringify(await figma.getNodeByIdAsync('1:8').then(n=>({id:n.name,w:Math.round(n.width)})))"

For an AI agent making 50+ calls per task, figcli can save 80–90% of token costs.

When to use Figma MCP

• You only need read-only access to design tokens
• You're already in a cloud-based workflow
• You don't have Figma Desktop installed (web-only)

---

Setup — let your AI do it for you

You don't install this by hand. You use an AI coding assistant — Claude Code (recommended) — point it at this project, and ask it to set everything up.

What you need first

• Figma Desktop — installed and open (download)
• Claude Code — Anthropic's AI assistant for your terminal. Install here (one command, takes a minute)
  (Or use Cursor — see below)

1. Let Claude install and connect it

Open Claude Code anywhere and paste:

"Read the README, CLAUDE.md and docs at https://github.com/febritecno/figcli, then install figcli and connect it to my Figma."

Claude downloads the installer, runs it, and connects to your open Figma Desktop. You watch — you don't type commands.

When it says it's connected, you're done. ✅

2. Start using it — just talk

Now describe what you want:

"Create a card component with title, description, and a primary button."

Claude builds it in Figma instantly.

Works on macOS, Windows, and Linux — don't worry, figcli handles the rest.

Or if you prefer to install it yourself in one line:

curl -sL https://raw.githubusercontent.com/febritecno/figcli/main/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/febritecno/figcli/main/install.ps1 | iex

---

Connection Modes

figcli connects to Figma in one of two ways. The AI picks the right one during setup — here's what they mean:

⚡ Wizard Mode — faster, recommended

• Applies a small, reversible one-time patch to Figma Desktop so figcli can talk to it directly via CDP (port 9222)
• No plugin to keep open — just open Figma Desktop
• Full command support: export capture, canvas info, canvas next, ~50–150ms response time
• The patch is safe and undoable — the AI can undo it anytime, nothing ever leaves your machine

Tell Claude: "connect to Figma" and it handles the patch and restart automatically.

Safe Mode — no changes to Figma

• Uses a lightweight WebSocket plugin that runs inside Figma — no modification to the app
• You run the plugin once from Plugins → Development → FigCli and keep it open while working
• All core commands work; export capture and canvas info/next are not available in this mode
• Good if your company's IT policy doesn't allow app modifications

Tell Claude: "connect to Figma in safe mode".

Feature	Safe Mode	Wizard Mode
Figma Desktop required	✅	✅
FigCli plugin open	✅ Required	❌ Not needed
figcli render	✅	✅
figcli watch	✅	✅
figcli eval (JS)	✅	✅
figcli export capture	❌	✅
figcli canvas info/next	❌	✅
Modifies Figma install	❌	✅ (once, reversible)
Speed	~200–500ms	~50–150ms ⚡

Auto-priority: If Wizard Mode is active, figcli uses CDP automatically for all commands — even if the plugin is also open. Safe Mode is the fallback when CDP is not available.

Switch modes any time:

figcli mode wizard   # switch to Wizard Mode
figcli mode safe     # switch to Safe Mode
figcli mode          # show current active mode

---

What you can ask Claude to build

Just describe it in plain language. A few examples:

Build components

• "Create three pricing cards in a row."
• "Make a login form with email and password fields."
• "Build a dashboard layout with a sidebar."

Apply design tokens

• "Add Tailwind colors as Figma variables."
• "Use my brand colors on these cards."
• "Apply shadcn's dark theme."

Inspect & modify

• "What's the font size and color of the selected text?"
• "Check the contrast ratio on this button."
• "Rename all frames on this page."

Export

• "Export the selected node as a PNG."
• "Generate Tailwind config from my Figma variables."

You never memorize commands. Claude knows them — you just describe the outcome.

---

For developers

Everything above is powered by a compiled Go CLI. If you want to run commands directly, script them, or extend the tool:

• REFERENCE.md — full command reference
• docs/ — embedded documentation (also accessible via figcli docs)
• CLAUDE.md — architecture and AI agent guidelines for this codebase

Manual install (if you prefer)

curl -sL https://raw.githubusercontent.com/febritecno/figcli/main/install.sh | bash

The binary installs to ~/.local/bin/figcli or /usr/local/bin/figcli. On first run, the daemon auto-registers as a login service so it's always available.

Verify connection

figcli status

Expected output (Safe Mode):

Daemon:       ✓ connected (port 3456)
Safe Mode:    ✓ connected (plugin bridge)
Wizard Mode:  ✗ not connected (CDP port 9222)

✓ Ready — Safe Mode active.

Run full diagnostics:

figcli test

---

Built-in Documentation

All documentation is embedded in the binary — no internet needed.

figcli docs                # index of all topics
figcli docs ai-guide       # full AI agent guide
figcli docs eval-api       # send custom JS to Figma via HTTP API
figcli docs inspect        # find & inspect elements by name, ID, type
figcli docs eval-snippets  # 30+ ready-to-use JS snippets

---

Commands

Command	Mode	Description
figcli status	Both	Connection status
figcli test	Both	Full diagnostics
figcli mode [wizard|safe]	—	Switch connection mode
figcli connect	Wizard	Activate Wizard Mode (alias for mode wizard)
figcli watch	Safe	Stream real-time selection changes
figcli find '<name>'	Both	Find nodes by name
figcli find '<name>' --type FRAME	Both	Find nodes filtered by type
figcli nodes	Both	List all top-level nodes on current page
figcli selection	Both	Show currently selected node(s)
figcli pages	Both	List all pages in the document
figcli node inspect [id]	Both	Full properties of a node
figcli node tree [id]	Both	Show children tree of a node
figcli node rename [id] [name]	Both	Rename a node
figcli node move [id] [x] [y]	Both	Move a node to coordinates
figcli node delete [id]	Both	Delete a node by ID
figcli render '<JSX>'	Both	Render element to canvas
figcli export capture [id]	Wizard only	Screenshot node as PNG
figcli canvas info	Wizard only	Canvas bounds & element count
figcli canvas next	Wizard only	Next free position on canvas
figcli a11y contrast [id]	Wizard	WCAG contrast check
figcli tokens tailwind	Wizard	Create Tailwind color palette
figcli motion hover [id]	Wizard	Create hover state variant
figcli eval '<JS>'	Both	Run custom JavaScript in Figma
figcli daemon start	—	Start daemon in foreground
figcli daemon install	—	Register daemon as login service
figcli docs [topic]	—	Show embedded documentation

---

Architecture

figcli
  ├── Safe Mode (default)
  │     CLI → Daemon (localhost:3456) → Plugin WebSocket → Figma JS Engine
  │
  └── Wizard Mode
        CLI → CDP WebSocket (localhost:9222) → Figma V8 directly

• Daemon (~/.figma-ds-cli/): HTTP + WebSocket server on port 3456. Auto-starts at login.
• Auth token: ~/.figma-ds-cli/.daemon-token — required for all daemon API calls.
• CDP patch: One-time modification to app.asar that opens the debug port.

---

Uninstall

curl -sL https://raw.githubusercontent.com/febritecno/figcli/main/uninstall.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/febritecno/figcli/main/uninstall.ps1 | iex

---

License

MIT