BlazeDocs documentation

CLI & API reference

PDF to Markdown for coding agents by default, with optional table-preserving HTML when agents need layout fidelity. The BlazeDocs CLI is the primary surface; an HTTP API and an Agent Skill ship alongside it. Install once, run from any shell, script it in CI, or hand it to your coding agent.

Format support: PDFs only. Markdown is the default output; pass HTML when table-heavy reports, forms, and specs need browser-native structure preserved.

Get API key Quick start CLI source on GitHub

$ node --version
$ npm install -g blazedocs
$ blazedocs convert ./paper.pdf --output paper.md

Quick start

Three steps from zero to converted Markdown. Add --output-format html when tables and formatting matter.

Install the CLI (Node.js 18 or later required).
Get an API key from the dashboard.
Run blazedocs convert against any PDF.

bash

node --version   # v18 or newer
npm install -g blazedocs
blazedocs            # guided setup, prompts for API key
blazedocs convert ./paper.pdf --output paper.md
blazedocs convert ./paper.pdf --output-format html --output paper.html

Prefer non-interactive auth? Set BLAZEDOCS_API_KEY in the environment and skip the setup step.

Install

The CLI ships as a single npm package. Pick the package manager you already use after confirming Node.js 18 or later.

bash

node --version

npm install -g blazedocs
pnpm add -g blazedocs
yarn global add blazedocs
bun add -g blazedocs

Verify the install:

bash

blazedocs --version
blazedocs version
blazedocs --help
blazedocs help

Requires Node.js 18 or later. The CLI is the primary supported surface — the HTTP API exists for environments where you cannot run Node.

Why do I get npm WARN EBADENGINE or SyntaxError: Unexpected token '?'?

Your Node.js version is too old. The BlazeDocs CLI requires Node.js 18+. Upgrade Node.js, then reinstall the latest CLI package:

bash

node --version
npm install -g blazedocs@latest

Authentication

Generate an API key from Dashboard → API Keys. Keys begin with bd_live_.

CLI (recommended)

bash

# Interactive — prompts for the key, stores it at ~/.blazedocs/config.json (mode 0600)
blazedocs login

# Or pipe the key in (CI-friendly)
echo "$MY_KEY" | blazedocs login --api-key-stdin

# Confirm the active identity
blazedocs whoami

Environment variable

For CI and agent workflows, set BLAZEDOCS_API_KEY. It overrides the stored config.

bash

export BLAZEDOCS_API_KEY=bd_live_xxxxxxxxxx
blazedocs convert ./paper.pdf

HTTP requests

Pass the key via either header:

http

Authorization: Bearer bd_live_xxxxxxxxxx
# or
x-api-key: bd_live_xxxxxxxxxx

Never commit keys to source control. Use environment variables in production. Keys are redacted from CLI output.

Common workflows

Convert a single PDF

bash

blazedocs convert ./paper.pdf --output paper.md
blazedocs convert ./paper.pdf --output-format html --output paper.html

Convert a URL

bash

blazedocs convert https://example.com/report.pdf --output report.md

Stream Markdown to another tool

bash

blazedocs --raw convert ./paper.pdf | pbcopy

Batch conversion with summary

bash

# Continue through failures, write summary.json, emit JSONL
blazedocs convert --batch ./*.pdf \
  --concurrency 1 \
  --on-error continue \
  --summary summary.json \
  --json

Multiple files into a directory

bash

blazedocs convert ./a.pdf ./b.pdf ./c.pdf --output ./markdown/

Idempotency for retried jobs

Avoid double-billing when your job runner retries the process:

bash

blazedocs convert ./report.pdf \
  --idempotency-key job-2026-04-25-001 \
  --json

Parse only successful results

bash

blazedocs convert ./*.pdf --json | jq -c 'select(.type=="result")'

Diagnose environment issues

bash

# Checks auth, network, config, Node version, disk, and CLI version
blazedocs doctor --json

Output

Default (TTY)

Markdown to stdout (or to --output), with a small status footer. Designed for humans.

--json

JSONL on stdout, one envelope per line. A successful conversion:

json

{
  "type": "result",
  "data": {
    "markdown": "# Title\n\n...",
    "page_count": 12,
    "token_count": 4200,
    "processing_time_ms": 1234,
    "file_name": "paper.pdf",
    "usage": {
      "pages_used": 42,
      "pages_limit": 1000,
      "pages_remaining": 958
    }
  }
}

When --output is set, the payload also includes written_to.

--raw

Pure payload only — for convert that means Markdown by default, or HTML with --output-format html. No progress, no banner, no footer. Pipe-safe.

Batch summary

json

{
  "total": 2,
  "succeeded": 1,
  "failed": 1,
  "results": [
    {
      "input": "a.pdf",
      "status": "failed",
      "error": {
        "code": "QUOTA_EXCEEDED",
        "message": "slow down",
        "exit_code": 2
      }
    },
    {
      "input": "b.pdf",
      "status": "succeeded",
      "pages": 3,
      "tokens": 42
    }
  ]
}

Errors under --json

Errors go to stderr as a single JSON line:

json

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Not authenticated.",
    "hint": "Run `blazedocs` to open setup, or set BLAZEDOCS_API_KEY.",
    "exit_code": 3
  }
}

Commands

bash

blazedocs convert <file-or-url...> [--output <path>] [--output-format markdown|html] [--batch]
blazedocs usage
blazedocs whoami
blazedocs doctor
blazedocs skills get core
blazedocs skills install
blazedocs skills list
blazedocs login [--api-key-stdin]
blazedocs logout

Flags & exit codes

Global flags

Flag	Effect
--json	Structured JSON on stdout; structured error JSON on stderr.
--raw	Pure payload only. For convert, Markdown only.
--silent	Suppress progress output. CI-compatible.
--yes	Accept interactive defaults. Agents and CI set this.
--version	Print the version.
--help	Print help.

Exit codes

Code	Meaning
0	Success
1	Generic failure: file not found, network error, invalid args, or API error
2	Quota or rate limit exceeded
3	Authentication required or invalid

Stable error codes

Returned in the error.code field of structured (--json) output. Safe to switch on.

text

AUTH_REQUIRED   QUOTA_EXCEEDED   NETWORK_ERROR    API_ERROR
FILE_NOT_FOUND  INVALID_ARGS     SKILL_NOT_FOUND  INTERNAL

Environment

Variable	Effect
BLAZEDOCS_API_KEY	Overrides ~/.blazedocs/config.json. Agents and CI prefer this.
BLAZEDOCS_INTERACTIVE	Set 0 to force non-interactive, 1 to force interactive.
BLAZEDOCS_SKIP_UPDATE_CHECK	1 disables npm registry upgrade checks.
BLAZEDOCS_NO_BANNER	1 suppresses the ANSI banner on TTY.
BLAZEDOCS_ASCII_LOGO	1 swaps Unicode block chars for plain ASCII logo.
NO_COLOR	Any non-empty value disables ANSI colors.
CI	Any non-empty value suppresses interactive prompts.

Keys stored by login live at ~/.blazedocs/config.json with mode 0600.BLAZEDOCS_API_KEY wins over the config file.

Agent Skill

The Agent Skill teaches Claude Code, Cursor, Codex, and any skill.sh-compatible coding agent how to use the BlazeDocs CLI: commands, flags, output shapes, and recovery paths.

Install via skill.sh (recommended)

bash

npx skills add https://github.com/kyle93afc/blazedocs-cli --skill blazedocs

This uses the same installer and location discovery as the rest of the agent-skill ecosystem.

Install via the CLI (offline / local)

bash

blazedocs skills install
blazedocs skills install --target-dir ~/.claude/skills --force

What agents get

Once installed, an agent can call blazedocs skills get core to load the full operations manual: commands, flags, exit codes, JSON shapes, and common recovery paths.

HTTP API

Use the HTTP API directly when you cannot run the CLI — for example, from a serverless function in a non-Node runtime, or from a language that has no Node bridge. For everything else, prefer the CLI.

POST /api/v1/convert

POSThttps://blazedocs.io/api/v1/convert

Multipart upload:

bash

curl -X POST https://blazedocs.io/api/v1/convert   -H "Authorization: Bearer bd_live_YOUR_KEY"   -F "file=@paper.pdf"   -F "output_format=html"

Or base64-encoded JSON:

bash

curl -X POST https://blazedocs.io/api/v1/convert   -H "Authorization: Bearer bd_live_YOUR_KEY"   -H "Content-Type: application/json"   -d '{"file_base64": "<base64-pdf>", "file_name": "paper.pdf", "output_format": "html"}'

Set output_format to html when you need a browser-ready document with complex tables preserved as HTML, including rowspan/colspan. Omit it, or pass markdown, for the default Markdown output.

HTML output is OCR-derived and should be treated as untrusted input. BlazeDocs sanitizes table fragments before returning them, but apps that render converted HTML should still sandbox or sanitize again.

Response:

json

{
  "success": true,
  "data": {
    "output_format": "html",
    "content": "<!doctype html>...",
    "markdown": "# Document Title

[tbl-0.html](tbl-0.html)",
    "html": "<!doctype html>...<table>...</table>...",
    "table_count": 3,
    "page_count": 5,
    "token_count": 4820,
    "processing_time_ms": 3200,
    "file_name": "paper.pdf"
  },
  "usage": {
    "pages_used": 45,
    "pages_limit": 500,
    "pages_remaining": 455
  }
}

GET /api/v1/convert

GEThttps://blazedocs.io/api/v1/convert

Returns your current tier, usage, and limits without performing a conversion.

bash

curl https://blazedocs.io/api/v1/convert \
  -H "Authorization: Bearer bd_live_YOUR_KEY"

json

{
  "tier": "starter",
  "usage": {
    "monthlyConversions": 12,
    "monthlyPages": 45,
    "monthlyTokens": 52000
  },
  "limits": {
    "conversions": 50,
    "pages": 500,
    "tokens": 500000,
    "fileSize": 20971520
  }
}

Rate-limit headers

Every response includes:

Header	Description
X-RateLimit-Limit	Total pages allowed per month
X-RateLimit-Remaining	Pages remaining this month
X-RateLimit-Reset	Unix timestamp when limits reset

BlazeDocs Connect

Connect lets a third-party tool obtain a BlazeDocs API key with a single user-approval click instead of asking the user to navigate the dashboard. It is intended for SDK and integration authors. For everyday CLI use, run blazedocs login.

bashconnect.sh

# 1. Create a session
curl -X POST https://blazedocs.io/api/connect/session \
  -H "Content-Type: application/json" \
  -d '{"provider": "openclaw"}'
# -> { "sessionId": "...", "approvalUrl": "..." }

# 2. Open approvalUrl in a browser. User clicks Approve.

# 3. Exchange the session for an API key
curl -X POST https://blazedocs.io/api/connect/exchange \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "..."}'
# -> { "apiKey": "bd_live_..." }

Connect mints a standard BlazeDocs API key — same quota, same billing, same revocation surface as a key created from the dashboard.

Plans & limits

CLI and API share the same monthly quota. Limits reset on the first of each calendar month UTC.

Plan	Price	Pages / mo	Best for
Free	$0	3 conversions, first 5 pages each	Testing & evaluation
Starter	$7.99/mo	500	Side projects & personal use
Pro	$14.99/mo	2,500	RAG pipelines & AI agents
Enterprise	$49.99/mo	10,000	Production workloads

Prices shown for annual billing. Monthly billing is on the pricing page.

Need more? support@blazedocs.io for custom enterprise pricing.

HTTP errors

All HTTP errors share a consistent format. For CLI error codes, see Flags & exit codes.

json

{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}

Status	Code	Description
400	BAD_REQUEST	Missing file, invalid PDF, or malformed request body
401	UNAUTHORIZED	Invalid or missing API key
413	FILE_TOO_LARGE	PDF exceeds your plan's file size limit
415	UNSUPPORTED_TYPE	Content-Type must be multipart/form-data or application/json
429	RATE_LIMITED	Monthly conversion limit exceeded — upgrade your plan
500	SERVER_ERROR	Internal error — retry or contact support

Get your API key

Free tier includes 3 conversions per month. No credit card required. Install the CLI, run blazedocs, and you are ready in under a minute.

Get API key View plans CLI source