minerucc

A CLI client for the MinerU OCR API v4. It parses local files and public URLs into Markdown: local files are uploaded to OSS, then polled to a terminal state, and the result zip (full.md + images/) is downloaded and extracted.

Requirements

• Node.js >= 26
• A MinerU API key (MINERUCC_API_KEY)

Installation

npm install -g @ayasechan/minerucc

To build and run from a checkout:

npm run build
node dist/index.mjs --help

Setup

The API key is required and read from the MINERUCC_API_KEY environment variable (or passed with --api-key). The service base URL defaults to https://ocr.eo.mk and can be overridden with MINERUCC_BASE_URL or --base-url.

export MINERUCC_API_KEY=your-key

Commands

parse <files...> — local files, full flow

Upload local files to OSS, submit them, poll to completion, then download and extract each result.

minerucc parse report.pdf slides.pptx --output ./results

The output defaults to ./out/<filename> (without extension); override with -o, --output <dir>. At most 50 files, each up to 200 MB.

submit <files...> — local files, no polling

Upload and submit local files, then print the batch_id and task_ids without waiting. Use get later to fetch the results.

minerucc submit report.pdf

parse-url <url> — single public URL

Submit a public URL and poll until parsed, then download and extract.

minerucc parse-url https://example.com/doc.pdf

The output defaults to ./out/<task_id>; override with -o, --output <dir>.

submit-url <url> — single public URL, no polling

Submit a public URL and print the task_id.

minerucc submit-url https://example.com/doc.pdf

batch <urls...> — multiple public URLs

Submit up to 50 public URLs, poll the batch, and download/extract each result. The output defaults to ./out/<task_id> per URL; override with -o, --output <dir>.

minerucc batch https://example.com/a.pdf https://example.com/b.pdf

status <task_id> — query one task once

minerucc status 3fa85f64-5717-4562-b3fc-2c963f66afa6

batch-status <batch_id> — query one batch once

minerucc batch-status 3fa85f64-5717-4562-b3fc-2c963f66afa6

get <task_id> — poll a submitted task, then download

Poll a previously submitted task to a terminal state, then download and extract its result. The output defaults to ./out/<task_id>; override with -o, --output <dir>.

minerucc get 3fa85f64-5717-4562-b3fc-2c963f66afa6

Global flags

Available on every command (before or after the subcommand):

| Flag | Description | | --- | --- | | --api-key <key> | API key (defaults to MINERUCC_API_KEY) | | --base-url <url> | Service base URL (defaults to MINERUCC_BASE_URL or https://ocr.eo.mk) | | --json | Print machine-readable JSON output | | --quiet | Suppress polling progress output | | --verbose | Print debug information (e.g. HTTP error bodies) |

Submit-parameter flags

Shared by parse, submit, parse-url, submit-url, and batch:

| Flag | Description | | --- | --- | | --ocr / --no-ocr | Enable/disable OCR (on by default) | | --formula / --no-formula | Enable/disable formula recognition (server default applies when unset) | | --table / --no-table | Enable/disable table recognition (server default applies when unset) | | -l, --language <lang> | Document language (default: ch) | | --model-version <ver> | Model version: vlm, pipeline, or MinerU-HTML | | --pages <ranges> | Page ranges, e.g. 1-20, 2, 4-6 | | --data-id <id> | Business ID (defaults to an auto-generated UUID) | | --extra-formats <list> | Extra export formats, comma-separated: docx,html,latex |

HTML inputs (.html/.htm) automatically select the MinerU-HTML model unless --model-version is given.

Callback flags

Used by parse and submit for local-file submissions:

| Flag | Description | | --- | --- | | --callback <url> | Callback URL called when parsing completes (requires --seed) | | --seed <string> | Random string used to sign the callback request |

Polling flags

Used by parse, parse-url, batch, and get:

| Flag | Description | | --- | --- | | --interval <ms> | Polling interval in milliseconds (default: 5000; minimum: 3000) | | --timeout <s> | Total polling timeout in seconds (default: 600) |

URL cache flags

Used by parse-url, submit-url, and batch:

| Flag | Description | | --- | --- | | --no-cache | Force re-fetching the URL, ignoring the server cache | | --cache-tolerance <sec> | Acceptable cache age in seconds; re-fetch if older |

Output

Each successful result produces a directory containing full.md and the referenced images/ folder; relative paths are preserved so the Markdown image references work as-is.

• Local files: ./out/<filename> (e.g. ./out/report/full.md)
• URL tasks: ./out/<task_id>

--json prints a single JSON object, e.g.:

{"ok":true,"kind":"parse","batchId":"...","results":[{"file":"report.pdf","taskId":"...","outputDir":"out/report","markdownPath":"/abs/out/report/full.md","imageCount":3}]}

On failure, JSON output is {"ok":false,"error":{"exitCode":1,"message":"..."}}.

Exit codes

| Code | Meaning | | --- | --- | | 0 | Success | | 1 | Generic, upload, or parse failure | | 2 | Usage error | | 3 | Authentication failure (401/403) | | 4 | Rate limited (429) | | 5 | Not found (404, or task/batch missing or expired) | | 6 | Validation or business error | | 7 | Network error | | 8 | Timeout |

Supported file types

.pdf, .png, .jpg, .jpeg, .jp2, .webp, .gif, .bmp, .doc, .docx, .ppt, .pptx, .xls, .xlsx, .html, .htm

Development

npm run build          # bundle with tsdown → dist/index.mjs
npm run dev            # tsdown --watch
npm run typecheck      # tsc --noEmit
npm test               # vitest run