doc2x-cli
/doc2x-cli
Installs and operates @noedgeai-org/doc2x-cli for document parsing, translation, and batch processing. Trigger when user mentions doc2x, doc2x-cli, PDF to Markdown, PDF OCR, document translation, batch PDF conversion, or bilingual PDF. Covers install, update, parse, translate, batch, login, logout, models, and term commands. Do NOT trigger for general PDF viewing, browser-based PDF tools, or non-doc2x workflows.
- Author
- noedgeai ↗
- Repository
- doc2x-cli-skills ↗
- Licence
- MIT
- Last repository change
- 21.09.2026
Assessment and security
- Files in this package
- 7
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 2
No signals detected. Repository changed on 21.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Installs and operates @noedgeai-org/doc2x-cli for document parsing, translation, and batch processing. Trigger when user mentions doc2x, doc2x-cli, PDF to Markdown, PDF OCR, document translation, batch PDF conversion, or bilingual PDF. Covers install, update, parse, translate, batch, login, logout, models, and term commands. Do NOT trigger for general PDF viewing, browser-based PDF tools, or non-doc2x workflows.
Original author description
Installs and operates @noedgeai-org/doc2x-cli for document parsing, translation, and batch processing. Trigger when user mentions doc2x, doc2x-cli, PDF to Markdown, PDF OCR, document translation, batch PDF conversion, or bilingual PDF. Covers install, update, parse, translate, batch, login, logout, models, and term commands. Do NOT trigger for general PDF viewing, browser-based PDF tools, or non-doc2x workflows.
How it works
- Quick Reference
- Preflight — run once before first doc2x command
- Authentication
- Commands
- Global Options
- Config File
- Exit Codes
- Troubleshooting
- References
SKILL.md preview
---
name: doc2x-cli
description: "Installs and operates @noedgeai-org/doc2x-cli for document parsing, translation, and batch processing. Trigger when user mentions doc2x, doc2x-cli, PDF to Markdown, PDF OCR, document translation, batch PDF conversion, or bilingual PDF. Covers install, update, parse, translate, batch, login, logout, models, and term commands. Do NOT trigger for general PDF viewing, browser-based PDF tools, or non-doc2x workflows."
license: MIT
metadata:
author: noedgeai
version: "0.2.0"
---
# Doc2X CLI
CLI tool for parsing PDFs/images to Markdown, LaTeX, Word, HTML, or PDF — and translating documents to 11 languages with bilingual output.
Targets CLI **0.2.0**. Check the installed version's help before using newer options. Website features are not automatically CLI features; see [translation and export modes](references/command-reference.md#translation-and-export-modes).
**IMPORTANT — Serial execution only:** Doc2X enforces a server-side concurrent task limit. You MUST run all doc2x commands sequentially — never launch multiple `doc2x` processes in parallel (no concurrent Agent tool calls, no background tasks, no `&`). Batch commands always run sequentially (concurrency is hardcoded to 1). Violating this causes "task limit exceeded" errors.
**IMPORTANT — Stable versions only:** NEVER install or use beta, alpha, rc, or any pre-release versions of `@noedgeai-org/doc2x-cli`. Always use the `@latest` tag explicitly when installing or updating. If `npm outdated` or `npm view` shows a pre-release version (e.g., `1.2.0-beta.1`), ignore it and stick with the latest stable release.
$ARGUMENTS
## Quick Reference
| Task | Command |
|------|---------|
| Parse PDF → Markdown | `doc2x parse ./paper.pdf` |
| Parse PDF → Word | `doc2x parse ./paper.pdf --to docx --docx-template academic` |
| Parse image → Markdown | `doc2x parse ./scan.png --to md` |
| Translate → Chinese | `doc2x translate ./paper.pdf` |
| Translate → English HTML | `doc2x translate ./paper.pdf --target-language en --to html` |
| Preserved-layout bilingual PDF | `doc2x translate ./paper.pdf --translate-type pdf --target-language en --pdf-font-strategy page-optimal` |
| Batch parse | `doc2x batch parse ./docs` |
| Batch translate | `doc2x batch translate ./docs --glob "**/*.pdf" --target-language en` |
| List models | `doc2x models list` |
| Manage glossary | `doc2x term list` |
| Login (OAuth) | `doc2x login` |
| Logout | `doc2x logout` |
| Account/quota/subscription | `doc2x account status --json` |
| Task result history | `doc2x records list --kind translate --limit 20 --json` |
| One task's reported usage | `doc2x usage show --translate-id ot_example --json` |
| Model details/guidance | `doc2x models show 10001 --json` / `doc2x models guide` |
## Preflight — run once before first doc2x command
**You MUST perform these checks at the start of every conversation before running any doc2x command.** Do not skip this even if the user appears to have doc2x installed.
### 1. Check Node.js version
```bash
node --version
```
Node.js must be >= 22. Tell the user to upgrade first if it is lower.
### 2. Check if doc2x CLI is installed
```bash
doc2x --version
```
- **"command not found"** → CLI is not installed. Go to step 3.
- **Version number shown** → CLI is installed. Go to step 4.
### 3. Install (if not installed)
```bash
npm i -g @noedgeai-org/doc2x-cli@latest
doc2x --help
```
If `command not found` after install: run `npm config get prefix` and tell the user to add `<prefix>/bin` to their PATH.
After successful install, proceed to the user's request — skip step 4.
### 4. Check for updates (if already installed)
```bash
npm view @noedgeai-org/doc2x-cli dist-tags.latest
```
Compare the output with the currently installed version. If a newer stable version is available, update:
```bash
npm i -g @noedgeai-org/doc2x-cli@latest
```
**CRITICAL:** Always use `dist-tags.latest` to find the stable version. NEVER use `npm outdated` (it may resolve to beta/pre-release versions). NEVER install a version containing `-beta`, `-alpha`, `-rc`, or any pre-release suffix.
Inform the user of the version change before proceeding.
## Authentication
```bash
# Auto mode — saved CLI OAuth login if present, otherwise desktop session
doc2x parse ./file.pdf
# OAuth mode — no desktop app needed; browser must reach this machine's callback
doc2x login # Opens browser for OAuth login (PKCE)
doc2x models list --auth-mode oauth # Verify the new login
doc2x parse ./file.pdf --auth-mode oauth # Uses stored OAuth credentials
# Print login URL instead of opening browser
doc2x login --no-browser
# Clear stored OAuth credentials
doc2x logout
```
Since 0.1.11, ordinary commands automatically use the saved CLI login. Explicit `--auth-mode client/oauth` or `authMode` in `--config` overrides auto selection; OAuth refresh failure never falls back to another desktop account. On 0.1.9, pass `--auth-mode oauth` after login. `--no-browser` only prints a URL: it still needs a callback to a random local port within 120 seconds, not a device-code flow. For remote machines, read [config and authentication](references/config-and-auth.md#choosing-the-right-mode).
Client mode connects to the desktop client at `127.0.0.1:34123`. Falls back to encrypted storage at:
- macOS: `~/Library/Application Support/doc2x/doc2x-store-data.json`
- Windows: `%APPDATA%/doc2x/doc2x-store-data.json`
- Linux: `~/.config/doc2x/doc2x-store-data.json`
OAuth mode stores credentials at:
- macOS: `~/Library/Application Support/doc2x/cli-oauth-tokens.json`
- Windows: `%APPDATA%/doc2x/cli-oauth-tokens.json`
- Linux: `~/.config/doc2x/cli-oauth-tokens.json`
## Commands
For account, points, retained history or failure recovery, read [account and receipts](references/account-and-receipts.md). Every parse/translate attempt now creates an atomic receipt, including when later export/download fails. Preserve its task IDs; `--to none` is successful processing without export. Receipt files contain local paths; review before sharing.
For Zotero input/output, read [Zotero workflow](references/zotero-workflow.md). `doc2x zotero manifest` prepares metadata and verifies local artifacts; actual attachment/note writes require a capable external Zotero tool. Never report the manifest as an import.
Account consumption history remains restricted. Do not invent `usage list`, bypass OAuth restrictions, or change accounts to obtain restricted history. `usage show` only uses existing per-task detail data; missing/zero defaults are not confirmed zero charges or refunds.
### parse
```bash
doc2x parse <input> [options]
```
Converts PDF or image to another format. Supported inputs: PDF (≤300 MB), PNG/JPG/JPEG/GIF/BMP (≤3 MB). **Not supported:** WebP, TIFF.
```bash
doc2x parse ./paper.pdf # → Markdown (default)
doc2x parse ./paper.pdf --to docx --docx-template academic # → Word
doc2x parse ./paper.pdf --to tex # → LaTeX
doc2x parse ./paper.pdf --to html # → HTML (client-rendered with MathJax)
doc2x parse ./paper.pdf --to pdf # → Re-typeset PDF
doc2x parse ./paper.pdf --to none --json # Parse only, no export
doc2x parse ./scan.png --to md # Image OCR
doc2x parse ./paper.pdf --image-models doc2x mathpix # With Mathpix (subscription)
doc2x parse ./paper.pdf --name "{basename}-{date}" # Custom filename
```
**IMPORTANT:** `--formula-mode dollar` only works with `--to md`. `--image-hosting online` stores images for only 30 days. `doc2x` in `--image-models` is mandatory and cannot be removed. `--docx-template` applies to V3 Word exports (`--to docx`) only. Values: `default`, `general`, `academic`, `business`, `elegant`, `minimal`, `technical`.
Load `references/command-reference.md` for the full option table.
### translate
```bash
doc2x translate <input> [options]
```
Inherits all parse options. Choose reflowed bilingual content (`md`) or preserved-layout PDF (`pdf`). The default translation model is Free (`10001`); use `models list` for current model availability.
```bash
doc2x translate ./paper.pdf # → Chinese (default)
doc2x translate ./paper.pdf --target-language en --to html # → English HTML
doc2x translate ./paper.pdf --translate-type pdf --target-language en --pdf-font-strategy page-optimal # → Bilingual PDF
doc2x translate ./paper.pdf --target-language en --to docx --docx-template technical # → Translated Word
doc2x translate ./paper.pdf --target-language en --term-id glossary1 # With glossary
doc2x translate ./paper.pdf --target-language ja --convert-trans translate # Translation only
doc2x translate ./paper.pdf --ignore-translate-types table code # Skip tables/code
doc2x translate ./paper.pdf --contextual-translation # Enhanced context
```
Languages: `zh en ja fr ru pt pt-BR es de ko ar`.
Fixed-layout PDF (`--translate-type pdf`) preserves page layout and exports a side-by-side bilingual PDF (original left, translation right). In 0.1.11 it defaults to `--to pdf` and rejects incompatible formats or `--convert-trans origin/translate` before upload; `--to none` skips export. Version 0.1.9 silently ignored those incompatible options. `--pdf-font-strategy`: `global-consistent` (default) or `page-optimal`. Use `--translate-type md --convert-trans translate --to docx` for a reflowed translation-only Word document.
Do not suggest `combinedTranslate` or combined-output CLI flags; the current stable CLI does not expose them.
### batch
```bash
doc2x batch <parse|translate> [inputs...] [options]
```
```bash
doc2x batch parse ./docs # Sequential parse
doc2x batch translate ./papers --glob "**/*.pdf" --target-language en # Batch translate
doc2x batch parse ./docs --dry-run # Preview matches
doc2x batch parse ./docs --continue-on-error --report ./report.json # Fault-tolerant
```
**CRITICAL:** Batch always runs sequentially (concurrency hardcoded to 1). Running multiple `doc2x` commands in parallel will trigger "task limit exceeded" errors. Always process one `doc2x` command at a time.
Defaults: `--glob "**/*.{pdf,png,jpg,jpeg}"`, `--skip-existing true`, `--report ./doc2x-report.json`. Exit code 6 when some files fail with `--continue-on-error`.
### login / logout
```bash
doc2x login # Opens browser for OAuth login
doc2x login --no-browser # Print login URL instead
doc2x logout # Clear stored OAuth credentials
```
### models list
```bash
doc2x models list # Table: Model ID, Name, Subscription, Flags
doc2x models list --json # JSON array
```
### term (glossary management)
```bash
doc2x term list # List glossaries
doc2x term create --name "Medical Terms" # Create → returns ID
doc2x term items --term-id <id> # View entries
doc2x term import --term-id <id> --file ./terms.csv # Import CSV
```
CSV format (RFC 4180): `origin,translate,originLang,translateLang`. Header auto-detected. Default: en→zh.
## Global Options
| Option | Default | Description |
|--------|---------|-------------|
| `--config <path>` | — | Config file (YAML/JSON) |
| `--auth-mode` | auto selection | `auto`, `client`, or `oauth` |
| `--timeout <ms>` | `60000` | API timeout |
| `--retry <n>` | `2` | Download retry count |
| `--json` | false | JSON output |
| `--quiet` | false | Errors only |
| `--verbose` | false | Debug output |
| `--no-color` | false | Disable colors (also `NO_COLOR` env) |
## Config File
```bash
doc2x parse ./file.pdf --config ./doc2x.config.yaml
```
Priority: CLI flags > config > built-in defaults. Load `references/config-and-auth.md` for full schema.
## Exit Codes
| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Invalid arguments |
| 2 | Auth/quota/subscription failure |
| 3 | Input file error (missing, too large, unsupported) |
| 4 | Server task failed |
| 5 | Export/download failed |
| 6 | Batch partial failure |
## Troubleshooting
Load `references/troubleshooting.md` for the full list (21 error scenarios with exact messages).
Common issues:
- `command not found` → `npm config get prefix`, add `<prefix>/bin` to PATH
- Install/update failure → retry with `npm i -g @noedgeai-org/doc2x-cli@latest --registry=https://registry.npmjs.org`
- Auth failure (client) → desktop app must be running and logged in
- Auth failure (OAuth) → run `doc2x login` to re-authenticate via browser
- `Unsupported image format` → convert WebP/TIFF to PNG first
- `Model requires subscription` → upgrade at https://doc2x.noedgeai.com/
- `Insufficient quota` → free + subscription pages exhausted
## References
- `references/command-reference.md`: Complete option tables for all commands, supported formats, processing pipelines
- `references/config-and-auth.md`: Authentication details, full config schema, batch behavior, exit codes
- `references/troubleshooting.md`: All error messages with exit codes, validation rules, debugging tips
Files in this package (7)
- SKILL.md 13 KB
- agents/agent.yaml 1 KB
- references/account-and-receipts.md 4 KB
- references/command-reference.md 14 KB
- references/config-and-auth.md 7 KB
- references/troubleshooting.md 8 KB
- references/zotero-workflow.md 3 KB
Versions
The database has no other skills named doc2x-cli.
Database snapshot: 13.11.2026 · package version 7596daf10d96 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100document-processing
This skill should be used when the user says \"process documents\", \"extract text from PDF\", \"OCR this document\", \"convert PDF to markdown\", \"extract emails from documents\", \"parse document\", \"document conversion\", \"batch OCR\", \"extract structured data from PDF\",… - 100pdf-extractor
This skill should be used when the user asks to "extract text from PDF", "convert PDF to text", "parse PDF", "read PDF contents", "extract data from documents", "batch PDF extraction", "PDF to markdown", "OCR PDF", "get text from PDF files", "I have a PDF", "can you read this… - 100pdf-convert
[Document Processing] Use when converting between PDF and Markdown: text PDFs to Markdown (scanned PDFs are reported, not OCR''d), Markdown to styled PDF. --to={markdown|pdf}. - 100pdf-convert
[Document Processing] Use when converting between PDF and Markdown: text PDFs to Markdown (scanned PDFs are reported, not OCR''d), Markdown to styled PDF. --to={markdown|pdf}. - 100pdf-processing-pro
PDF toolkit of uv-runnable scripts for forms, tables, merging, splitting and validation. Use when filling a PDF form from data, reading a form's fields, extracting tables to CSV or Excel, merging or splitting PDFs, checking a PDF is valid, or batch-processing a folder of PDFs… - 100pdf-ocr
Parse PDF files to markdown using GLM-OCR via Ollama locally. Converts each page to an image, runs OCR, and outputs clean markdown. Use when the user wants to extract text from a PDF.