docmd-cli 0.1.0__tar.gz

docmd_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install weasyprint system dependencies
+        # DOCX/PPTX conversion goes through weasyprint, which needs native
+        # Pango/GObject/Cairo libraries that pip cannot provide.
+        run: sudo apt-get update && sudo apt-get install -y libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info
+      - name: Install docmd
+        run: pip install -e ".[full,dev]"
+      - name: Run tests
+        run: pytest -v

docmd_cli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for PyPI trusted publishing (OIDC) - no token stored
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

docmd_cli-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.venv/
+.env
+.DS_Store
+*.log

docmd_cli-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,149 @@
+# Architecture: Doc-to-Markdown API
+
+## The pitch (keep this pinned above your desk)
+We are not competing on conversion quality. We are selling **"hit an endpoint, get clean Markdown back"** — no Python env, no 8GB+ RAM, no GPU, no dependency hell. The open-source core proves the engine works and builds trust. The hosted API sells convenience.
+
+## Positioning risk (checked 2026-09-18)
+Marker's *code* is Apache-2.0 (no restriction). Marker's *model weights* use a modified
+Open RAIL-M license: free for research, personal use, and organizations under $5M in
+funding/revenue; beyond that, a commercial license from Datalab is required. This is not
+a launch blocker for a bootstrapped start, but it is a real ceiling to plan around if the
+hosted API grows past that threshold. Separately, Datalab already runs its own hosted
+"upload a file, get Markdown back" API (datalab.to/pricing) with a free tier and
+pay-as-you-go pricing — so "convenience" alone is not a durable moat, since Datalab
+already sells that. The real differentiator has to be the post-processing quality (see
+below), not just "no setup required." Every feature that's free elsewhere (e.g. OCR,
+which Marker already bundles) should stay free in `docmd` too; gating something users
+can trivially get by calling Marker directly doesn't protect revenue, it just damages
+trust.
+
+---
+
+## System overview
+
+```
+                        +---------------------------+
+                        |   docmd (OSS library)      |  <- pip install docmd-cli
+                        |   Python CLI + library     |  <- free, MIT license
+                        |   wraps Marker under       |
+                        |   the hood                 |
+                        +--------------+--------------+
+                                       | same core logic,
+                                       | imported not duplicated
+                                       v
++--------------+    +---------------------------+    +-----------------+
+|   Client      |--->|   API Gateway (FastAPI)   |--->|  Inference       |
+|  (curl, SDK,  |    |   - auth (API keys)       |    |  Worker (GPU)    |
+|   your docs)  |    |   - rate limiting         |    |  Modal / RunPod  |
++--------------+    |   - usage metering         |    |  runs Marker     |
+       ^             |   - job queue              |    +--------+---------+
+       |             +--------------+--------------+             |
+       |                            |                             |
+       |                            v                             |
+       |             +---------------------------+                |
+       |             |  Postgres (Supabase)       |                |
+       |             |  - users, api_keys         |<---------------+
+       |             |  - usage_events            |   writes result +
+       |             |  - jobs (status/result)    |   usage back
+       |             +---------------------------+
+       |                            ^
+       |                            |
+       |             +---------------------------+
+       +------------>|  Stripe (billing)          |
+      webhook events  |  - subscriptions            |
+                       |  - usage-based invoicing   |
+                       +---------------------------+
+```
+
+**Key architectural decision: the OSS library and the hosted API share the same core conversion code.** Put the actual conversion logic (file -> Markdown) in the open-source package. The API is a thin, closed-source wrapper around it that adds auth, billing, queuing, and GPU orchestration. This way:
+- The OSS repo is genuinely useful standalone (real trust, real stars)
+- You never duplicate logic between "free" and "paid"
+- Improvements to the core benefit both
+
+---
+
+## Repo structure
+
+This repo currently contains **Stage 1 only**: the `docmd/` OSS package. The `api/`
+folder (hosted API) is a later stage, described below for context but not yet built.
+
+```
+docmd/
+|-- README.md
+|-- ARCHITECTURE.md
+|-- LICENSE                       # MIT for the core package
+|-- pyproject.toml                # package config for `docmd` on PyPI
+|-- docmd/                        # --- OSS PACKAGE (public, pip-installable) ---
+|   |-- __init__.py
+|   |-- cli.py                    # `docmd convert file.pdf` entrypoint
+|   |-- converters/
+|   |   |-- __init__.py
+|   |   |-- base.py               # Converter protocol/interface
+|   |   |-- marker_converter.py   # wraps datalab-to/marker
+|   |   `-- registry.py           # maps file type -> converter
+|   |-- postprocess/              # THIS is where docmd earns its existence
+|   |   |-- table_cleanup.py      # fix mangled table structure from raw Marker output
+|   |   |-- heading_normalize.py  # consistent heading levels, no orphaned headers
+|   |   `-- image_handling.py     # consistent alt-text / placeholder convention
+|   |-- config.py
+|   `-- errors.py                 # error taxonomy
+|-- tests/
+|   |-- test_cli.py
+|   |-- test_converters.py
+|   |-- test_postprocess.py
+|   `-- fixtures/                 # sample pdf/docx test files (generated)
+`-- .github/
+    `-- workflows/
+        `-- ci.yml                 # tests on PR
+
+# Not yet built (later stage):
+# api/            - FastAPI hosted service (auth, billing, queue, GPU worker)
+```
+
+### Post-processing: the actual product
+Raw Marker output is good but not perfect for RAG use — this is where `docmd` needs to add real value instead of being pure plumbing:
+- **Table cleanup**: fix structure that comes out mangled from complex layouts
+- **Heading normalization**: consistent heading levels, no orphaned/duplicate headers
+- **Image handling**: a consistent convention for alt-text or placeholders (RAG pipelines need to know what to do with images, even if just "skip")
+- **Optional LLM polish pass** (v2, opt-in, costs extra): run a cheap LLM call over the output to fix remaining formatting oddities — this is a legitimate premium feature since it has a real marginal cost
+
+Treat this folder as the actual differentiator. A thin wrapper is a weekend project; good post-processing is a product.
+
+---
+
+## Tech stack (with reasoning)
+
+| Layer | Choice | Why |
+|---|---|---|
+| OSS core | Python, wraps `marker-pdf` (pinned `==2.0.0`) | Don't reinvent conversion; Marker has ~40k combined stars (with Surya) and active maintenance |
+| API framework (later stage) | FastAPI | Async-friendly, great for I/O-bound job queuing, auto-generates OpenAPI docs |
+| GPU inference (later stage) | Modal (first choice) or RunPod | Modal has better Python DX and publishes an official Marker deployment guide; RunPod is often cheaper at scale |
+| Database (later stage) | Postgres via Supabase | Free tier is generous, easy to self-host later |
+| Billing (later stage) | Stripe, prepaid credits by default | Avoids surprise invoices |
+| API deploy (later stage) | Railway or Fly.io | Simple deploys, no k8s complexity |
+
+---
+
+## Packaging: optional dependencies
+
+- `pip install docmd-cli` -> core PDF conversion (Marker bundles OCR here already; there is
+  no separate lean/no-OCR base install, since Marker's own base dependencies include
+  `surya-ocr`)
+- `pip install docmd-cli[full]` -> adds DOCX/PPTX/EPUB/XLSX support via Marker's `full` extra
+
+## License clarity
+
+MIT for the `docmd` wrapper is fine and expected for an OSS trust play. Marker's code is
+Apache-2.0. Marker's *model weights* are under a modified Open RAIL-M license: free for
+research, personal use, and organizations under $5M funding/revenue; beyond that, a paid
+license from Datalab is required (see datalab.to/pricing). Re-check this before scaling
+the hosted API past that threshold.
+
+## What "done" looks like for Stage 1 (this repo, today)
+
+- [x] `docmd` installable via `pip install -e .` locally
+- [x] Converts a PDF to Markdown from the CLI in one command
+- [x] Post-processing (table cleanup, heading normalization) visibly improves on raw Marker output
+- [x] README has a compelling before/after example and a 30-second quickstart
+- [ ] Published to PyPI
+- [ ] Hosted API (later stage, not built yet)

docmd_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 taherzribi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docmd_cli-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: docmd-cli
+Version: 0.1.0
+Summary: Convert PDFs, DOCX, and PPTX to clean, structure-preserving Markdown.
+Project-URL: Homepage, https://github.com/taherzribi/docmd
+Project-URL: Issues, https://github.com/taherzribi/docmd/issues
+Author: taherzribi
+License: MIT
+License-File: LICENSE
+Keywords: document-conversion,docx,markdown,pdf,pptx,rag
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: <4,>=3.10
+Requires-Dist: click<9,>=8.2.0
+Requires-Dist: marker-pdf==2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: python-docx>=1.1.0; extra == 'dev'
+Requires-Dist: reportlab>=4.0.0; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: marker-pdf[full]==2.0.0; extra == 'full'
+Description-Content-Type: text/markdown
+
+# docmd
+
+**Convert PDFs, DOCX, and PPTX to clean, structure-preserving Markdown — from the CLI or a Python library.**
+
+Built for feeding documents into LLM and RAG pipelines, where clean Markdown beats raw text extraction.
+
+*(Published on PyPI as `docmd-cli` since `docmd` was already taken by an unrelated
+package — the import (`import docmd`) and CLI command (`docmd convert ...`) are
+unaffected.)*
+
+```bash
+pip install docmd-cli
+docmd convert report.pdf
+```
+
+```python
+from docmd import convert
+
+markdown = convert("report.pdf")
+print(markdown)
+```
+
+## Why docmd
+
+Great open-source document-to-Markdown converters already exist (docmd is built on
+[Marker](https://github.com/datalab-to/marker)). The problem isn't quality — it's that
+running them yourself means a Python environment, several GB of RAM, ideally a GPU, and
+a non-trivial setup process before you convert your first file.
+
+`docmd` wraps that engine with sane defaults and adds real post-processing on top
+(table cleanup, heading normalization) so the output is closer to what a RAG pipeline
+actually wants, not just raw model output.
+
+A hosted API (`POST` a file, get Markdown back, no local setup) is planned — see
+[ARCHITECTURE.md](ARCHITECTURE.md). It is not live yet; this repo is the open-source
+core, usable standalone today.
+
+## What it handles
+
+| Input | Output |
+|---|---|
+| PDF (text-based) | Markdown with preserved headings, lists, tables |
+| PDF (scanned) | Markdown via OCR — bundled by Marker, free |
+| DOCX | Markdown with formatting preserved (`pip install docmd-cli[full]`) |
+| PPTX | Markdown, one section per slide (`pip install docmd-cli[full]`) |
+
+## Quickstart
+
+**CLI**
+```bash
+pip install docmd-cli
+docmd convert my-file.pdf -o output.md
+```
+
+**Python**
+```python
+from docmd import convert
+
+# From a file path
+markdown = convert("my-file.pdf")
+
+# From bytes
+with open("my-file.pdf", "rb") as f:
+    markdown = convert(f.read(), filename="my-file.pdf")
+```
+
+## Installing DOCX/PPTX support
+
+The base install (`pip install docmd-cli`) covers PDF only and stays lean. DOCX and
+PPTX need Marker's own additional dependencies:
+
+```bash
+pip install "docmd-cli[full]"
+```
+
+DOCX/PPTX conversion also needs [weasyprint](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#installation)'s
+native Pango/GObject/Cairo libraries, which `pip` cannot install for you:
+
+```bash
+# macOS
+brew install pango
+
+# Debian/Ubuntu
+sudo apt-get install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info
+```
+
+PDF conversion (the base install) does not need this.
+
+## How it works
+
+`docmd` wraps [Marker](https://github.com/datalab-to/marker) with sane defaults and a
+clean output format, then runs its own post-processing pass
+(`docmd/postprocess/`) to fix table structure and normalize heading levels — see
+[ARCHITECTURE.md](ARCHITECTURE.md) for why this is the actual differentiation, not
+just a thin wrapper.
+
+## License
+
+The `docmd` wrapper code is MIT — see [LICENSE](LICENSE).
+
+`docmd` depends on [Marker](https://github.com/datalab-to/marker), whose *code* is
+Apache-2.0 and whose *model weights* are licensed under a modified Open RAIL-M license:
+free for research, personal use, and organizations under $5M in funding or revenue.
+Commercial use beyond that threshold requires a license from
+[Datalab](https://www.datalab.to/pricing). This applies to you if you deploy `docmd`
+commercially at scale — check Marker's current license terms directly before doing so.
+
+## Roadmap
+
+- [x] PDF, DOCX, PPTX → Markdown
+- [x] Table cleanup / heading normalization post-processing
+- [ ] Hosted API
+- [ ] OCR quality tuning for scanned documents
+- [ ] Batch conversion endpoint
+- [ ] HTML output option
+
+## Contributing
+
+Issues and PRs welcome. If you're hitting a conversion quality issue, please include a
+sample file (or a minimal reproduction) — it makes fixes much faster.
+
+---
+
+*If docmd saves you the trouble of setting up your own PDF-parsing pipeline, consider starring the repo — it's how other people find it.*

docmd_cli-0.1.0/README.md

@@ -0,0 +1,124 @@
+# docmd
+
+**Convert PDFs, DOCX, and PPTX to clean, structure-preserving Markdown — from the CLI or a Python library.**
+
+Built for feeding documents into LLM and RAG pipelines, where clean Markdown beats raw text extraction.
+
+*(Published on PyPI as `docmd-cli` since `docmd` was already taken by an unrelated
+package — the import (`import docmd`) and CLI command (`docmd convert ...`) are
+unaffected.)*
+
+```bash
+pip install docmd-cli
+docmd convert report.pdf
+```
+
+```python
+from docmd import convert
+
+markdown = convert("report.pdf")
+print(markdown)
+```
+
+## Why docmd
+
+Great open-source document-to-Markdown converters already exist (docmd is built on
+[Marker](https://github.com/datalab-to/marker)). The problem isn't quality — it's that
+running them yourself means a Python environment, several GB of RAM, ideally a GPU, and
+a non-trivial setup process before you convert your first file.
+
+`docmd` wraps that engine with sane defaults and adds real post-processing on top
+(table cleanup, heading normalization) so the output is closer to what a RAG pipeline
+actually wants, not just raw model output.
+
+A hosted API (`POST` a file, get Markdown back, no local setup) is planned — see
+[ARCHITECTURE.md](ARCHITECTURE.md). It is not live yet; this repo is the open-source
+core, usable standalone today.
+
+## What it handles
+
+| Input | Output |
+|---|---|
+| PDF (text-based) | Markdown with preserved headings, lists, tables |
+| PDF (scanned) | Markdown via OCR — bundled by Marker, free |
+| DOCX | Markdown with formatting preserved (`pip install docmd-cli[full]`) |
+| PPTX | Markdown, one section per slide (`pip install docmd-cli[full]`) |
+
+## Quickstart
+
+**CLI**
+```bash
+pip install docmd-cli
+docmd convert my-file.pdf -o output.md
+```
+
+**Python**
+```python
+from docmd import convert
+
+# From a file path
+markdown = convert("my-file.pdf")
+
+# From bytes
+with open("my-file.pdf", "rb") as f:
+    markdown = convert(f.read(), filename="my-file.pdf")
+```
+
+## Installing DOCX/PPTX support
+
+The base install (`pip install docmd-cli`) covers PDF only and stays lean. DOCX and
+PPTX need Marker's own additional dependencies:
+
+```bash
+pip install "docmd-cli[full]"
+```
+
+DOCX/PPTX conversion also needs [weasyprint](https://doc.courtbouillon.org/weasyprint/stable/first_steps.html#installation)'s
+native Pango/GObject/Cairo libraries, which `pip` cannot install for you:
+
+```bash
+# macOS
+brew install pango
+
+# Debian/Ubuntu
+sudo apt-get install libpango-1.0-0 libpangocairo-1.0-0 libgdk-pixbuf2.0-0 libffi-dev shared-mime-info
+```
+
+PDF conversion (the base install) does not need this.
+
+## How it works
+
+`docmd` wraps [Marker](https://github.com/datalab-to/marker) with sane defaults and a
+clean output format, then runs its own post-processing pass
+(`docmd/postprocess/`) to fix table structure and normalize heading levels — see
+[ARCHITECTURE.md](ARCHITECTURE.md) for why this is the actual differentiation, not
+just a thin wrapper.
+
+## License
+
+The `docmd` wrapper code is MIT — see [LICENSE](LICENSE).
+
+`docmd` depends on [Marker](https://github.com/datalab-to/marker), whose *code* is
+Apache-2.0 and whose *model weights* are licensed under a modified Open RAIL-M license:
+free for research, personal use, and organizations under $5M in funding or revenue.
+Commercial use beyond that threshold requires a license from
+[Datalab](https://www.datalab.to/pricing). This applies to you if you deploy `docmd`
+commercially at scale — check Marker's current license terms directly before doing so.
+
+## Roadmap
+
+- [x] PDF, DOCX, PPTX → Markdown
+- [x] Table cleanup / heading normalization post-processing
+- [ ] Hosted API
+- [ ] OCR quality tuning for scanned documents
+- [ ] Batch conversion endpoint
+- [ ] HTML output option
+
+## Contributing
+
+Issues and PRs welcome. If you're hitting a conversion quality issue, please include a
+sample file (or a minimal reproduction) — it makes fixes much faster.
+
+---
+
+*If docmd saves you the trouble of setting up your own PDF-parsing pipeline, consider starring the repo — it's how other people find it.*

docmd_cli-0.1.0/docmd/__init__.py

@@ -0,0 +1,83 @@
+"""docmd: convert PDF/DOCX/PPTX to clean, structure-preserving Markdown.
+
+    from docmd import convert
+    markdown = convert("report.pdf")
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+from docmd.config import ConvertConfig
+from docmd.converters.base import ConversionResult
+from docmd.converters.registry import get_converter
+from docmd.postprocess.heading_normalize import normalize_headings
+from docmd.postprocess.image_handling import apply_image_handling
+from docmd.postprocess.table_cleanup import clean_tables
+
+__all__ = ["convert", "convert_document", "ConvertConfig", "ConversionResult"]
+__version__ = "0.1.0"
+
+
+def convert_document(
+    source: str | Path | bytes,
+    *,
+    filename: str | None = None,
+    config: ConvertConfig | None = None,
+) -> ConversionResult:
+    """Convert `source` and return the full result (markdown + page count +
+    metadata), after docmd's post-processing pass has run.
+
+    `source` is either a path to a file, or raw bytes - in which case
+    `filename` is required so docmd knows the format (its extension is used
+    to pick a converter; the content itself is what gets converted).
+    """
+    config = config or ConvertConfig()
+
+    if isinstance(source, (bytes, bytearray)):
+        if not filename:
+            raise ValueError("filename is required when passing bytes")
+        suffix = Path(filename).suffix
+        fd, tmp_path = tempfile.mkstemp(suffix=suffix)
+        try:
+            with os.fdopen(fd, "wb") as tmp:
+                tmp.write(source)
+            result = _convert_path(tmp_path, config)
+        finally:
+            os.unlink(tmp_path)
+    else:
+        result = _convert_path(str(source), config)
+
+    return result
+
+
+def convert(
+    source: str | Path | bytes,
+    *,
+    filename: str | None = None,
+    config: ConvertConfig | None = None,
+) -> str:
+    """Convert `source` (a file path, or bytes + filename) and return the
+    resulting Markdown as a string."""
+    return convert_document(source, filename=filename, config=config).markdown
+
+
+def _convert_path(filepath: str, config: ConvertConfig) -> ConversionResult:
+    converter = get_converter(filepath)
+    result = converter.convert(filepath, config)
+
+    markdown = result.markdown
+    if config.clean_tables:
+        markdown = clean_tables(markdown)
+    if config.normalize_headings:
+        markdown = normalize_headings(markdown)
+    markdown = apply_image_handling(markdown, result.images, config.image_mode)
+
+    return ConversionResult(
+        markdown=markdown,
+        page_count=result.page_count,
+        images=result.images,
+        metadata=result.metadata,
+    )

docmd_cli-0.1.0/docmd/cli.py

@@ -0,0 +1,68 @@
+"""`docmd convert <file> [-o output.md]`"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+
+from docmd import convert_document
+from docmd.config import ConvertConfig
+from docmd.errors import DocmdError
+
+
+@click.group()
+@click.version_option(package_name="docmd")
+def main() -> None:
+    """docmd: convert PDF/DOCX/PPTX to clean, structure-preserving Markdown."""
+
+
+@main.command()
+@click.argument("file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option(
+    "-o",
+    "--output",
+    "output",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Write Markdown to this file instead of stdout.",
+)
+@click.option(
+    "--force-ocr",
+    is_flag=True,
+    default=False,
+    help="Force OCR even on pages that already have a text layer.",
+)
+@click.option(
+    "--use-llm",
+    is_flag=True,
+    default=False,
+    help="Use an LLM pass for higher-fidelity table/form extraction (needs a provider API key set for Marker; has a real marginal cost).",
+)
+@click.option(
+    "--image-mode",
+    type=click.Choice(["placeholder", "alt-text", "skip"]),
+    default="placeholder",
+    show_default=True,
+    help="How to represent images in the output.",
+)
+def convert(file: Path, output: Path | None, force_ocr: bool, use_llm: bool, image_mode: str) -> None:
+    """Convert FILE to Markdown."""
+    config = ConvertConfig(force_ocr=force_ocr, use_llm=use_llm, image_mode=image_mode)
+
+    try:
+        result = convert_document(str(file), config=config)
+    except DocmdError as exc:
+        click.echo(f"error: {exc}", err=True)
+        sys.exit(1)
+
+    if output is not None:
+        output.write_text(result.markdown, encoding="utf-8")
+        click.echo(f"wrote {output} ({result.page_count} page(s))", err=True)
+    else:
+        click.echo(result.markdown)
+
+
+if __name__ == "__main__":
+    main()