bruce-doc-converter

Bruce Doc Converter

Run the local bdc CLI through a command execution tool. It prints JSON on stdout; progress logs may appear on stderr.

Prepare the CLI (once per session)

Check installation and updates the first time you convert in a session; later conversions reuse the same entry point without checking again.

1. Run bdc --help-json. If the command is missing, look for an existing virtual environment (.venv/bin/bdc, or .venv\Scripts\bdc on Windows) before concluding it is not installed; otherwise install it following Install and update.
2. Read cli_version and install (source, auto_upgrade, upgrade_command). CLIs before 0.2.2 have no install field; identify the installation as described in the reference.
3. When the network is available, find the latest stable release: python -m pip index versions bruce-doc-converter (first line). Compare semantic versions, not strings; never downgrade or choose a pre-release.
4. If a newer release exists:
   • auto_upgrade: true (pipx, uv tool, pip --user): run upgrade_command, re-run bdc --help-json to confirm, and tell the user the old and new versions.
   • venv: this may be a project dependency. Tell the user an update exists and run upgrade_command only after they agree.
   • system or source (a development checkout): tell the user; do not modify it.
   • A version the user or host pinned stays as is; only mention the update.
5. Offline, a failed query, or a host policy that forbids installs: keep using the installed version and say that updates were not checked. Follow the host's install approval and audit rules; do not bypass them to get a newer version.

After an upgrade, the next Markdown to Word conversion may return DEPENDENCY_INSTALL_REQUIRED; run its next_command (bdc setup-node) and retry.

Convert

Office/PDF to Markdown

bdc convert "<file>"
bdc convert "<file>" --content preview      # large files: return a preview, full text is still written
bdc convert "<file>" --extract-images true  # also save embedded images
bdc batch "<directory>"