SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsmarkitdown-cli

markitdown-cli

Office & productivity

View repository

Updated 10-15 21:48

About this skill

MarkItDown CLI Complete Usage Guide

Purpose is clear: enable LLMs to generate based on this skillcorrect, copy-pasteableof the markitdown command-line invocation.

Offline baseline: based on the markitdown command's argparse (see packages/markitdown/src/markitdown/__main__.py). Any judgment of "whether this parameter exists" is based on the source code; when this document conflicts with the official README,the official one prevails。

When to Use This Skill

✅ When to use this skill(pure CLI / command-line questions):

  • User asks "how do I use the markitdown command? What parameters are there?"
  • User wants to batch-convert PDF/PPT/Word → Markdown
  • User wants to feed stdin streams (pipe / curl output) to markitdown
  • User asks "how do I list installed plugins", "how do I enable plugins"
  • User asks about the CLI configuration for Azure Document Intelligence / Content Understanding
  • User asks "how does the CLI write output to a file instead of stdout"

❌ When not to use this skill:

  • Want to use the Python API → markitdown-awesome of references/api/python-api.md
  • Want to do OCR (embedded images / scanned PDFs / LLM Vision) → markitdown-ocr
  • Want to understand what MarkItDown is, which formats it supports → markitdown-awesome
  • User already knows markitdown, just asking about best practices → give examples directly, don't detour to this skill

⚠️ Gray areas:

  • User asks "how do I do OCR" → default to markitdown-ocr(because the CLI currently does not support LLM parameters).
  • User asks "how do I convert PDF" but doesn't state the scenario → default to the CLI path, but also note: if it's a scanned document, Azure DI is recommended.

Workflow

Each time you answer a CLI-type question, go through the following process once:

Step 1 — Confirm input and output

  • Input:<file> / stdin / http(s)://…?
  • Output:stdout / -o out.md / tee reuse?
  • Is there a special format that needs to be noted (-x / -m)?

Step 2 — Choose backend (default / Azure DI / Azure CU)

  • Default (local): don't pass -d and don't pass --use-cu
  • High-quality PDF/scans:-d -e <endpoint>
  • Multimodal/structured fields:--use-cu --cu-endpoint <endpoint>

Step 3 — Choose whether to enable plugins

  • OCR(LLM Vision)→ -p, but remember the CLI does not have --llm-client/--llm-model,requires a Python wrapper(see markitdown-ocr)
  • Custom plugins → same as above,-p is enough

Step 4 — Assemble the command and self-check

Compare against Validation self-check checklistgo through it once.

Step 5 — Handle errors

If the user gives MissingDependencyException / UnsupportedFormatException and other exceptions, jump to §8 Troubleshooting Quick Reference.

Step 6 — Give next-step suggestions

After outputting the command, add: "If you need batching / CI integration / Docker, see examples/advanced/safe-batch-processing.md"。

Validation (self-check checklist)

After each command is generated, go through once:

  • -d and --use-cu do notappear at the same time?
  • When using -d , when usingmust include -e <endpoint>?
  • When using --use-cu , when usingmust include --cu-endpoint <endpoint>?
  • Reading from stdin but the file has no extension → added -x or -m?
  • Going through an HTTP URL → evaluated SSRF risk?
  • Output contains non-ASCII → recommended -o out.md instead of stdout?
  • User installed the plugin but did not enable it → prompt to add -p?
  • CLI has no --llm-client → did not falsely promise that OCR can be enabled from the command line?
  • --list-plugins and "convert file" are not on the same command line?

Gotchas

Ordered by hit frequency from high to low:

  1. -d and --use-cu are mutually exclusive — argparse enforces mutually_exclusive_group, and if both appear at the same time it errors out directly.
  2. -d must be paired with -e — otherwise __main__.py actively _exit_with_error("Document Intelligence Endpoint is required …")。
  3. --use-cu must be paired with --cu-endpoint — same logic as above.
  4. CLI has no --llm-client / --llm-model — to enable OCR from the command line, you must use a Python wrapper (see markitdown-ocr)。do not invent a nonexistent flag。
  5. --list-plugins triggers sys.exit(0) — when combined with "convert file" on the same command line, the conversion logic will not run at all.
  6. When reading from stdin there is no extension → must -x or -m — otherwise accepts() are all False, reporting UnsupportedFormatException。
  7. -c charset is validated with codecs.lookup — a typo will _exit_with_error("Invalid charset: …"); common usable values:utf-8、utf-16、latin-1、gbk(must be registered in the system codecs).
  8. CLI outputs garbled Chinese — when the terminal LANG != *UTF-8 , add -o out.md to write to disk.
  9. --keep-data-uris by default does not retain — base64 images in the output will be truncated; if the user needs images, use --keep-data-uris。
  10. HTTP URL performs a real GET — convert_uri internally sends a request; SSRF risk is borne by the caller. For production, it is recommended to use Python requests.get() + convert_response()。
  11. Large file memory peak — convert_local reads all at once open(path, "rb"), and a several-hundred-MB PDF may blow up memory. For streaming scenarios use convert_stream。
  12. Missing optional dependency — when reporting MissingDependencyException , install by format pip install 'markitdown[<extra>]' , do not omit the square brackets.
  13. Azure credentials — DI/CU use the default credential chain by default; in the CLIthere is nooption to explicitly pass a key, and credentials are determined by the environment/SDK.
  14. --cu-file-types accepts a comma-separated string — writing the wrong type name will _exit_with_error("Unknown file type: …"), aligned with the ContentUnderstandingFileType enum.
  15. A broken pipe causes BrokenPipeError — when using markitdown f.pdf | head , MarkItDown will finish writing the entire markdown and then print triggers EPIPE;does not affect the result, but head a nonzero exit code will make set -o pipefail fail.

1. Minimal form

markitdown <file>            # 转 stdout
markitdown <file> -o out.md  # 写文件
cat <file> | markitdown      # 从 stdin 读
markitdown < <file>          # 等价写法

<file> can be omitted: when omitted, it forces reading from stdin. Note: when using stdin, MarkItDown does not know the real extension, so you need to use -x or -m to hint.

2. Full parameter list

Short option Long option Type Description
-v --version flag Print version number and exit
-o --output str Output file; by default writes to stdout
-x --extension str Extension hint (leading .may be omitted). E.g.:-x pdf
-m --mime-type str MIME hint, e.g. -m application/pdf
-c --charset str Charset hint, e.g. -c utf-8
-d --use-docintel flag Use the Azure Document Intelligence backend, requires configuring -e
-e --endpoint str Document Intelligence endpoint URL
— --use-cu / --use-content-understanding flag To use Azure Content Understanding, you need --cu-endpoint
— --cu-endpoint str Content Understanding endpoint
— --cu-analyzer str a custom analyzer ID; if omitted, it is automatically selected by file type
— --cu-file-types str comma-separated, e.g. --cu-file-types pdf,jpeg,mp4
-p --use-plugins flag Enable markitdown.plugin third-party plugins discovered via entry points
— --list-plugins flag List installed plugins, then exit after listing
— --keep-data-uris flag Keep data:image/...;base64,… URIs in the output (by default they are truncated)

Mutually exclusive group:-d(--use-docintel) and --use-cu are mutually exclusive; you can choose only one.

3. Input/Output Matrix

Usage Command Template When to Use
Single file → stdout markitdown a.pdf When you want to pipe directly to another tool
Single file → file markitdown a.pdf -o a.md The most common "output to file" pattern
stdin → stdout cat a.pdf | markitdown Programmatic invocation, without writing intermediate files
stdin → file cat a.pdf | markitdown -o a.md shell chaining
stdin + hint cat blob | markitdown -x pdf File has no extension or the extension is wrong
stdin + MIME curl … | markitdown -m application/pdf Fetch remotely, then convert
HTTP URL markitdown https://example.com/doc.html A URL passed directly in the CLI will be parsed as a URI

The CLI currently has no -i/--input parameter; you can only rely on stdin or the <file> placeholder.

4. Output Control

  • stdout encoding fault tolerance:_handle_output() will use sys.stdout.encoding + errors="replace" to write,it will not crash due to terminal encoding。
  • Very large output:MarkItDown by default writes it all at once print(result.markdown), do not dump it into a log file. It is recommended to add -o。
  • Image data URI:--keep-data-uris controls whether to keep data:image/...;base64,…in the output Markdown (by default it is truncated to reduce size).

5. Plugin Management

# 看装了哪些插件
markitdown --list-plugins
# 输出类似:
# Installed MarkItDown 3rd-party Plugins:
#   * ocr              (package: markitdown_ocr)
#   * my-plugin        (package: my_pkg)
# 若没有:打印 "  * No 3rd-party plugins installed."

# 启用插件
markitdown scanned.pdf -p
# 加 LLM 参数配合 markitdown-ocr:
markitdown scanned.pdf -p --llm-client openai --llm-model gpt-4o

⚠️ markitdown --list-plugins and -p/--use-plugins do not conflict—but __main__.py in --list-plugins immediately sys.exit(0)after being triggered, so it cannot be combined with "convert file" on the same command line.

5.1 Configure an OpenAI-compatible client via environment variables (with markitdown-ocr)

export OPENAI_API_KEY=sk-...
markitdown scanned.pdf -p --llm-client openai --llm-model gpt-4o

⚠️ Note:__main__.py current argparse does not register the --llm-client and --llm-model options(they are only available in the Python API MarkItDown(llm_client=…, llm_model=…) ). To enable OCR via the CLI, the most reliable way at present is to write a 3-line Python wrapper (see markitdown-ocr skill)。If the official version adds CLI options in the future, follow the official documentation first。

6. Azure Backend Switching

6.1 Document Intelligence(-d -e)

markitdown scan.pdf -d -e "https://<resource>.cognitiveservices.azure.com/"

Applicable to: high-quality PDFs, scanned documents, table extraction. Requires pip install 'markitdown[az-doc-intel]', and the environment must be able to access that endpoint (Azure credentials use the default chain).

6.2 Content Understanding(--use-cu --cu-endpoint)

# 自动选 analyzer(按文件类型:documentSearch/videoSearch/audioSearch)
markitdown report.pdf --use-cu --cu-endpoint "https://<cu>.services.ai.azure.com/"

# 自定义 analyzer
markitdown invoice.pdf --use-cu \
  --cu-endpoint "https://<cu>.services.ai.azure.com/" \
  --cu-analyzer "my-invoice-analyzer"

# 仅对部分类型启用 CU
markitdown mixed_files/ --use-cu \
  --cu-endpoint "https://<cu>.services.ai.azure.com/" \
  --cu-file-types pdf,jpeg,mp4

Applicable to: multimodal (documents/images/audio/video), requiring structured YAML front matter, custom analyzers.

For the full comparison (CLI ↔ Python API ↔ service endpoint), see azure/endpoint-matrix.md; for practical scripts, see examples/azure/azure-backends.md。

7. Typical Workflow Examples

7.1 Batch convert directory PDFs to Markdown

find ./inbox -name '*.pdf' -print0 | while IFS= read -r -d '' f; do
  out="./md/$(basename "${f%.pdf}").md"
  markitdown "$f" -o "$out"
done

7.2 Use with xargs in parallel (use with caution)

find ./inbox -name '*.pdf' -print0 \
  | xargs -0 -n1 -P4 -I{} sh -c 'markitdown "{}" -o "./md/$(basename "{}" .pdf).md"'

⚠️ Some PDF processing consumes a large amount of memory and network IO; the degree of parallelism should not exceed the number of CPUs.

7.3 Use with jq/grep for subsequent filtering

# 把 PDF 转 Markdown,然后保留所有 "##" 开头的章节
markitdown report.pdf | grep -E '^##' > outline.md

7.4 Save fetched web pages as Markdown

curl -sL "https://example.com/article.html" \
  | markitdown -m text/html \
  > article.md

7.5 Docker one-line command

Reference Dockerfile(docker build -t markitdown:latest . after):

docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md
# 等价于:
docker run --rm -v "$PWD":/data markitdown:latest /data/your-file.pdf -o /data/output.md

For more batch / CI / Docker practical examples, see examples/advanced/workflows.md and examples/advanced/safe-batch-processing.md。

8. Troubleshooting Quick Reference

Symptom Troubleshooting Command / Approach
Error MissingDependencyException pip install 'markitdown[对应特性]'(e.g. [pdf]/[docx]/[pptx])
UnsupportedFormatException Use file <path> to see the actual type, add -x/-m hint; or confirm the corresponding extras are installed
Chinese output garbled Ensure the terminal LANG=*UTF-8*, or add -o out.md to avoid terminal encoding issues
Using -d but reports missing endpoint The CLI already requires -e; if it still reports "endpoint required", check whether -pwas also passed, sometimes the parameter order needs to be rearranged
Using --use-cu but reports analyzer does not exist First use the default automatic selection (do not pass --cu-analyzer), confirm the endpoint is reachable
All data:image… in the output are gone Add --keep-data-uris
Plugin installed but convert not taking effect Use markitdown --list-plugins to confirm the plugin is recognized; then confirm -p
OCR did not run at all Use markitdown-ocr skill — must be injected via the Python API llm_client

9. Security Notes

  • MarkItDown performs I/O with the current process permissions.Do notfeed arbitrary URLs directly to markitdown https://..., otherwise the SSRF risk is borne by the caller.
  • In container scenarios, be sure to restrict --user and --read-only volume mounts.

10. When to Jump to a Sibling Skill

User Question Jump to
"What is MarkItDown, which formats does it support, and how is the architecture set up?" markitdown-awesome
"How to use an LLM (GPT-4o / Azure OpenAI) for OCR, scanned PDFs, and embedded image OCR?" markitdown-ocr
"How to use the Python API instead of the CLI?" markitdown-awesome of references/api/python-api.md

11. Privacy Policy

This Skill only provides local documents and examples,does not collect, store, or transmit any user data. Command invocations and Azure endpoint communication are initiated by the user in their own environment, and privacy responsibility is borne by the user.

12. Reference Links

  • Official README
  • Official argparse source code
  • Dockerfile
  • Parameter quick reference: in this repository references/cli/cheatsheet.md
  • Sibling Skill:markitdown-awesome — after installing with npx skills add full-stack-skills/document-skills --skill markitdown-awesome , reference it by skill name
  • Sibling Skill:markitdown-ocr — after installing with npx skills add full-stack-skills/document-skills --skill markitdown-ocr , reference it by skill name
  • Full installation:npx skills add full-stack-skills/document-skills(install all 11 skills at once)