Skip to content

Python tool for converting files and office documents to Markdown.

feat(cli): support MARKITDOWN_CU_ENDPOINT / MARKITDOWN_DOCINTEL_ENDPOINT (#2358)

Sinan Olsson-Pasicf618f478a724
diff --git a/README.md b/README.md
index 37be2d1d..138303f4 100644
--- a/README.md
+++ b/README.md
@@ -188,6 +188,13 @@ Content Understanding is ideal when you need capabilities beyond what built-in o
markitdown path-to-file.pdf --use-cu --cu-endpoint "<content_understanding_endpoint>"
```
+The endpoint can also be set once in the environment, so callers only need `--use-cu`:
+
+```bash
+export MARKITDOWN_CU_ENDPOINT="<content_understanding_endpoint>"
+markitdown path-to-file.pdf --use-cu
+```
+
**Python API:**
```python
@@ -244,6 +251,13 @@ To use Microsoft Document Intelligence for conversion:
markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"
```
+The endpoint can also be set once in the environment, so callers only need `-d`:
+
+```bash
+export MARKITDOWN_DOCINTEL_ENDPOINT="<document_intelligence_endpoint>"
+markitdown path-to-file.pdf -o document.md -d
+```
+
More information about how to set up an Azure Document Intelligence Resource can be found [here](https://learn.microsoft.com/en-us/azure/ai-services/document-intelligence/how-to-guides/create-document-intelligence-resource?view=doc-intel-4.0.0)
### Python API
diff --git a/packages/markitdown/src/markitdown/__main__.py b/packages/markitdown/src/markitdown/__main__.py
index eb399fc6..b2575540 100644
--- a/packages/markitdown/src/markitdown/__main__.py
+++ b/packages/markitdown/src/markitdown/__main__.py
@@ -2,6 +2,7 @@
#
# SPDX-License-Identifier: MIT
import argparse
+import os
import sys
import codecs
from typing import Any, Dict
@@ -98,13 +99,15 @@ def main():
"-e",
"--endpoint",
type=str,
- help="Document Intelligence Endpoint. Required if using Document Intelligence.",
+ default=os.environ.get("MARKITDOWN_DOCINTEL_ENDPOINT") or None,
+ help="Document Intelligence Endpoint. Required if using Document Intelligence. Defaults to the MARKITDOWN_DOCINTEL_ENDPOINT environment variable.",
)
parser.add_argument(
"--cu-endpoint",
type=str,
- help="Content Understanding Endpoint. Required if using --use-cu.",
+ default=os.environ.get("MARKITDOWN_CU_ENDPOINT") or None,
+ help="Content Understanding Endpoint. Required if using --use-cu. Defaults to the MARKITDOWN_CU_ENDPOINT environment variable.",
)
parser.add_argument(
@@ -203,7 +206,8 @@ def main():
if args.use_docintel:
if args.endpoint is None:
_exit_with_error(
- "Document Intelligence Endpoint is required when using Document Intelligence."
+ "Document Intelligence Endpoint is required when using Document Intelligence. "
+ "Pass -e/--endpoint or set MARKITDOWN_DOCINTEL_ENDPOINT."
)
elif args.filename is None:
_exit_with_error("Filename is required when using Document Intelligence.")
@@ -215,6 +219,7 @@ def main():
if args.cu_endpoint is None:
_exit_with_error(
"Content Understanding Endpoint (--cu-endpoint) is required when using --use-cu."
+ "Pass --cu-endpoint or set MARKITDOWN_CU_ENDPOINT."
)
cu_kwargs: Dict[str, Any] = {
diff --git a/packages/markitdown/tests/test_cu_converter.py b/packages/markitdown/tests/test_cu_converter.py
index 33fca831..20b517f7 100644
--- a/packages/markitdown/tests/test_cu_converter.py
+++ b/packages/markitdown/tests/test_cu_converter.py
@@ -5,6 +5,7 @@ Follows the same pattern as test_docintel_html.py.
"""
import io
+import os
import sys
from unittest.mock import MagicMock, patch
@@ -801,6 +802,7 @@ class TestCLIArgs:
[sys.executable, "-m", "markitdown", "--use-cu", "fake.pdf"],
capture_output=True,
text=True,
+ env={**os.environ, "MARKITDOWN_CU_ENDPOINT": ""},
)
assert result.returncode != 0
assert (
@@ -961,3 +963,73 @@ class TestMissingDependency:
assert "az-content-understanding" in str(exc_info.value)
assert exc_info.value.__cause__ is import_error
+
+
+# ---------------------------------------------------------------------------
+# Endpoint environment variables (issue #2326)
+# ---------------------------------------------------------------------------
+
+
+class TestEndpointEnvVars:
+ """Endpoint flags fall back to operator-configured environment variables."""
+
+ @pytest.mark.parametrize(
+ "env_var, argv, kwarg",
+ [
+ (
+ "MARKITDOWN_CU_ENDPOINT",
+ ["markitdown", "--use-cu", "fake.pdf"],
+ "cu_endpoint",
+ ),
+ (
+ "MARKITDOWN_DOCINTEL_ENDPOINT",
+ ["markitdown", "-d", "fake.pdf"],
+ "docintel_endpoint",
+ ),
+ ],
+ )
+ def test_endpoint_read_from_environment(self, monkeypatch, env_var, argv, kwarg):
+ """With the env var set, the endpoint flag can be omitted entirely."""
+ from markitdown.__main__ import main
+
+ monkeypatch.setenv(env_var, "https://from-env")
+ monkeypatch.setattr(sys, "argv", argv)
+
+ with patch("markitdown.__main__.MarkItDown") as mock_markitdown:
+ main()
+
+ assert mock_markitdown.call_args.kwargs[kwarg] == "https://from-env"
+
+ def test_flag_overrides_environment(self, monkeypatch):
+ """Fails if the env var is ever read after parsing instead of as an argparse default."""
+ from markitdown.__main__ import main
+
+ monkeypatch.setenv("MARKITDOWN_CU_ENDPOINT", "https://from-env")
+ monkeypatch.setattr(
+ sys,
+ "argv",
+ [
+ "markitdown",
+ "--use-cu",
+ "--cu-endpoint",
+ "https://from-flag",
+ "fake.pdf",
+ ],
+ )
+
+ with patch("markitdown.__main__.MarkItDown") as mock_markitdown:
+ main()
+
+ assert mock_markitdown.call_args.kwargs["cu_endpoint"] == "https://from-flag"
+
+ def test_empty_environment_variable_is_treated_as_unset(self, monkeypatch, capsys):
+ """An empty env var must not pass as a valid endpoint."""
+ from markitdown.__main__ import main
+
+ monkeypatch.setenv("MARKITDOWN_CU_ENDPOINT", "")
+ monkeypatch.setattr(sys, "argv", ["markitdown", "--use-cu", "fake.pdf"])
+
+ with pytest.raises(SystemExit):
+ main()
+
+ assert "MARKITDOWN_CU_ENDPOINT" in capsys.readouterr().out