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

``bash
npm install -g @mstrathman/figma
`

$3

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

Authentication

$3

Get a token from Figma Developer Settings.

`bash


Interactive login

figma auth login

Or with token directly

figma auth login --token

Or use environment variable

export FIGMA_TOKEN=
`

$3

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

`bash


Set credentials

export FIGMA_CLIENT_ID=
export FIGMA_CLIENT_SECRET=

Login via browser

figma auth login --web
`

$3

`bash
figma auth status
`

Commands

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

`bash


Using full Figma URL (recommended)

figma file get "https://www.figma.com/file/ABC123xyz/My-Design"

Using file key

figma file get ABC123xyz
`

$3

`bash


Get file JSON structure

figma file get

Get simplified file structure (for understanding hierarchy)

figma file structure
figma file structure --depth 3 --format tree

Get specific nodes

figma file nodes --id "1:2,1:3"

Export images from nodes

figma file images --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 --id "1:2,1:3" --naming name -o ./icons # Uses node names
figma file images --id "1:2,1:3" --naming path -o ./icons # Includes parent path
`

$3

`bash


List all frames in a file

figma frame list --file

Filter by page

figma frame list --file --page "Components"

Filter by type

figma frame list --file --type component,component_set

Only top-level frames

figma frame list --file --top-level --format table
`

$3

`bash


List team projects

figma project list --team

List files in a project

figma project files
`

$3

`bash


List components in a file

figma component list --file

List team components

figma component list --team

Get component details

figma component get
`

$3

`bash


List styles in a file

figma style list --file

List team styles

figma style list --team

Get style details

figma style get
`

$3

`bash


List variables

figma variable list

Export as design tokens

figma variable export --format css --output tokens.css
figma variable export --format style-dictionary --output tokens.json

Group by scope (colors, spacing, radius, etc.)

figma variable export --categorize --format css
`

$3

`bash


Export design tokens from styles

figma export tokens --format css
figma export tokens --format scss
figma export tokens --format tailwind
figma export tokens --format style-dictionary

Export icons

figma export icons --frame "Icons" --format svg --output ./icons

Handle icon variants

figma export icons --variant-format suffix # icon-name--large.svg
figma export icons --variant-format folder # icon-name/large.svg

Export complete theme package

figma export theme --formats "css,json,tailwind" --output ./theme
`

$3

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

`bash


Export everything

figma handoff --all --output ./design-handoff

Customize what to export

figma handoff --tokens css,scss --assets --structure --readme

Just tokens and structure (no assets)

figma handoff --tokens css,json --structure
`

Output structure:

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

$3

`bash


GET request

figma api /v1/me

With query parameters

figma api /v1/files//images -q "ids=1:2,format=svg"

POST request

figma api /v1/files//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

`bash
figma component list --file --format table
figma frame list --file --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

$3

`bash


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
`

$3

`bash


Get all components and process with jq

figma component list --file | jq '.meta.components[].name'

Export specific nodes as PNGs at 2x

figma file images --id "1:2,1:3,1:4" --format png --scale 2 --output ./exports

List all frames and their IDs

figma frame list --file --format table
`

$3

`bash


Get file structure for AI analysis

figma file structure --depth 3 --format json > structure.json

Export handoff for coding agent

figma handoff --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