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.

Installation#

First, check if bdc is already available:

bash

command -v bdc        # macOS / Linux
where bdc             # Windows

If not installed, try the following in order — stop at the first that succeeds:

bash

# 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)
pip install --user bruce-doc-converter   # or: python3 -m pip install --user bruce-doc-converter

# 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:

bash

bdc convert "<file>"

For batch conversion:

bash

bdc batch "<directory>"

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

bash

bdc setup-node

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".

Troubleshooting installation#

ErrorCauseFixSOCKS support / proxy connection errorall_proxy or http_proxy env vars setRun unset all_proxy http_proxy https_proxy (macOS/Linux) or set all_proxy= (Windows CMD), then retrycommand not found: pipxpipx not installedTry uv tool install or pip install --user insteadexternally-managed-environmentPython 3.11+ system Python forbids global pipUse pipx, uv tool install, or the venv fallbackPermission deniedNo write access to install locationAdd --user flag, or use venv fallbackbdc: command not found after venv installvenv bin not in PATHUse full path: .venv/bin/bdc (macOS/Linux) or .venv\Scripts\bdc (Windows)

Supported formats#

InputOutput.docxMarkdown.xlsxMarkdown.pptxMarkdown.pdfMarkdown.mdWord .docx