@fiduswriter/cli

Command-line tool for converting documents between Fidus Writer native format (.fidus) and other document formats. Built on top of @fiduswriter/document.

Install

npm install -g @fiduswriter/cli

See INSTALL.md for platform-specific packages (Debian, Arch, Fedora, macOS Homebrew) and building from source.

Update

If you installed the package globally with npm, update it to the latest version with:

npm install -g @fiduswriter/cli@latest

Usage

Convert documents

The convert command is the default and handles all format conversions:

# .fidus → DOCX
fidusconvert document.fidus output.docx

# DOCX → .fidus
fidusconvert input.docx output.fidus

# DOCX → LaTeX (explicit format flags)
fidusconvert --from docx --to latex input.docx output.latex.zip

# .fidus → HTML with a custom citation style
fidusconvert -s chicago-author-date document.fidus output.html.zip

# .fidus → DOCX with a custom template
fidusconvert --docx-template my-template.docx document.fidus output.docx

# .fidus → JATS with book-part-wrapper type
fidusconvert --jats-type book-part-wrapper document.fidus output.jats.zip

Pipe through stdin/stdout

Use - as the input or output path to read from stdin or write to stdout. When - is used, the format must be given explicitly with --from or --to.

# Markdown → Pandoc JSON → Fidus Writer
pandoc -f markdown -t json input.md | fidusconvert --from pandoc --to fidus - output.fidus

# Fidus Writer → raw Pandoc JSON → Markdown
fidusconvert --from fidus --to pandoc input.fidus - | pandoc -f json -t markdown

# .fidus → DOCX on stdout (binary, redirect to a file)
fidusconvert --from fidus --to docx input.fidus - > output.docx

Status messages are written to stderr so they do not mix with piped output.

When exporting to --to pandoc -, the raw Pandoc JSON document is emitted on stdout (not the usual .pandoc.json.zip archive). For all other formats the binary archive is written directly to stdout.

Inspect a .fidus file

fidusconvert info document.fidus

This prints the file's MIME type, format version, document title, language, paper size, citation style, image and bibliography counts, and a listing of all files inside the .fidus archive.

Options

Option	Description
--from <format>	Input format (auto-detected from extension if omitted)
--to <format>	Output format (auto-detected from extension if omitted)
-s, --style <style>	Citation style: apa, chicago-author-date, ieee, etc. (default: apa)
--docx-template <path>	Custom DOCX template file
--odt-template <path>	Custom ODT template file
--jats-type <type>	JATS type: article, book-part-wrapper, book (default: article)
--math-output <mathml|svg>	Math output for HTML/EPUB export: mathml (default) or svg
--tracked-changes <resolve|include>	Tracked changes for HTML/EPUB/DOCX/ODT export: resolve (accept all, default) or include them. Formats that cannot represent tracked changes (LaTeX, JATS, Pandoc) always resolve them.

Supported formats

Format	Read	Write	Extension
Fidus Writer	yes	yes	.fidus
DOCX	yes	yes	.docx
ODT	yes	yes	.odt
LaTeX		yes	.latex.zip
HTML		yes	.html.zip
EPUB		yes	.epub
JATS		yes	.jats.zip
Pandoc JSON	yes	yes	.json / .pandoc.json.zip

Dependencies

• @fiduswriter/document — document schema, importers and exporters
• fwtoolkit — shared utilities

Development

npm install
npm run build

Tests

The full test suite uses Pandoc to generate DOCX, ODT and Pandoc-JSON fixtures from Markdown sources and to cross-check exported files. Make sure Pandoc is installed before running the tests:

# Debian/Ubuntu
sudo apt-get install pandoc

# macOS
brew install pandoc

Run all tests:

npm test

If Pandoc is unavailable, the core CLI tests in test/convert.test.ts can be run directly:

npx tsx test/convert.test.ts

The test suite covers:

• All supported export formats from .fidus files.
• Import of DOCX, ODT and Pandoc JSON files into .fidus.
• A full conversion matrix (Markdown → DOCX/ODT/JSON → .fidus → every output format) with content checks.
• Pre-existing DOCX and ODT fixtures, including files with tracked changes, comments, footnotes and citation-manager fields.
• Synthetic DOCX files built from citation-manager word/document.xml fragments (Zotero, Mendeley, EndNote and Word-native bibliographies), with Word-native sources bundled as customXml/item1.xml.
• Synthetic ODT files built from citation-manager content.xml fragments (Zotero reference marks and LibreOffice native bibliography marks).

License

AGPL-3.0-or-later