figma

A command-line interface for the Figma API, inspired by GitHub's gh CLI. Built for design-to-code workflows and agent-to-agent handoffs.

Note: This is an unofficial tool and is not affiliated with or endorsed by Figma, Inc.

Installation

npm install -g @mstrathman/figma

From source

git clone https://github.com/mstrathman/figma.git
cd figma
npm install
npm run build
npm link

Authentication

Personal Access Token (Recommended)

Get a token from Figma Developer Settings.

# Interactive login
figma auth login

# Or with token directly
figma auth login --token <your-token>

# Or use environment variable
export FIGMA_TOKEN=<your-token>

OAuth (Browser Login)

For OAuth, you need to create a Figma app first.

# Set credentials
export FIGMA_CLIENT_ID=<your-client-id>
export FIGMA_CLIENT_SECRET=<your-client-secret>

# Login via browser
figma auth login --web

Check Status

figma auth status

Commands

All commands accept either a Figma URL or a file key:

# Using full Figma URL (recommended)
figma file get "https://www.figma.com/file/ABC123xyz/My-Design"

# Using file key
figma file get ABC123xyz

Files

# Get file JSON structure
figma file get <url>

# Get simplified file structure (for understanding hierarchy)
figma file structure <url>
figma file structure <url> --depth 3 --format tree

# Get specific nodes
figma file nodes <url> --id "1:2,1:3"

# Export images from nodes
figma file images <url> --id "1:2" --format svg --output ./exports

# Use node-id from URL directly
figma file images "https://www.figma.com/file/ABC123xyz/Design?node-id=1-2" -o ./exports

# Naming strategies for exported images
figma file images <url> --id "1:2,1:3" --naming name -o ./icons    # Uses node names
figma file images <url> --id "1:2,1:3" --naming path -o ./icons    # Includes parent path

Frames

# List all frames in a file
figma frame list --file <url>

# Filter by page
figma frame list --file <url> --page "Components"

# Filter by type
figma frame list --file <url> --type component,component_set

# Only top-level frames
figma frame list --file <url> --top-level --format table

Projects

# List team projects
figma project list --team <team-id>

# List files in a project
figma project files <project-id>

Components

# List components in a file
figma component list --file <url>

# List team components
figma component list --team <team-id>

# Get component details
figma component get <component-key>

Styles

# List styles in a file
figma style list --file <url>

# List team styles
figma style list --team <team-id>

# Get style details
figma style get <style-key>

Variables (Enterprise)

# List variables
figma variable list <url>

# Export as design tokens
figma variable export <url> --format css --output tokens.css
figma variable export <url> --format style-dictionary --output tokens.json

# Group by scope (colors, spacing, radius, etc.)
figma variable export <url> --categorize --format css

Export (Design-to-Code)

# Export design tokens from styles
figma export tokens <url> --format css
figma export tokens <url> --format scss
figma export tokens <url> --format tailwind
figma export tokens <url> --format style-dictionary

# Export icons
figma export icons <url> --frame "Icons" --format svg --output ./icons

# Handle icon variants
figma export icons <url> --variant-format suffix   # icon-name--large.svg
figma export icons <url> --variant-format folder   # icon-name/large.svg

# Export complete theme package
figma export theme <url> --formats "css,json,tailwind" --output ./theme

Handoff (All-in-One)

Export a complete design handoff package for developers or AI agents:

# Export everything
figma handoff <url> --all --output ./design-handoff

# Customize what to export
figma handoff <url> --tokens css,scss --assets --structure --readme

# Just tokens and structure (no assets)
figma handoff <url> --tokens css,json --structure

Output structure:

figma-handoff/
├── tokens/
│   ├── tokens.css
│   └── tokens.json
├── assets/
│   └── *.svg
├── structure.json
└── HANDOFF.md

Raw API Access

# GET request
figma api /v1/me

# With query parameters
figma api /v1/files/<key>/images -q "ids=1:2,format=svg"

# POST request
figma api /v1/files/<key>/comments -X POST -d '{"message":"Hello"}'

Output Formats

Most commands support --format for output:

• json (default) - JSON output, great for piping to jq
• table - Human-readable table format

figma component list --file <url> --format table
figma frame list --file <url> --format table

Configuration

Configuration is loaded in this priority order:

1. Environment variables (FIGMA_TOKEN, FIGMA_TEAM_ID)
2. Command-line flags (--token)
3. Local config (.figmarc in current directory)
4. User config (~/.config/figma/config.json)

Figma URLs

Commands accept full Figma URLs with automatic parsing:

https://www.figma.com/file/ABC123xyz/My-Design?node-id=1-2
                           ^^^^^^^^^                  ^^^
                           file key                   node ID (optional)

The CLI extracts the file key and node ID automatically. You can override the node ID with --id.

Examples

Export a design system

# Export tokens as CSS variables
figma export tokens "https://www.figma.com/file/ABC123xyz/Design-System" \
  --format css --output ./src/styles/tokens.css

# Export all icons as SVGs with semantic names
figma export icons "https://www.figma.com/file/ABC123xyz/Icons" \
  --frame "Icons" --naming name --output ./src/assets/icons

# Complete handoff package
figma handoff "https://www.figma.com/file/ABC123xyz/Design-System" \
  --all --output ./design-handoff

Automate with scripts

# Get all components and process with jq
figma component list --file <url> | jq '.meta.components[].name'

# Export specific nodes as PNGs at 2x
figma file images <url> --id "1:2,1:3,1:4" --format png --scale 2 --output ./exports

# List all frames and their IDs
figma frame list --file <url> --format table

Agent-to-agent workflows

# Get file structure for AI analysis
figma file structure <url> --depth 3 --format json > structure.json

# Export handoff for coding agent
figma handoff <url> --all --output ./handoff

# The HANDOFF.md contains structured info for LLMs
cat ./handoff/HANDOFF.md

Tech Stack

• TypeScript
• Commander.js (CLI framework)
• @figma/rest-api-spec (official Figma API types)
• keytar (secure credential storage)

License

MIT