spek-cli

CLI tool to download and extract Figma design specs from Directus.

Installation

npx spek-cli

Usage

Interactive Mode

Simply run without arguments to be prompted for the file ID:

npx spek-cli

Direct Download

Download a specific file by ID:

npx spek-cli -d <file-id>
# or
npx spek-cli --download <file-id>

First Run Setup

On first run, you'll be prompted to configure:

1. Directus Instance URL: Your Directus instance (e.g., https://my-instance.directus.app)
2. Access Token: Your Directus access token for authentication

Configuration is saved to ~/.spek-cli/config.json

Features

• ✅ Download files from Directus using official SDK
• ✅ Automatic authentication with access token
• ✅ Extract ZIP files to named folder (based on filename)
• ✅ Prompt before overwriting existing folders
• ✅ Auto-setup configuration on first run
• ✅ Interactive and direct command modes

Configuration

Configuration file location: ~/.spek-cli/config.json

{
  "directusUrl": "https://my-instance.directus.app",
  "accessToken": "your-access-token",
  "createdAt": "2026-02-13T..."
}

Examples

# First time - interactive setup
npx spek-cli
# Prompts for: Directus URL, Access Token, File ID

# Subsequent runs - direct download
npx spek-cli -d abc123-def456-ghi789

# Interactive mode (prompts for file ID only)
npx spek-cli

Output Structure

When you download a file, it will be extracted into a folder named after the file:

# If the file in Directus is named "design-specs-v1.zip"
npx spek-cli -d abc123

# Creates structure:
./design-specs-v1/
├── README.md
├── manifest.json
├── components/
├── icons/
└── images/

Error Handling

The CLI handles common errors gracefully:

• Invalid authentication: Check your access token
• File not found: Verify the file ID exists in Directus
• Network errors: Check your internet connection
• Corrupted ZIP: The downloaded file is invalid
• Permission errors: Ensure write access to current directory

Help

npx spek-cli --help

Version

npx spek-cli --version

Development

This CLI tool is part of the specs-figma monorepo.

Build

npm run build

Watch Mode

npm run dev

Local Testing

Linux/macOS:

# Build first
npm run build

# Run locally
node dist/index.js -d <file-id>

Windows:

# Build first
npm run build

# Run locally
node dist/index.js -d <file-id>

Note for Windows users: See WINDOWS_DEVELOPMENT.md for detailed Windows-specific development guide.

License

MIT