CLI 命令参考
基本用法
markitai <input> [options]<input> 可以是:
- 文件路径 (
document.docx) - 目录路径 (
./docs) - URL (
https://example.com)
转换选项
--llm
启用 LLM 驱动的格式清洗和优化。默认只写入 .llm.md(跳过基础 .md)。使用 --keep-base 可以同时写入两个文件。
markitai document.docx --llm社媒帖(由站点提取器整理、标记为 content_profile: social_post 的内容,如 X/Twitter 帖子)的正文会原样直通。LLM 仅生成 frontmatter 元数据,帖子结构和原文措辞不会被改动。
目录批量转换可用 --llm-batch 走服务商的 Batch API,价格为实时调用的一半:
markitai docs/ --llm --llm-batch -o out/ # 挂等到 --llm-batch-timeout(默认 1 小时),超时转两段式
markitai --llm-batch-collect <batch-id> -o out/ # 稍后收取已转交的 batch需要单模型的 OpenAI 或 Anthropic 池。命中缓存的文档立即完成;batch 中失败的文档会逐个实时重跑,部分失败不会丢输出。OpenAI 侧的推理模型在 batch 中以关闭推理运行——batch 部署对 function tools 的硬性要求。--alt/--desc 与 --screenshot 都与文档增强同批提交,图片分析和页图增强同样享受折扣;页数超过单次调用上限的文档改为实时增强,因为批处理多一轮就多一次等待。暂不能与 --ocr 组合——它的页图从不渲染:batch 第一阶段关闭 LLM 转换,而那正是用本地 OCR 读扫描页的分支。
TIP
--llm、--alt、--desc、--ocr、--screenshot 都有对应的 --no-* 反义参数(--no-llm、--no-alt、--no-desc、--no-ocr、--no-screenshot),可用来显式关闭某个预设本会启用的特性,例如 --preset rich --no-desc。
-p, --preset <name>
使用预定义的配置预设。
| 预设 | 说明 |
|---|---|
rich | LLM + alt + desc + screenshot |
standard | LLM + alt + desc |
minimal | 仅基础转换 |
markitai document.pdf --preset rich
markitai document.pdf --preset rich --no-desc # rich 但不生成 desc,任何预设特性都可用 --no-* 单独关闭--profile <name>
为下游消费者塑形输出。与 --preset 正交:预设决定运行哪些功能,profile 决定输出长什么样。不带 --profile 时输出不变。
| Profile | 效果 |
|---|---|
rag | 可见的 assets/ 目录(而非隐藏的 .markitai/assets/)、PDF 注入 <!-- page: N --> 页标记、管道表列数校验 |
obsidian | 可见的 assets/ 目录;可通过 output.wikilinks 启用 wikilink 图片引用 |
okf | frontmatter 对齐 Open Knowledge Format 规范 |
markitai document.pdf --profile rag -o out/
markitai document.pdf --preset rich --profile rag -o out/ # 功能 + 形态详见输出 Profile。
--alt
使用 AI 生成图片的 alt 文本。需要 --llm,未启用时会跳过图片分析并给出提示。
markitai document.pdf --llm --alt--desc
生成图片的详细描述。需要 --llm,未启用时会跳过图片分析并给出提示。
markitai document.pdf --llm --desc--screenshot
启用截图捕获:
- PDF/PPTX: 将页面/幻灯片渲染为 JPEG 图片
- URL: 使用 Playwright 捕获全页面截图
# 文档截图
markitai document.pdf --screenshot
markitai presentation.pptx --screenshot
# URL 截图
markitai https://example.com --screenshotTIP
对于 URL,--screenshot 会在需要时自动将抓取策略升级为 playwright。截图将保存为 .markitai/screenshots/{域名}_路径.full.jpg。
--screenshot-only
仅捕获截图,不提取内容。对 URL 输入而言,行为取决于是否启用 --llm:
| 命令 | 输出 |
|---|---|
--screenshot-only | 仅截图(不生成 .md 文件) |
--llm --screenshot-only | .llm.md + 截图(LLM 从截图提取内容);加 --keep-base 可同时得到 .md |
# 仅捕获截图
markitai https://example.com --screenshot-only
# LLM 纯粹从截图提取内容
markitai https://example.com --llm --screenshot-onlyTIP
当传统内容提取失败时(如重 JavaScript 网站、社交媒体),使用 --llm --screenshot-only 模式。
WARNING
对于文件输入(PDF/PPTX),不加 --llm 的 --screenshot-only 不会跳过 .md,仍会照常写入提取出的文本 Markdown,只是额外附带截图。上面“不生成 .md 文件”的保证仅适用于 URL 输入。
当配置文件启用了该模式时,用 --no-screenshot-only 关掉它。
--ocr
为扫描文档启用 OCR。
markitai scanned.pdf --ocr- 不带
--llm:--ocr使用本地 RapidOCR。 - 带
--llm(--ocr --llm):由视觉模型直接读取页面图像(VLM OCR),不再走 RapidOCR——无需本地 OCR 后端,但页面图像会发送给远端模型;设置MARKITAI_NO_VLM_OCR=1可强制走本地 RapidOCR。
处理单张图片时,请使用 --ocr 提取文字,或使用 --llm 分析图片。如果两者都未启用,Markitai 会以状态码 1 退出,不会在没有任何输出时仍报告转换成功。
PDF 里的数学公式
PDF 文本抽取本身不认识「公式」这个概念,所以公式能保留多少,取决于模型能看到多少页面:
| 运行方式 | 公式的下场 |
|---|---|
--ocr --llm | 行内公式写成 $...$ LaTeX,被抽取噪声吞掉的正文也会一并还原 |
--alt / --desc | 独立成行的公式是以图片形式进入 markitai 的,其 LaTeX 会被还原进 images.json 的 text 字段,alt 文本给出概述 |
| 都不带 | 独立公式保留为图片引用——内容不丢,但也不是文本;行内公式维持抽取噪声原样 |
网页不同:MathJax 和 MathML 无需模型参与,直接转换为 $...$ / $$...$$。
--pure
透明直通模式:LLM 仅做文本清理,不生成 frontmatter 或后处理。
# 不带 --llm:输出原始 markdown,不含 frontmatter
markitai document.docx --pure
# 带 --llm:通过 LLM 仅做文本清理
markitai document.docx --llm --pure
# 带 --preset:preset 控制功能,--pure 控制输出格式
markitai document.pdf --preset rich --pureTIP
--pure 和 --llm 是独立的标志。--pure 单独使用时跳过 frontmatter 生成;--pure --llm 将内容发送给 LLM 做文本清理,但返回原始输出,不包含生成的元数据(description、tags 等)。
WARNING
--pure 会静默覆盖 --alt、--desc 和 --screenshot。同时使用这些标志时会显示警告。
当配置文件启用了纯净模式时,用 --no-pure 恢复 frontmatter 和后处理。
--keep-base
在 LLM 模式下仍写入基础 .md 文件。默认情况下 --llm 只输出 .llm.md 以避免冗余文件。
# 默认:只写入 .llm.md
markitai document.docx --llm
# 同时保留 .md 和 .llm.md
markitai document.docx --llm --keep-base--no-compress
禁用图片压缩。
markitai document.pdf --no-compress当配置文件禁用了压缩时,用 --compress 重新开启。
输出选项
-o, --output <path>
指定输出位置。对单个文件/URL 输入,-o 也可以是一个具体文件路径(如 -o result.md),而不一定是目录。省略时,单文件/URL 转换会输出到 stdout;目录批量与 .urls 列表输入则必须指定 -o。
markitai document.docx -o ./output
markitai document.docx -o ./result.md--resume
恢复中断的批量处理。已完成的文件会跳过,FAILED/中断时处于 IN_PROGRESS 的文件会重试,本次新增的文件也会被纳入,并报告 Resuming batch: N completed, M remaining。仅对批量输入(目录/.urls)生效,单个文件/URL 输入时会被忽略。
markitai ./docs -o ./output --resume--record-history
将本次完成的运行记录为 markitai serve 历史中的任务(保存在 ~/.markitai/serve/jobs/ 下,输出与引用的资源会一并复制),使其无需重启服务即可实时出现在网页界面的历史页面中。CLI 记录的条目带有「CLI」徽标,并与网页创建的任务共享七天清理、删除与归档下载。
markitai document.docx -o ./output --record-history优先级:--record-history / --no-record-history > MARKITAI_RECORD_HISTORY(真值:1/true/yes/on;已设置但为假值表示显式关闭)> 配置项 history.record > 默认(关闭)。stdout/管道模式下跳过记录;记录完全容错,绝不会导致转换失败,完成后在 stderr 打印一行确认信息(可被 --quiet 抑制)。参见配置 → 环境变量。
并发选项
--llm-concurrency <n>
LLM 并发请求数(默认:10)。
markitai ./docs --llm --llm-concurrency 10-j, --batch-concurrency <n>
文件处理并发数(默认:10)。
markitai ./docs -o ./output -j 4TIP
对于文件和 URL 混合的批处理,使用 --url-concurrency 单独控制 URL 抓取。这样可以防止慢速 URL 阻塞文件处理。
缓存选项
--no-cache
禁用 LLM 结果缓存(强制重新调用 API)。
markitai document.docx --llm --no-cache当配置文件禁用了缓存时,用 --cache 重新允许读取缓存。
--no-cache-for <patterns>
对特定文件或模式禁用缓存(逗号分隔)。
# 单个文件
markitai ./docs --no-cache-for file1.pdf
# Glob 模式
markitai ./docs --no-cache-for "*.pdf"
# 多个模式
markitai ./docs --no-cache-for "*.pdf,reports/**"URL 选项
.urls 文件支持
当输入为 .urls 文件时,Markitai 自动将其作为 URL 批量任务处理。目录批量输入也会自动发现扫描树内的 .urls 文件并处理(遵循相同的 --glob/--max-depth 规则),将其中的 URL 与常规文件合并到同一次批量任务中。
markitai urls.urls -o ./output.urls 文件支持三种格式:
纯文本:每行一个 URL,可在 URL 后加空白与自定义输出文件名:
# 以 # 开头的是注释
https://example.com/page1
https://example.com/page2 custom_nameURL 字符串组成的 JSON 数组:
["https://example1.com", "https://example2.com"]对象组成的 JSON 数组,可选 output_name:
[
{"url": "https://example1.com"},
{"url": "https://example2.com", "output_name": "custom"}
]如果批次中有 URL 失败,已成功的 URL 结果仍会保留。部分成功的 .urls 任务以状态码 10 退出,脚本和 CI 可以据此区分完整成功与部分失败。
--glob, -g <pattern>
限制目录批量扫描的匹配模式。可重复指定多个模式。使用 ! 前缀排除。
# 只处理 PDF 文件
markitai ./docs -o ./output -g "*.pdf"
# 处理 PDF 和 DOCX 文件
markitai ./docs -o ./output -g "*.pdf" -g "*.docx"
# 排除子目录
markitai ./docs -o ./output -g '!drafts/**'TIP
仅适用于目录输入。在有历史扩展的 shell(如 zsh)中使用 ! 前缀时请使用单引号。
--max-depth <n>
覆盖目录递归扫描深度(默认:5)。0 表示仅扫描输入目录本身(不递归)。
markitai ./docs -o ./output --max-depth 2--url-concurrency <n>
URL 抓取并发数(默认:5)。与 --batch-concurrency 独立,防止慢速 URL 阻塞文件处理。
markitai ./docs -o ./output --url-concurrency 5-s, --strategy <name>
选择 URL 抓取策略。这是抓取 URL 的主要参数,与下方的 -b/--backend 正交。
| 取值 | 说明 |
|---|---|
auto(默认) | 按策略优先级依次尝试,失败自动回退 |
static | 使用内置 webextract 的静态 HTTP 抓取,快速、无需 JS、无需外部 API |
playwright | Playwright 浏览器渲染,适用于 JavaScript 重度依赖的 SPA 网站(如 x.com) |
defuddle | Defuddle API,免费、无需认证,内容清洗效果优秀 |
jina | Jina Reader API,浏览器渲染不可用时的云端替代方案 |
cloudflare | Cloudflare Browser Rendering /content API,同时会启用 Workers AI toMarkdown 文件转换(见 -b/--backend) |
markitai https://example.com -s defuddle
markitai https://x.com/user/status/123 -s playwrightTIP
-s cloudflare 需要 CLOUDFLARE_API_TOKEN 和 CLOUDFLARE_ACCOUNT_ID(环境变量或 markitai.json 中配置)。在 dash.cloudflare.com/profile/api-tokens 创建 Token,添加 Browser Rendering: Edit 和 Workers AI: Read 权限。详见配置说明 → Cloudflare 设置。
TIP
如需预先安装 Playwright 浏览器:
uv run playwright install chromium
# Linux 还需安装系统依赖:
uv run playwright install-deps chromium-b, --backend <name>
选择文件转换后端,与 -s/--strategy(仅影响 URL 抓取)正交。
| 取值 | 说明 |
|---|---|
native(默认) | 内置转换器(DOCX、PDF、图片等) |
cloudflare | Cloudflare Workers AI toMarkdown,需要 CF 凭据 |
markitai document.pdf -b cloudflare
markitai https://example.com -s playwright -b cloudflare # -s 与 -b 可自由组合TIP
Cloudflare Browser Rendering 在 Free 计划上可用。Workers AI toMarkdown 对 PDF/Office/CSV/XML 免费;图片转换使用 Neurons 配额。对于有本地转换器的格式,内置转换器通常输出质量更高。存在更优本地转换器时,-b cloudflare 会给出提示。
已移除的旧后端参数
下面 6 个后端别名已在 1.0.0 移除。继续传入会得到一条指明替代写法的用法错误,因此旧脚本会直接报错,而不是悄悄用错引擎完成转换:
| 已移除参数 | 改用 |
|---|---|
--playwright | -s playwright |
--defuddle | -s defuddle |
--static | -s static |
--jina | -s jina |
--cloudflare | -s cloudflare(需要 CF 文件转换时再加 -b cloudflare) |
--kreuzberg | (无——.rtf 自 1.0.0 起原生转换) |
markitai https://example.com -s defuddle # 替代旧的 --defuddle这些别名带来的互斥规则也随之取消:-s/--strategy 与 -b/--backend 相互正交,可自由组合。
初始化命令
markitai init
交互式配置向导,检查依赖项、检测 LLM 提供商(包括 ChatGPT OAuth、Claude/Copilot CLI,以及 GEMINI_API_KEY 环境变量)并生成配置文件。
# 交互式配置向导
markitai init
# 快速模式(不询问直接生成默认配置)
markitai init --yes
markitai init -y
# 生成本地项目配置(./markitai.json)
markitai init --local
# 指定输出路径
markitai init -o ./markitai.json-I, --interactive
进入交互模式,引导式文件转换设置。
markitai -I配置命令
markitai config list
显示当前生效的配置。默认会递归遮罩秘密值,包括提供商、抓取或认证设置中的嵌套字段。
markitai config list # 默认格式:json
markitai config list --format table # 简洁表格视图
markitai config list -f yaml # 需要:uv add pyyaml
markitai config list --show-secrets # 明确要求显示原始值WARNING
--show-secrets 仅供本机检查。不要把它的完整输出贴到 issue、聊天、CI 日志或其他共享渠道。
markitai config get <key>
获取特定配置值。
markitai config get llm.enabled
markitai config get cache.enabledmarkitai config set <key> <value>
设置配置值。
markitai config set llm.enabled true
markitai config set cache.enabled falsemarkitai config path
显示配置文件路径。
markitai config pathmarkitai config edit
交互式编辑配置设置,通过引导式菜单操作。
markitai config editmarkitai config validate
验证配置文件。
markitai config validate
markitai config validate ./markitai.json # 验证指定文件缓存命令
markitai cache stats
显示缓存统计信息。
markitai cache stats
markitai cache stats -v # 详细模式(等同于 --verbose)
markitai cache stats --json # JSON 输出
markitai cache stats --verbose --limit 50 # 限制显示条目数(默认:20)markitai cache clear
清除缓存数据。
markitai cache clear
markitai cache clear -y # 跳过确认
markitai cache clear --include-spa-domains # 同时清除已学习的 SPA 域名markitai cache spa-domains
查看或管理已学习的 SPA 域名。这些是自动检测到需要浏览器渲染的域名。
markitai cache spa-domains # 列出已学习的域名
markitai cache spa-domains --json # JSON 输出
markitai cache spa-domains --clear # 清除所有已学习的域名TIP
SPA 域名会在静态抓取检测到 JavaScript 依赖时自动学习。这可以加速后续请求,避免浪费的静态抓取尝试。
诊断命令
markitai doctor
检查核心状态、可选能力和认证状态。缺少未启用的可选工具只会显示警告,不代表基础安装失败。当已配置的 Playwright 工作流无法启动、活跃 API 模型引用了缺失的环境变量、已启用的本地 LLM Provider 无法加载或认证,或明确请求的自动修复未成功时,命令会以非零状态码退出,因此脚本和 CI 可以依赖该结果。
markitai doctor
markitai doctor --fix # Playwright 包已存在时,安全安装并重新检查 Chromium
markitai doctor --json # JSON 输出
markitai doctor --suggest-extras # 输出适合 `uv tool install "markitai[...]"` 的逗号分隔 extras 列表,包含 browser/extra-fetch/svg/heif/ocr 及检测到的提供商 extra每一项都是能力报告,没有启用的能力不会让整次检查失败:
- 可选:RapidOCR,用于对扫描件和图片执行
--ocr。它随ocrextra 提供,不在核心安装内,因此这里显示「未安装」只表示 OCR 未开启,而不是安装损坏 - 可选:VLM OCR,用于对扫描件执行
--ocr --llm:由视觉模型读取页面图像,替代 RapidOCR。配置了视觉模型即可用;设置MARKITAI_NO_VLM_OCR=1可强制走本地 RapidOCR - 未配置时可选:Playwright,用于动态 URL 抓取(SPA 渲染);当
fetch.strategy为playwright或screenshot.enabled为 true 时,它会成为阻断检查 - 可选:LibreOffice,用于 PPTX 幻灯片渲染(macOS 上未安装时会回退到已装的 Microsoft PowerPoint)
- LLM API:配置和模型状态
- Vision Model:用于图像分析(从 litellm 自动检测)
- 本地 Provider 认证:Claude Agent、GitHub Copilot 和 ChatGPT 的认证状态(如果已配置)
普通 doctor 每次发现 Chromium 文件存在时,都会执行隔离且有超时限制的 headless 启动测试,因此过期 marker 或缺少 Linux 系统库不会得到绿灯。doctor --fix 不会向当前项目添加 Python 包。Playwright 包存在但 Chromium 缺失或不可用时,它会使用 Markitai 自身的解释器安装 Chromium,并重新执行运行时检查。启动失败仍会以非零状态退出;Linux 下会附上 playwright install-deps chromium 修复命令。如果 Playwright 包本身缺失,命令会安全退出,并提示使用 uv tool install 'markitai[browser]' --force 或对应的 pipx 命令替换隔离安装。
--json 与 --fix 不能同时使用:JSON 是只读的健康状态快照,修复则是面向人的交互操作。
输出示例:
◆ 系统检查
• 配置文件:~/.markitai/config.json
可选能力
⚠ RapidOCR: not installed — --ocr unavailable (everything else works)
⚠ Playwright: Playwright not installed
⚠ LibreOffice: Not installed
LLM
✓ LLM API: 1 active model(s) configured
✓ Vision Model: 1 detected: copilot/claude-haiku-4.5
✓ GitHub Copilot SDK: SDK + CLI installed
认证状态
✓ Copilot Auth: Authenticated
⚠ 核心检查通过(3 项必需或已配置检查通过,3 项非阻断警告)TIP
LLM 分组中的部分提供商和模型消息仍会显示为英文;分组标题、修复提示和总结行已经本地化。LLM API 行里的 API provider(s): ... 仅在启用了真正的远程 API 模型(非 claude-agent/、copilot/ 或 chatgpt/)时才会出现。doctor 会解析活跃 API 模型中显式的 env: 引用;缺失变量会作为已配置失败,而不是只按模型数量显示绿灯。
TIP
当使用本地 provider(claude-agent/ 或 copilot/)时,doctor 命令还会检查认证状态,如果认证失败会提供解决方案提示。
认证命令
markitai auth
本地提供商(Copilot、Claude、ChatGPT)的认证辅助工具。Gemini 通过直接 API Key 或 OpenRouter 访问(见配置说明),不通过此命令管理。不带子命令运行时,会显示三个 provider 各自登录状态的一览。
markitai auth # 查看所有 provider 概览markitai auth copilot status
显示 GitHub Copilot CLI 认证状态。
markitai auth copilot status
markitai auth copilot status --json # JSON 输出markitai auth copilot login
运行 GitHub Copilot CLI 认证。
markitai auth copilot loginmarkitai auth claude status
显示 Claude Code CLI 认证状态。
markitai auth claude status
markitai auth claude status --json # JSON 输出markitai auth claude login
运行 Claude Code CLI 认证。
markitai auth claude loginmarkitai auth chatgpt status
显示 ChatGPT OAuth 认证状态。
markitai auth chatgpt status
markitai auth chatgpt status --json # JSON 输出markitai auth chatgpt login
运行 ChatGPT OAuth Device Code Flow 认证。
markitai auth chatgpt loginTIP
也可以使用 markitai doctor 一次性检查所有已配置提供商的认证状态。
其他选项
--quiet, -q
隐藏进度和一般提示,错误仍写入 stderr。单次转换原本会输出到 stdout 的 Markdown 在 --quiet 下仍会保留;静默模式不会把实际结果变成空输出。当远程服务可能收到公网 URL 时,一次性的隐私揭露也会刻意保留在 stderr。
markitai document.docx --quiet-v, --verbose
启用详细输出。
markitai document.docx --verbose--dry-run
预览转换,不写入文件。
markitai document.docx --dry-run-c, --config <path>
指定配置文件路径。
markitai document.docx --config ./my-config.json--config-json <json>
内联 JSON 配置覆盖,与配置文件深度合并(显式 CLI 参数仍然优先)。适合 agent/CI 场景。
markitai document.docx --config-json '{"llm": {"concurrency": 4}}'-V, --version
显示版本信息。
markitai -V-h, --help
显示帮助信息。
markitai -h
markitai config -h
markitai cache -h