Font Converter CLI

A powerful command-line tool to convert WOFF and WOFF2 font files to TTF format with support for recursive directory scanning.

Features

• ✅ Convert WOFF to TTF
• ✅ Convert WOFF2 to TTF
• ✅ Single file conversion
• ✅ Batch directory conversion
• ✅ Recursive subdirectory scanning
• ✅ Maintains directory structure in output
• ✅ Comprehensive file validation
• ✅ Detailed error handling
• ✅ Verbose logging option
• ✅ Font validation using FontKit
• ✅ Cross-platform support (Windows, macOS, Linux)

Quick Start

# Install globally from npm
npm install -g @princevish/font-converter-cli

# Or install locally for development
npm install

# Convert a single font file
font-converter-cli convert input.woff

# Batch convert with recursive search
font-converter-cli batch ./fonts --recursive --verbose

# Get help
font-converter-cli --help

Installation

Global Installation (Recommended)

# Install globally from npm
npm install -g @princevish/font-converter-cli

# Verify installation
font-converter-cli --version
font-converter-cli --help

Local Development Installation

# Clone repository
git clone https://github.com/princevish/font-converter-cli.git
cd font-converter-cli

# Install dependencies
npm install

# Test the CLI
node bin/cli.js --help

# Link for global use (optional)
npm link

Requirements

• Node.js: >= 14.0.0
• npm: >= 6.0.0
• Operating System: Windows, macOS, or Linux

Usage

Basic Commands

Convert a Single Font File

# Convert WOFF to TTF
font-converter-cli convert input.woff

# Convert WOFF2 to TTF
font-converter-cli convert input.woff2

# Specify output file
font-converter-cli convert input.woff -o output.ttf

# Enable verbose logging
font-converter-cli convert input.woff --verbose

Batch Convert Multiple Files

# Convert all WOFF/WOFF2 files in a directory
font-converter-cli batch ./fonts

# Specify output directory
font-converter-cli batch ./fonts -o ./converted

# Search subdirectories recursively
font-converter-cli batch ./fonts -o ./converted --recursive

# Enable verbose logging
font-converter-cli batch ./fonts --verbose

Command Line Options

convert command

Convert a single font file from WOFF or WOFF2 to TTF.

font-converter-cli convert <input> [options]

Arguments:

• <input> - Path to the input font file (WOFF or WOFF2)

Options:

• -o, --output <output> - Specify output TTF file path (default: same directory as input)
• -v, --verbose - Enable verbose logging
• -h, --help - Display help for the convert command

Examples:

# Basic conversion
font-converter-cli convert myFont.woff

# With custom output path
font-converter-cli convert myFont.woff -o ./converted/myFont.ttf

# With verbose output
font-converter-cli convert myFont.woff2 --verbose

batch command

Convert multiple font files in a directory.

font-converter-cli batch <directory> [options]

Arguments:

• <directory> - Directory containing WOFF/WOFF2 files

Options:

• -o, --output-dir <dir> - Output directory for converted TTF files (default: same as input)
• -r, --recursive - Search subdirectories recursively for font files
• -v, --verbose - Enable verbose logging
• -h, --help - Display help for the batch command

Examples:

# Convert all fonts in current directory
font-converter-cli batch .

# Convert with output directory
font-converter-cli batch ./source-fonts -o ./converted-fonts

# Recursive search in subdirectories
font-converter-cli batch ./fonts --recursive --verbose

# Verbose batch conversion
font-converter-cli batch ./fonts --verbose

Global Options

• -V, --version - Display version number
• -h, --help - Display help information

Common Use Cases

1. Web Font Migration

Convert web fonts to TTF for desktop applications:

font-converter-cli batch ./web-assets/fonts --recursive -o ./desktop-fonts --verbose

2. Development Workflow

Convert downloaded fonts for local development:

font-converter-cli convert downloaded-font.woff2 -o ./src/assets/fonts/font.ttf

3. Font Library Organization

Process complex font directory structures:

# Your fonts are organized like this:
# fonts/
# ├── family1/
# │   ├── woff/
# │   └── woff2/
# ├── family2/
# │   ├── woff/
# │   └── woff2/
# └── ...

# Convert all with preserved structure:
font-converter-cli batch ./fonts --recursive -o ./converted-fonts

4. Selective Conversion

Convert specific font formats or families:

# Convert only WOFF files from one family
font-converter-cli batch ./fonts/poppins/woff -o ./converted

# Convert only WOFF2 files from one family
font-converter-cli batch ./fonts/poppins/woff2 -o ./converted

Supported Formats

Input Formats

• WOFF (.woff) - Web Open Font Format
• WOFF2 (.woff2) - Web Open Font Format 2.0

Output Format

• TTF (.ttf) - TrueType Font

Examples

Single File Conversion

# Convert a WOFF file
$ font-converter-cli convert OpenSans-Regular.woff
✅ Successfully converted to: OpenSans-Regular.ttf

# Convert with verbose output
$ font-converter-cli convert OpenSans-Bold.woff2 --verbose
Detected format: woff2
Input file size: 45623 bytes
Converting WOFF2 to TTF...
Font family: Open Sans
Font style: Bold
Number of glyphs: 937
Output file size: 87234 bytes
✅ Successfully converted to: OpenSans-Bold.ttf

Batch Conversion

# Convert all fonts in a directory
$ font-converter-cli batch ./web-fonts --verbose
Found 5 font files to convert
Converting: OpenSans-Regular.woff
✅ OpenSans-Regular.woff -> OpenSans-Regular.ttf
Converting: OpenSans-Bold.woff
✅ OpenSans-Bold.woff -> OpenSans-Bold.ttf
Converting: OpenSans-Italic.woff2
✅ OpenSans-Italic.woff2 -> OpenSans-Italic.ttf
Converting: OpenSans-BoldItalic.woff2
✅ OpenSans-BoldItalic.woff2 -> OpenSans-BoldItalic.ttf
Converting: Roboto-Regular.woff
✅ Roboto-Regular.woff -> Roboto-Regular.ttf
✅ Successfully converted 5 files

Recursive Directory Search

# Convert fonts from nested directories
$ font-converter-cli batch ./fonts --recursive --verbose
Recursive mode: searching subdirectories
Found 78 font files to convert
Files found in subdirectories:
  poppins/woff/poppins-regular.woff
  poppins/woff2/poppins-bold.woff2
  roboto/woff/roboto-medium.woff
  ...
Converting: poppins/woff/poppins-regular.woff
✅ poppins/woff/poppins-regular.woff -> poppins/woff/poppins-regular.ttf
Converting: poppins/woff2/poppins-bold.woff2
✅ poppins/woff2/poppins-bold.woff2 -> poppins/woff2/poppins-bold.ttf
...
✅ Successfully converted 31 files
⚠️  Failed to convert 47 files

Error Handling

The tool provides detailed error messages for various scenarios:

# File not found
$ font-converter-cli convert nonexistent.woff
❌ Conversion failed: Validation failed: File not found: nonexistent.woff

# Invalid format
$ font-converter-cli convert document.pdf
❌ Conversion failed: Validation failed: Unsupported file extension: .pdf. Supported formats: .woff, .woff2

# Permission denied
$ font-converter-cli convert protected.woff -o /system/fonts/
❌ Conversion failed: Validation failed: Permission denied: cannot write to /system/fonts/

Technical Details

Dependencies

• commander - Command line argument parsing and CLI interface
• fontkit - Font parsing, validation, and metadata extraction
• wawoff2 - High-performance WOFF2 decompression

Conversion Algorithms

WOFF to TTF Process:

1. ✅ Signature Validation - Verifies WOFF magic number (0x774F4646)
2. ✅ Header Parsing - Extracts font metadata and table information
3. ✅ Decompression - Uses zlib to decompress table data
4. ✅ TTF Reconstruction - Rebuilds proper TTF structure with correct offsets
5. ✅ Validation - Verifies output integrity with FontKit

WOFF2 to TTF Process:

1. ✅ Signature Validation - Verifies WOFF2 magic number (0x774F4632)
2. ✅ Modern Decompression - Uses Brotli algorithm via wawoff2 library
3. ✅ Binary Processing - Handles complex WOFF2 transformations
4. ✅ TTF Output - Produces standard TTF format
5. ✅ Quality Assurance - FontKit validation ensures font integrity

Performance Characteristics

• File Size: Handles fonts from 100 bytes to 50MB
• Batch Processing: Efficiently processes large font collections
• Memory Usage: Optimized for minimal memory footprint
• Error Recovery: Graceful handling of corrupted or invalid fonts
• Cross-Platform: Works on Windows, macOS, and Linux

Font Validation

The tool performs comprehensive validation at multiple stages:

1. Pre-Conversion Validation:

   • File existence and permissions
   • File size constraints (100 bytes - 50MB)
   • Format signature validation
   • Path security checks

2. Post-Conversion Validation:

   • Font structure integrity using FontKit
   • Glyph count verification
   • Font metadata extraction (family name, style, etc.)
   • Output file size validation

3. Error Handling:

   • Detailed error messages with context
   • Non-destructive operation (original files preserved)
   • Batch processing continues on individual failures
   • Exit codes for automation integration

Troubleshooting

Common Issues

"No WOFF or WOFF2 files found"

Problem: The CLI can't find font files in the specified directory.

Solutions:

# If fonts are in subdirectories, use --recursive
node bin/cli.js batch ./fonts --recursive

# Check if files have correct extensions (.woff or .woff2)
ls ./fonts/  # or dir fonts\ on Windows

# Target specific subdirectory
node bin/cli.js batch ./fonts/font-family/woff

"WOFF2 decompression failed"

Problem: WOFF2 file might be corrupted or use an unsupported variant.

Solutions:

# Try converting individual files to isolate the issue
node bin/cli.js convert problem-font.woff2 --verbose

# Check file integrity
file problem-font.woff2  # On Linux/macOS

"Permission denied"

Problem: Insufficient permissions to read input or write output.

Solutions:

# Ensure you have read permissions on input directory
chmod +r ./fonts/* # Linux/macOS

# Ensure write permissions on output directory
mkdir -p ./output && chmod +w ./output

# Or specify a different output directory
node bin/cli.js batch ./fonts -o ~/Desktop/converted-fonts

"File too large" or "File too small"

Problem: Font file size is outside supported range (100 bytes - 50MB).

Solutions:

• Files smaller than 100 bytes are likely corrupted
• Files larger than 50MB may be invalid or contain multiple fonts
• Use ls -lh (Linux/macOS) or dir (Windows) to check file sizes

Performance Tips

1. Use verbose mode to monitor progress: --verbose
2. Process in smaller batches if you have thousands of fonts
3. Use SSD storage for faster I/O operations
4. Close other applications if processing very large font collections

Getting Help

# General help
node bin/cli.js --help

# Command-specific help
node bin/cli.js convert --help
node bin/cli.js batch --help

# Version information
node bin/cli.js --version

Error Codes

The CLI uses standard exit codes for automation integration:

• 0 - ✅ Success - All operations completed successfully
• 1 - ❌ Conversion failure - Font conversion process failed
• 1 - ❌ Validation failure - Input validation failed
• 1 - ❌ File system error - I/O or permission errors

Changelog

v1.0.0 (Latest)

• ✅ Initial release with WOFF and WOFF2 support
• ✅ Single file and batch conversion
• ✅ NEW: Recursive directory scanning with --recursive flag
• ✅ NEW: Directory structure preservation in output
• ✅ IMPROVED: Enhanced WOFF2 support with wawoff2 library
• ✅ Comprehensive error handling and validation
• ✅ FontKit integration for quality assurance
• ✅ Cross-platform compatibility
• ✅ Verbose logging and detailed progress reporting

Roadmap

Planned Features

• 📅 GUI Version - Electron-based desktop application
• 📅 Watch Mode - Automatic conversion on file changes
• 📅 Configuration Files - JSON/YAML config for batch settings
• 📅 Plugin System - Custom conversion pipelines
• 📅 Font Optimization - Size reduction and glyph subsetting
• 📅 Metadata Preservation - Font licensing and attribution info
• 📅 Format Detection - Auto-detect optimal output format
• 📅 Progress Bar - Visual progress indication for large batches

License

ISC License

Contributing

We welcome contributions! Here's how you can help:

Development Setup

# Clone the repository
git clone <repository-url>
cd font-converter

# Install dependencies
npm install

# Run tests
npm test

# Test CLI locally
node bin/cli.js --help

Contribution Guidelines

1. Fork the repository and create a feature branch
2. Write tests for new functionality
3. Follow existing code style and conventions
4. Update documentation including README and examples
5. Test thoroughly on different platforms if possible
6. Submit a pull request with clear description

Areas for Contribution

• 🐛 Bug fixes - Report and fix issues
• ✨ New features - Implement roadmap items
• 📝 Documentation - Improve guides and examples
• 🧪 Testing - Add test cases and improve coverage
• 🌍 Localization - Add support for other languages
• 🚀 Performance - Optimize conversion algorithms

Reporting Issues

When reporting bugs, please include:

• Operating system and Node.js version
• Font file details (format, size, source)
• Complete error message or output
• Steps to reproduce the issue
• Sample font files if possible (and permissible)

Support

Documentation

• 📚 README - Complete usage guide (this document)
• 📜 Examples - See examples/ directory for more samples
• 🚀 CLI Help - Use --help flag with any command

Community

• 💬 Issues - Report bugs and request features
• 📬 Discussions - Ask questions and share tips
• 👥 Contributors - Join our development community

Commercial Support

• 🏢 Enterprise - Custom features and priority support available
• 📞 Consulting - Font workflow optimization and integration
• 🎆 Training - Team workshops on font management

For issues, questions, or contributions, please visit the project repository.

Made with ❤️ for the web development community

Font Converter CLI - Transform your font workflows with confidence