npm package: @mstrathman/figma
Description: 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.
Author: mstrathman
Latest version: 0.2.2

# 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
```

### From source

```bash
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](https://www.figma.com/developers/api#access-tokens).

```bash
# 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](https://www.figma.com/developers/apps) first.

```bash
# 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

```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
```

### Files

```bash
# 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

```bash
# 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

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

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

### Components

```bash
# 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

```bash
# 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)

```bash
# 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)

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
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

```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
```

### Automate with scripts

```bash
# 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

```bash
# 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