FormatFerry CLI

Convert HTML, DOCX, PDF, XLSX, and CSV to clean Markdown from the command line.

npm install -g formatferry

Requires Node.js 18+.

Quick Start

# Pipe HTML from stdin
echo '<h1>Hello</h1><p>World</p>' | formatferry

# Convert a file
formatferry -i document.html -o output.md

# Convert a Word document
formatferry -i report.docx -o report.md

# Convert a PDF
formatferry -i paper.pdf -o paper.md

# Convert a spreadsheet
formatferry -i data.xlsx -o data.md

Commands

Convert (default)

The default command converts input to Markdown.

formatferry [options]

| Option | Description | |--------|-------------| | -i, --input <path> | Input file path (.html, .htm, .docx, .pdf, .xlsx, .csv) | | -o, --output <path> | Output file path (defaults to stdout) | | -f, --format <format> | Markdown format (default: github) | | --url <url> | Fetch and convert a web article (requires API key) | | --batch <glob> | Batch convert files matching a glob pattern (Premium) | | --output-dir <dir> | Output directory for batch mode |

Input Modes

1. stdin — pipe HTML content directly:

   cat page.html | formatferry
   pbpaste | formatferry          # macOS clipboard

2. File — use --input for local files:

   formatferry -i report.docx
   formatferry -i data.xlsx -f commonmark

3. URL — fetch and extract a web article (requires API key):

   formatferry --url https://example.com/article

Supported Formats

| Format | Flag Value | Description | |--------|-----------|-------------| | GitHub Flavored Markdown | github | Default. Tables, task lists, strikethrough | | CommonMark | commonmark | Strict CommonMark spec | | Slack | slack | Slack mrkdwn syntax | | Discord | discord | Discord Markdown | | Reddit | reddit | Reddit Markdown | | Confluence | confluence | Confluence wiki markup | | R Markdown | rmarkdown | R Markdown with YAML front matter | | Custom | custom | Base Markdown with no format-specific rules |

Supported File Types

| Extension | Type | Notes | |-----------|------|-------| | .html, .htm | HTML | Rich text, web pages, Google Docs exports | | .docx | Word | Microsoft Word documents (via Mammoth.js) | | .pdf | PDF | Text extraction (via PDF.js) | | .xlsx | Excel | Spreadsheets with multi-sheet support (via SheetJS) | | .csv | CSV | Comma-separated data files |

Auth

Manage license keys and API keys.

formatferry auth [options]

| Option | Description | |--------|-------------| | --license-key <key> | Activate a license key | | --api-key <key> | Activate an API key | | --status | Show current license/plan status | | --logout | Remove stored credentials |

License Key

# Activate a license key
formatferry auth --license-key FF-PREM-XXXX-XXXX

# Check status
formatferry auth --status

# Remove credentials
formatferry auth --logout

API Key

API keys enable URL extraction and are available through subscription plans.

# Activate an API key
formatferry auth --api-key ff_your_api_key_here

# Check plan and quota
formatferry auth --status

Plans

| Plan | Features | Batch | URL Extraction | |------|----------|-------|----------------| | Free | Basic conversion | No | No | | Pro | Atlassian parsing, token optimization, batch | Yes | Yes | | Credits | Pay-per-use URL extraction | No | Yes | | Agent Starter | All Pro features + rate limit | Yes | Yes | | Agent Pro | All Pro features + higher rate limit | Yes | Yes | | Agent Scale | All Pro features + highest rate limit | Yes | Yes |

Batch Convert (Premium)

Convert multiple files at once using glob patterns.

# Convert all HTML files in a directory
formatferry --batch "docs/*.html"

# Convert to a specific output directory
formatferry --batch "**/*.html" --output-dir converted/

# Convert with a specific format
formatferry --batch "*.docx" -f commonmark --output-dir output/

Batch mode requires a Premium license or a Pro/Agent API key. Output files are written with .md extension alongside the source files, or to --output-dir if specified.

The batch summary reports success/failure counts:

Batch complete: 5 succeeded, 1 failed, 6 total

Files that fail conversion (e.g., unsupported types in a broad glob) are logged to stderr and skipped — remaining files continue processing.

Configuration

Credentials are stored in a platform-specific config file:

| Platform | Path | |----------|------| | macOS/Linux | ~/.config/formatferry/config.json | | Windows | %APPDATA%\formatferry\config.json |

The config file is created with 0600 permissions (owner read/write only) on POSIX systems.

Entitlement Caching

License keys are validated against the FormatFerry license server on each CLI invocation with a 2-second timeout. If the server is unreachable:

• Cache < 7 days old: Cached entitlements are used
• Cache > 7 days old: Falls back to free tier with a warning

Revoked keys are automatically removed from the config.

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | Error (invalid input, missing file, auth failure, unsupported format) |

All errors are written to stderr. Conversion output goes to stdout (unless --output is specified).

Examples

# Convert clipboard HTML to Markdown (macOS)
pbpaste | formatferry | pbcopy

# Convert a Google Docs export
formatferry -i "My Document.html" -o document.md

# Convert all Word docs in a project
formatferry --batch "reports/**/*.docx" --output-dir markdown/

# Extract and convert a web article
formatferry --url https://blog.example.com/post -o article.md

# Use CommonMark format for strict compatibility
formatferry -i page.html -f commonmark

# Pipe through other tools
curl -s https://example.com | formatferry -f reddit

Tips

• For HTML documents over ~100 KB, prefer -i <file> over piping through stdin to avoid OS shell buffer limitations.

Development

# Install dependencies (from repo root)
npm install

# Run tests
npm test --workspace=packages/cli

# Build
npm run build --workspace=packages/cli

See PUBLISHING.md for npm publish instructions.