Bruce Doc Converter

Bruce Doc Converter

Agent-facing document converter CLI..

When to use

Use this skill when the user asks to:

• Convert .docx, .xlsx, .pptx, .pdf, or .md files.
• Read, summarize, inspect, or analyze Office/PDF documents.
• Export Markdown as Word.
• Process uploaded document files whose content the agent cannot directly read.

Setup and version check

Run this first — it checks installation status and current version in one step:

bashCopy code
bdc --help-json

• Command not found → not installed. Install using one of the methods below, then re-run.
• Returns JSON with cli_version → installed. Compare against the latest on PyPI:

  bashCopy code
  pip index versions bruce-doc-converter 2>/dev/null | head -1
  

  If the versions differ, upgrade (see Upgrade section), then re-run bdc setup-node if Markdown to Word was previously set up.

Install (if not already installed)

Try the following in order — stop at the first that succeeds:

bashCopy code
# 1. pipx (preferred — isolated, bdc lands in PATH)
pipx install bruce-doc-converter

# 2. uv (if available — fast, isolated, bdc lands in PATH)
uv tool install bruce-doc-converter

# 3. pip --user (most universally available, bdc lands in PATH)
pip3 install --user bruce-doc-converter  # macOS/Linux
pip install --user bruce-doc-converter   # Windows
# or universally: python3 -m pip install --user bruce-doc-converter (use `python` on Windows)

# 4. venv fallback (works everywhere, but bdc will NOT be in PATH)
python3 -m venv .venv
.venv/bin/pip install bruce-doc-converter
# Windows: .venv\Scripts\pip install bruce-doc-converter

venv note: If you used the venv fallback, replace every bdc command below with .venv/bin/bdc (macOS/Linux) or .venv\Scripts\bdc (Windows).

Windows note: Use python instead of python3 if the former is not recognized.

Command

Run:

bashCopy code
bdc convert "<file>"

For Markdown files with Mermaid diagrams, PNG rendering defaults to scale 4. Increase or decrease it when needed:

bashCopy code
bdc convert "<file.md>" --mermaid-scale 5

For batch conversion:

bashCopy code
bdc batch "<directory>"
bdc batch "<directory>" --mermaid-scale 5

For Markdown to Word, initialize the Node.js dependencies explicitly before first use:

bashCopy code
bdc setup-node

If the Markdown contains Mermaid diagrams (```mermaid blocks), they will be automatically rendered as PNG images embedded in the Word document. The CLI automatically detects and uses the user's local Chrome / Edge / Chromium during conversion, launching it headlessly with a temporary browser profile, so do not install a bundled browser unless local browser detection fails.

If no local browser is available, explicitly install Puppeteer's dedicated browser:

bashCopy code
bdc setup-node --install-browser

If your environment specifically requires npm lifecycle scripts, run:

bashCopy code
bdc setup-node --allow-scripts --install-browser

Linux note: Mermaid rendering is disabled by default on Linux sandboxed environments. Set BRUCE_DOC_CONVERTER_ALLOW_CHROMIUM_NO_SANDBOX=1 if your environment requires it and you understand the risk.

The CLI prints JSON to stdout by default. Progress logs may appear on stderr.

Output handling

Parse stdout as JSON.

On success:

• success is true.
• output_path points to the generated file.
• Office/PDF inputs include markdown_content for direct analysis.
• .md inputs produce a .docx file and may omit markdown_content.

On failure:

• success is false.
• Use error_code, retryable, optional next_command, error, and optional suggestion to decide the next step.
• Do not pre-check Python dependencies. Run the command first and react to JSON failure.
• If Markdown to Word returns DEPENDENCY_INSTALL_REQUIRED, run next_command when present, otherwise run bdc setup-node, then retry.
• bdc setup-node is idempotent and may return already_installed: true with install_action: "skipped".

Upgrade

To upgrade to the latest version, use the same tool you used to install:

bashCopy code
pipx upgrade bruce-doc-converter          # if installed via pipx
uv tool upgrade bruce-doc-converter       # if installed via uv
pip install --user --upgrade bruce-doc-converter   # if installed via pip --user
.venv/bin/pip install --upgrade bruce-doc-converter  # if installed in a venv (macOS/Linux)
.venv\Scripts\pip install --upgrade bruce-doc-converter  # venv on Windows

After upgrading, re-run bdc setup-node if you use Markdown to Word conversion, as Node.js dependencies may also have been updated.

Troubleshooting installation

Supported formats