Support MARKITDOWN_CU_ENDPOINT / MARKITDOWN_DOCINTEL_ENDPOINT env vars so the endpoint is operator-configured, not caller-supplied

[ArlindNocaj]

Problem

--cu-endpoint is a required flag with no environment-variable fallback, so the caller must know and supply the resource endpoint on every invocation. When the caller is an AI agent, this forces the agent to own a piece of deployment configuration it has no business knowing.

The credential is already ambient — ContentUnderstandingConverter falls through to DefaultAzureCredential(), which resolves managed identity / workload identity / az login from the environment. So today the CLI has an asymmetry:

Input	Source	Caller must know it?
Credential	ambient (DefaultAzureCredential, or AZURE_API_KEY env)	❌ no
Endpoint	--cu-endpoint flag only	✅ yes

AZURE_API_KEY — the far more sensitive value — is read from the environment, while the endpoint is not. Closing that gap makes the endpoint follow the same operator-configured model as the credential.

Why this matters for agent/CLI usage

The clean separation is: the operator configures the environment, the agent just runs the tool. That lets an agent invoke:

markitdown report.pdf --use-cu

instead of needing a resource URL injected into its prompt or context.

Concretely, requiring the flag today means the endpoint:

• has to be templated into agent prompts, skill definitions, or system messages;
• ends up in shell history, ps output, CI logs, and agent transcripts on every call;
• must be re-plumbed by every wrapper, instead of being set once at deploy time.

There's already evidence of demand. The community agent skill in #1810 documents handling the Document Intelligence path via MARKITDOWN_DOCINTEL_ENDPOINT — but that variable does not exist in markitdown. The wrapper had to invent the convention and expand it into -e itself, because the CLI offers no env fallback. Standardising it upstream would let wrappers stop reimplementing it and converge on one name.

Current behaviour

$ markitdown report.pdf --use-cu
Content Understanding Endpoint (--cu-endpoint) is required when using --use-cu.
$ echo $?
1

Verified on markitdown 0.1.7. The only environment variables read anywhere in the package are EXIFTOOL_PATH and AZURE_API_KEY:

$ grep -rn 'MARKITDOWN_' site-packages/markitdown/
# (no matches)

Proposed behaviour

Add an environment fallback for both cloud endpoints, with the explicit flag taking precedence:

Flag	Env fallback
--cu-endpoint	MARKITDOWN_CU_ENDPOINT
-e / --endpoint	MARKITDOWN_DOCINTEL_ENDPOINT

Resolution order: explicit flag → environment variable → existing error.

export MARKITDOWN_CU_ENDPOINT="https://<resource>.cognitiveservices.azure.com"
markitdown report.pdf --use-cu                 # resolves from env
markitdown report.pdf --use-cu --cu-endpoint https://other...  # flag still wins

The MARKITDOWN_ prefix matches the name already circulating in the community (#1810) and avoids colliding with the generic AZURE_* variables consumed by DefaultAzureCredential.

Sketch

In __main__.py:

cu_endpoint = args.cu_endpoint or os.environ.get("MARKITDOWN_CU_ENDPOINT")
if cu_endpoint is None:
    _exit_with_error(
        "Content Understanding Endpoint is required when using --use-cu. "
        "Pass --cu-endpoint or set MARKITDOWN_CU_ENDPOINT."
    )

and the equivalent for args.endpoint / MARKITDOWN_DOCINTEL_ENDPOINT.

Compatibility

Fully backward compatible. Existing invocations that pass the flag are unaffected; the env var is consulted only when the flag is absent, which is currently a hard error. No change to the Python API, where cu_endpoint stays an explicit kwarg.

I'm happy to open a PR if the approach and the variable names look right.