@noedgeai-org/doc2x-cli

CLI for Doc2X document parsing, translation, and batch workflows.

Install

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

Requires Node >=22.

Commands

doc2x login
doc2x logout
doc2x parse <input>
doc2x translate <input>
doc2x batch <parse|translate> [inputs...]
doc2x term list
doc2x models list

Authentication

Since 0.1.11, commands automatically use credentials saved by doc2x login, or the desktop session when no CLI login is saved. Expired OAuth credentials are refreshed; a failed refresh never switches to a different desktop account.

• --auth-mode auto (default): saved CLI login, otherwise desktop
• --auth-mode client: explicitly reuse an authenticated desktop client session
• --auth-mode oauth: use OAuth credentials from doc2x login

Explicit flags override authMode in --config. doc2x logout clears the CLI login. The browser must reach the computer running doc2x login at a random localhost callback port. --no-browser prints the URL but does not enable device-code login on a remote server.

Examples

doc2x parse ./paper.pdf --to md
doc2x parse ./paper.pdf --to docx --docx-template academic
doc2x translate ./paper.pdf --target-language en --to html
doc2x translate ./paper.pdf --target-model Free
doc2x translate ./paper.pdf --translate-type pdf --pdf-font-strategy page-optimal
doc2x batch parse ./docs --glob "**/*.pdf"

--translate-type pdf preserves the page layout and exports side-by-side bilingual PDF (original left, translation right). Its default output is PDF. In 0.1.11, unsupported --to docx/md/html/tex or --convert-trans origin/translate combinations are rejected before upload rather than silently ignored. Use --to none to skip export. For editable translation-only Word, use --translate-type md --convert-trans translate --to docx; that output is reflowed.

The CLI accepts PDF and PNG/JPG/JPEG/GIF/BMP. Convert Office documents to PDF first. Website-only preserved-layout Word/WPS, MathType, Typst, Excel table exports, and image translation editing are not CLI flags.

Notable Options

• --target-model <model>: Translation LLM model ID/name. Defaults to the shared free aggregate model Free (10001) when the backend advertises it in doc2x models list; pass another listed ID/name to override.
• --docx-template <template>: Word template for V3 docx export. Values: default, general, academic, business, elegant, minimal, technical.
• --pdf-font-strategy <strategy>: PDF font strategy for fixed-layout translation (--translate-type pdf). Values: global-consistent, page-optimal.

Account and retained task records (0.2.0)

doc2x account status --json
doc2x records list --kind translate --limit 20 --json
doc2x records show --parse-id op_example --json
doc2x usage show --translate-id ot_example --json
doc2x models show 10001 --json
doc2x models guide

Account status reports the selected authentication mode, minimal account ID, subscription expiry, shared PDF/image page quota, and available points. Integer ledger values are strings; 100 point units equal one displayed point. Unknown fields are null, never fabricated zero balances. There is no purchase, payment, or account consumption-history command; OAuth permissions are unchanged.

records list --limit counts source documents and includes their parse or translation results without downloading document content. It follows the service's ten-source page limit internally and returns nextCursor; use --cursor to continue. It lists retained results, not a complete failed-task ledger. records show can report an in-progress task even before result metadata exists; expired/unavailable status is unknown.

usage show uses only the existing single-task detail API. Translation tokens/points are reported_by_task when evidence is present. Empty tokens and zero defaults are unconfirmed, because they can also mean the billing lookup was unavailable. Parse consumption is not_provided. Neither output claims final settlement, refunds or fallback-model execution. There is intentionally no usage list.

Model details describe membership eligibility; unknown context limits, price and quality recommendations stay null. models guide explains Free/10001, terminology, sample evaluation and layout choices without switching models.

Durable receipts and batch failures

doc2x translate ./paper.pdf --translate-type pdf --receipt ./paper-run.json --json
doc2x parse ./paper.pdf --to none --receipt ./parse-only.json --json
doc2x batch parse ./docs --to none --report ./batch-report.json --json

Every parse/translate attempt automatically creates <out>/.doc2x-receipts/<attempt-id>.json; --receipt selects a new path for a single task. Existing receipt files are never overwritten by a new attempt. Receipts are updated atomically when task IDs are obtained and stages change. Results keep the previous outputFiles/meta fields and add a versioned receipt with task IDs, stage states, artifact paths and task-reported usage. Failure JSON on stderr also carries the receipt. Receipts do not contain tokens, signed URLs or raw exceptions; they do contain local file paths, so review before sharing.

SIGINT/SIGTERM writes an interrupted checkpoint. Forced termination/power loss can leave the last running checkpoint; it does not prove the remote task stopped. Query the retained task ID before starting another paid task. Final billing metadata is optional: a failed usage query does not turn a successful conversion into a failed one.

--to none means successful processing with export skipped. Existing output files are explicit skips. Batch writes a checkpoint after each completed/failed file and stops scheduling on the first error unless --continue-on-error is set. Reports include unprocessed files as a count. A file that failed before receiving a task ID cannot invent one. Per-file receipts preserve in-flight IDs even before the batch report is updated.

Zotero handoff (no direct library writes)

doc2x zotero manifest --receipt ./paper-run.json --library-id 1 --item-key ABCD1234 --attachment-key EFGH5678 --out ./zotero-import.json --json

Use actual Zotero library/item keys supplied by your Zotero tool. The command verifies exported files, records SHA256/size and metadata, and produces a stable idempotencyKey for an external plugin/MCP/CLI importer. It requires a successful receipt with files; --to none, failed/skipped tasks or missing artifacts are rejected. It never reads Zotero SQLite, writes an attachment, edits notes, or generates an AI summary. Output explicitly says writtenToZotero: false.

Import through a tool that supports your Zotero version and library permissions. Check the parent item, deduplicate by the manifest key, and preserve user-written notes. Markdown/HTML/TeX may reference adjacent resource files; import the full resource bundle or use a converter/importer that handles those references. HTML formulas can depend on a remote MathJax runtime. A manifest validates listed artifacts, not every external link or completeness of an edited receipt. If import fails, retry import without repeating Doc2X processing.