Doc2X CLI User Guide

doc2x-cli is a command-line tool provided by Doc2X for parsing and converting PDF or image files into Markdown, Word, LaTeX, HTML, or PDF formats, with support for multi-language document translation and batch processing.

Command Overview

Command	Description
`doc2x login`	Log in to Doc2X via browser (OAuth)
`doc2x logout`	Clear stored OAuth credentials
`doc2x parse <input>`	Parse PDF or image and export to a structured document format
`doc2x translate <input>`	Parse and translate a PDF file
`doc2x batch <action> [inputs...]`	Batch `parse` or `translate` for multiple files or directories
`doc2x models list`	List translation models available for your account
`doc2x term list`	List glossaries and their IDs configured for your account

Requirements & Installation

Runtime: Node.js 22 or higher
Network: Access to Doc2X services is required
File limits: PDF up to 300 MiB, images up to 3 MiB
Supported image formats: png, jpg, jpeg, gif, bmp (webp, tiff, and tif are not supported)

Prerequisites

Checked against public npm package @noedgeai-org/doc2x-cli@0.2.0 on 2026-10-05. The older @noedgeai GitHub Packages installation is not this guide's entry point; no GitHub registry setup is needed for the new @noedgeai-org package. After upgrading, check doc2x --version and command-specific --help before running tasks.

Installation

Install the package globally via npm:

bash

npm i -g @noedgeai-org/doc2x-cli@0.2.0

# Verify installation
doc2x --version

Tip: If you get command not found: doc2x after installation, make sure npm's global bin directory is in your system PATH.

Authentication

Default --auth-mode auto prefers the saved CLI login, otherwise the desktop session. Explicit flags override configuration; a failed OAuth refresh does not switch to another desktop account. The CLI uses a personal account, not an Open Platform API Key.

Explicit Client Mode

Reads the login state from the locally running Doc2X desktop client. Best suited for personal development machines. Simply ensure the desktop client is logged in and running:

bash

doc2x parse ./paper.pdf --auth-mode client

OAuth Mode

Browser-based OAuth does not require the desktop client. The browser must reach a random localhost callback port on the computer running the CLI. --no-browser prints the URL; it is not a remote device-code login. Do not copy tokens into untrusted environments.

bash

# Log in (opens browser for OAuth authorization)
doc2x login

# After login, run commands with OAuth mode
doc2x --auth-mode oauth parse ./paper.pdf

# If you cannot open a browser, use --no-browser to get the URL manually
doc2x login --no-browser

# Log out (clear credentials)
doc2x logout

OAuth credentials are stored in the system application data directory (macOS: ~/Library/Application Support/doc2x/, Linux: ~/.config/doc2x/, Windows: %APPDATA%\doc2x\) and tokens are refreshed automatically.

Global Options

The following options apply to all commands:

Option	Description	Default
`--config <path>`	Path to config file (YAML/JSON)	-
`--auth-mode <mode>`	Authentication mode: `auto`, `client`, or `oauth`	`auto`
`--timeout <ms>`	API request timeout in milliseconds	`60000`
`--retry <n>`	Retry count for downloads/exports	`2`
`--json`	Output results as JSON	`false`
`--quiet`	Only output errors and final results	`false`
`--verbose`	Output debug information	`false`
`--no-color`	Disable colored output (auto-detected in non-TTY)	Auto

Quick Start

Four most common scenarios:

bash

# 1. Parse a PDF and export as Markdown (default)
doc2x parse ./paper.pdf

# 2. Parse a PDF and export as Word
doc2x parse ./paper.pdf --to docx

# 3. Translate a PDF to Chinese and export as Word
doc2x translate ./paper.pdf --target-language zh --to docx

# 4. Batch parse all PDFs in a directory to Markdown
doc2x batch parse ./docs --glob "**/*.pdf"

By default, output files are saved in the output folder under the current directory.

Document Parsing (parse)

The parse command processes PDF and image files. Use the --to flag to specify the output format: md (default), docx, tex, html, pdf, none (parse only, no export).

bash

doc2x parse ./paper.pdf --to tex
doc2x parse ./image.png

Parse Options

Option	Description	Default
`--to <fmt>`	Output format: `none`, `md`, `tex`, `docx`, `html`, `pdf`	`md`
`--image-models <models...>`	Image OCR models (`doc2x` is mandatory): `doc2x` `mathpix`	`doc2x`
`--vision-models <models...>`	LLM vision models for image parsing (use IDs from `doc2x models list`)	-
`--image-hosting <mode>`	Image source: `local` or `online`	`local`
`--formula-mode <mode>`	Formula delimiter: `normal` or `dollar`	`normal`
`--formula-level <level>`	Formula downgrade level: `normal`, `onlyLine`, `processAll`	`normal`
`--merge-cross-page-forms`	Attempt to merge tables that span across pages	`false`
`--remove-comments`	Remove HTML comments from output	`false`
`--avoid-indented-code-blocks`	Code indentation compatibility	`false`
`--out <path>`	Output directory or file path	`./output`
`--name <pattern>`	Filename template: `{basename}`, `{date}`, `{lang}`	`{basename}`
`--overwrite`	Overwrite existing output files	`false`

Note on formula dollar mode: --formula-mode dollar is only effective when exporting to Markdown. It has no effect with other export formats.
Note on HTML export: HTML output relies on MathJax CDN for formula rendering. For fully offline use, consider exporting to docx or pdf instead.
Note on online image hosting: When using --image-hosting online, images are only stored for 30 days.

Document Translation (translate)

The translate command accepts PDFs. Target language defaults to zh; specify --target-language explicitly to avoid an unintended default or configuration value.

Supported Target Languages

zh (Chinese), en (English), ja (Japanese), fr (French), ru (Russian), pt (Portuguese), pt-BR (Brazilian Portuguese), es (Spanish), de (German), ko (Korean), ar (Arabic)

Translation Modes

Two modes are available, controlled by --translate-type:

Document translation (default: md): Extracts and translates content, then exports to Markdown, Word, HTML, etc. Supports bilingual output.
Fixed-layout translation (pdf): Exports a bilingual PDF with original on the left and translation on the right, preserving each page layout. PDF is the default output; there are no translation-only, reversed-order, or above/below CLI switches.

bash

# Document translation: translate to Chinese, export as Word
doc2x translate ./paper.pdf --target-language zh --to docx

# Fixed-layout translation: translate to Chinese, export as layout-preserved PDF
doc2x translate ./paper.pdf --target-language zh --translate-type pdf

Translate Options

The following options are specific to the translate command (all parse options are also inherited):

Option	Description	Default
`--translate-type <t>`	Translation mode: `md` or `pdf`	`md`
`--target-language <lang>`	Target language code	`zh`
`--target-model <model>`	ID/name from the service model list	`Free` (`10001`) when available
`--term-id "YOUR_TERM_ID"`	Glossary ID (get IDs via `doc2x term list`)	-
`--font-color-extraction`	Extract font color	`false`
`--ignore-translate-types <list...>`	Element types to skip: `table`, `code`, `figure`, `reference`	-
`--convert-trans <t>`	Reflowed output only; fixed-layout PDF requires `both`. Content: `both` (bilingual), `origin` (original only), `translate` (translated only)	`both`
`--contextual-translation`	Enable contextual translation enhancement	`false`

Batch Processing (batch)

The batch command processes multiple files or entire directories at once, and automatically generates a processing report.

bash

# Batch parse specific files in a directory
doc2x batch parse ./docs --glob "**/*.pdf" --to docx

# Batch translate, continue on errors
doc2x batch translate ./papers --glob "**/*.pdf" --target-language zh --continue-on-error

Batch Options

Option	Description	Default
`--glob <pattern>`	Glob pattern for directory inputs	`*/.{pdf,png,jpg,jpeg}`
`--continue-on-error`	Continue when a file fails	`false`
`--skip-existing`	Skip files with existing output	`true`
`--report <path>`	Report output path	`./doc2x-report.json`
`--dry-run`	Print the list of files to be processed without executing	`false`

The batch command also supports all parse and translate options.

Model Query (models)

List available translation models for your account, including model IDs, names, and subscription requirements. Use the model ID from this list for the --target-model option in the translate command.

bash

doc2x models list

# JSON format output
doc2x models list --json

Glossary Management (term)

Glossaries help unify terminology translation across documents.

Term Subcommands

Subcommand	Description	Required Options
`doc2x term list`	List all glossaries	-
`doc2x term create`	Create a new glossary	`--name <name>`
`doc2x term items`	List items in a glossary	`--term-id "YOUR_TERM_ID"`
`doc2x term import`	Import terms from a CSV file	`--term-id "YOUR_TERM_ID" --file <path>`

bash

# List all glossaries
doc2x term list

# Create a glossary
doc2x term create --name "Technical Dictionary"

# List items in a glossary
doc2x term items --term-id "YOUR_TERM_ID"

# Import terms from a CSV file
doc2x term import --term-id "YOUR_TERM_ID" --file terms.csv

CSV Import Format

The CSV file supports the following columns (RFC 4180 compliant):

Column	Description	Default
`origin`	Source term	(required)
`translate`	Translated term	(required)
`originLang`	Source language code	`en`
`translateLang`	Target language code	`zh`

Supported language codes: zh, en, ja, fr, ru, pt, pt-BR, es, de, ko, ar.

Example CSV file:

text

origin,translate,originLang,translateLang
machine learning,机器学习,en,zh
neural network,神经网络,en,zh

Configuration & Output Settings

Output Control

Use --out to specify the output directory and --name to configure the filename template. Supported placeholders: {basename}, {date}, {lang}.

bash

# Specify output directory and filename with language suffix
doc2x translate ./paper.pdf --target-language zh --out ./results --name "{basename}_{lang}" --to docx

Configuration File

For frequently used parameter combinations, create a YAML or JSON configuration file and load it with --config.

Configuration priority (highest to lowest): CLI arguments > config file > built-in defaults.

yaml

# doc2x.yaml
authMode: auto
timeout: 60000
retry: 2
defaults:
  parse:
    to: docx
    imageModels: ["doc2x"]
    visionModels: []
    imageHosting: local
    formulaMode: normal
    formulaLevel: normal
    mergeCrossPageForms: false
    removeComments: false
    avoidIndentedCodeBlocks: false
    out: ./output
    name: "{basename}"
    overwrite: false
  translate:
    translateType: md
    targetLanguage: zh
    targetModel: "10001"
    termId: ""
    fontColorExtraction: false
    ignoreTranslateTypes: []
    convertTrans: both
    contextualTranslation: false
  batch:
    glob: "**/*.{pdf,png,jpg,jpeg}"
    continueOnError: false
    skipExisting: true
    report: ./doc2x-report.json
    dryRun: false

bash

doc2x --config ./doc2x.yaml parse ./paper.pdf

JSON Output

Use the --json flag to format command output as JSON, useful for scripting and automation:

bash

doc2x parse ./paper.pdf --json
doc2x batch parse ./docs --json

Exit Codes

Exit Code	Meaning
`0`	Success
`1`	Argument error
`2`	Authentication failed
`3`	Input file error
`4`	Task processing failed
`5`	Export failed
`6`	Batch partial failure

Troubleshooting

Issue / Error	Suggested Fix
`Cannot connect to desktop client`	Confirm the desktop client is running and logged in. On servers or headless environments, use `doc2x login` and switch to `--auth-mode oauth`
OAuth login failed	Ensure network access to Doc2X services, try `doc2x login --no-browser` to manually copy the URL
Output file not generated or unchanged	The CLI does not overwrite existing files by default. Add `--overwrite` to force update
Image upload rejected or failed	Check image format and size. Max 3 MiB per image; webp, tiff, and tif are not supported — convert to png or jpg
Insufficient quota / model requires subscription	Check your account quota and subscription status. Some features (e.g., `mathpix` model) may require a premium account

Check the account, then process one sample

bash

doc2x --version
doc2x login
doc2x account status --json
doc2x models list --json

Confirm the selected identity, subscription, shared parsing pages, and points. null is unknown, not zero balance. Raw points use 100 ledger units per displayed point; they are not cash. A snapshot does not reserve quota for a batch. Website login, Open Platform keys, and CLI OAuth are separate credentials.

bash

doc2x parse ./paper.pdf --to md --out ./output --receipt ./paper-run.json --json

This creates a real task. Inspect outputFiles, meta, and receipt, then open the actual files. A completion message alone is insufficient. Preserve adjacent image resources when moving MD/TEX/HTML; HTML formulas may require the MathJax network runtime.

Word templates and translation outputs

bash

# V3 reflowed Word template
doc2x parse ./paper.pdf --to docx --docx-template academic --out ./word-output

# Editable, translation-only Word with reflowed layout
doc2x translate ./paper.pdf --translate-type md --convert-trans translate --target-language en --to docx --docx-template technical --out ./translated-word

# Fixed-layout bilingual PDF: original left, translation right
doc2x translate ./paper.pdf --translate-type pdf --target-language en --pdf-font-strategy page-optimal --out ./bilingual-pdf

--docx-template accepts default/general/academic/business/elegant/minimal/technical for V3 Word export only. --pdf-font-strategy accepts global-consistent (default) or page-optimal for fixed-layout translation. Fixed-layout PDF rejects --to docx/md/tex/html and --convert-trans origin/translate before upload; --to none processes without export.

Ordinary parsing with --to pdf produces re-typeset PDF, not a scanned-page text layer. Website preserved-layout Word/WPS, MathType, Typst, Excel, Eduediter, and image-translation editing are not current CLI flags. Convert Office files to PDF separately; changing the suffix is not conversion.

Batch preview, receipts, and failure follow-up

bash

# List matching files without submitting parsing
doc2x batch parse ./docs --glob "**/*.pdf" --dry-run --json

# Run only after reviewing the list; files are processed sequentially
doc2x batch parse ./docs --glob "**/*.pdf" --to md --out ./batch-output --report ./batch-report.json --json

Batch work is sequential and stops scheduling after the first failure unless --continue-on-error is explicit. Reports count unprocessed files separately; they are neither failures nor successes. Existing outputs may be skipped. Check paths/backups before overwriting.

Each file attempt saves a receipt under the output directory's .doc2x-receipts/; --receipt chooses a fresh single-task file and does not overwrite a previous receipt. taskIds, stages, status, outputFiles, and artifacts describe separate stages. --to none is successful processing with skipped export. Ctrl+C or power loss does not guarantee remote cancellation.

Replace these placeholder IDs with real IDs from your receipt:

bash

doc2x records show --parse-id op_example --json
doc2x records show --translate-id ot_example --json
doc2x records list --kind translate --limit 20 --json
doc2x usage show --translate-id ot_example --json

records list --limit counts source documents; continue with --cursor when nextCursor is returned. It is not an exhaustive failed-task ledger; unknown does not mean failed. usage show reads task-reported usage only. reported_by_task does not establish settlement/refunds; empty zero defaults can be unconfirmed, and parse usage is not_provided. There is no usage list consumption history or general resume/re-export command. Do not invent flags or repeat paid processing just to recover an output.

Receipts exclude tokens/signed URLs but contain local paths and task metadata; review before sharing. Success JSON goes to stdout; failure JSON can be on stderr with a nonzero exit code.

Model details and external Zotero import

bash

doc2x models show 10001 --json
doc2x models guide
doc2x zotero manifest --receipt ./paper-run.json --library-id 1 --item-key ABCD1234 --out ./zotero-import.json --json

Models come from the current service list. Subscription eligibility is not a full price quote; unknown context lengths/prices remain null. --vision-models takes available IDs/names, but the existence of a translation model does not guarantee image-enhancement quality. Check flags/permissions before choosing.

Use real library/item keys from your Zotero tool. The manifest command requires a successful receipt with files, verifies size/hash, and creates import metadata. It does not write to Zotero; output states writtenToZotero: false. Use a compatible external plugin/MCP importer, check the parent item, deduplicate, and preserve user notes and resource files. Retry an import failure without repeating Doc2X processing.

Doc2X Client

One-Click Save Guide

Doc2X MCP Guide

Doc2X CLI User Guide

Command Overview

Requirements & Installation

Prerequisites

Installation

Authentication

Explicit Client Mode

OAuth Mode

Global Options

Quick Start

Document Parsing (parse)

Parse Options

Document Translation (translate)

Supported Target Languages

Translation Modes

Translate Options

Batch Processing (batch)

Batch Options

Model Query (models)

Glossary Management (term)

Term Subcommands

CSV Import Format

Configuration & Output Settings

Output Control

Configuration File

JSON Output

Exit Codes

Troubleshooting

Check the account, then process one sample

Word templates and translation outputs

Batch preview, receipts, and failure follow-up

Model details and external Zotero import

Version sources