命令行工具

免费的 marsdawn 命令行工具：从终端或 LLM 代理把 Markdown 导出成 PDF；装了 MarsDawn app 的话，也能用它打开文件。

marsdawn 免费、另外发布，不通过 Mac App Store。用 Homebrew 安装，在 Apple 芯片的 Mac 上装好就能直接使用。export 可以单独使用；open 需要 MarsDawn app。

要从 AI 代理或脚本调用 marsdawn？请看给 AI 代理的 marsdawn 参考，里面有 JSON 输出、Schema 和所有退出代码。

安装

brew tap redtear1115/tap && brew install marsdawn

在用写程序的代理吗？执行 marsdawn skill --install 来加上 marsdawn skill：一个文件，教它把自己写的文稿在 MarsDawn 里打开给你审阅，也能导出 PDF。

在 Apple 芯片的 Mac 上，Homebrew 会直接安装预先构建好的版本，几秒就完成，不需要另外安装任何东西。在 Intel Mac 上则会从源代码构建，需要几分钟，也需要 Xcode 26 以上（Swift 6.2）。这个工具需要 macOS 15 以上。

也可以从源代码用 Swift Package Manager 构建：

git clone https://github.com/redtear1115/mars-dawn-kit.git
cd mars-dawn-kit
swift build -c release --product marsdawn

用 marsdawn --version 查看安装的版本。

命令

marsdawn open

在 MarsDawn app 中打开一个或多个 Markdown 文件，方便审阅。需要先安装这个 app：没有安装时，marsdawn open 会以代码 3 结束，并说明没有安装 MarsDawn。export 不需要这个 app。App 已在 Mac App Store 上架。

marsdawn open notes.md
marsdawn open notes.md:120
marsdawn open notes.md --line 120
marsdawn open .
marsdawn open notes.md --folder .

path:line：请 MarsDawn 定位到那一行。后面再接列号，例如 notes.md:120:8，会被忽略。如果有文件的完整名称就是这个参数，则视为那个文件。
--line <n>：同样的功能，只用于单一文件，也可以用在文件名本身以冒号加数字结尾的情况。只能搭配一个文件。
行号范围是 1 到 999999999。
MarsDawn 1.0 会打开文件，并跳到指定的行。
文件夹参数会在窗口的侧边栏打开，而不是当成文稿：marsdawn open . 会显示当前的文件夹。--folder <path> 可以在打开文件的同时做到一样的事。一个窗口的侧边栏只显示一个文件夹，所以指定两个是使用方式错误。
--wait <n>：搭配会回报结果的 MarsDawn 1.0.2 或更高版本，--folder 最多等待 n 秒（0 到 30，默认 2），等 app 回报文件夹的结果。--wait 0，或 app 不会回报时，不会等待，发出的请求和以前完全相同。
--wait 的值超出 0 到 30 是使用方式错误（代码 64）。负数要写成 --wait=-1。
加上 --json 时，文件夹报告的是「已请求」，而不是「已附加」，因为由 app 决定；加上 --wait 时，结果还会说明文件夹后来怎么样了。完整列表见给 AI 代理的 marsdawn 参考。
--background：打开时不把 MarsDawn 带到最前面。
--json：输出 JSON 结果，而不是文本。

行号功能从 marsdawn 0.3.0 开始提供，文件夹与 --background 从 0.5.1 开始，--wait 与文件夹状态从 0.5.3 开始。

marsdawn export

把 Markdown 文件导出成分页的 PDF，使用和 MarsDawn 导出 PDF 相同的组件。不需要安装 MarsDawn app。相对路径的图片，会以输入文件所在的文件夹为准。

marsdawn export notes.md -o notes.pdf --theme classic --paper a4

-o, --output <path>：PDF 的输出位置，默认是把输入文件的扩展名换成 .pdf。
--theme <dawn|classic|modern|vivid>：预览主题的浅色版本，默认读取 $MARSDAWN_THEME，否则用 dawn。
--paper <a4|letter>：纸张大小，默认 a4。
--breaks：段落内的每个换行都当作换行，和 HackMD 一样。不加时，两个中文或日文字符之间的换行会去掉，让前后两行连成一句。
--layout <document|handbook>：页面布局，默认 document。handbook 会导出成手册：页边距更宽并留出装订边，每个一级标题从新的一页开始，附带有页码的目录页、页脚页码和 PDF 书签；front matter 有 title 时，还会加上封面。
--toc-title <text>：手册目录页的标题，默认 Contents。
单独一行的  会从新的一页开始，两种布局都适用。
--allow-remote-images：导出时加载网络图片，默认关闭。
--force：如果输出文件已存在就直接覆盖。
--json：输出 JSON 结果，而不是文本。
超过 16 MiB 的文件不会导出：export 以代码 5 结束，不写出任何文件。

--breaks 从 marsdawn 0.7.0 开始提供，--layout 和 --toc-title 从 0.7.1 开始，handbook 这个值从 0.7.2 开始。0.7.1 的旧值 manual 仍可使用。

marsdawn theme

在分享主题文件（theme.json）之前，先检查它，看看它的样子。不需要 MarsDawn app。主题有哪些字段，请见和你的代理一起做主题。

marsdawn theme validate my-theme.json
marsdawn theme css my-theme.json
marsdawn theme preview my-theme.json --appearance dark -o preview.png

validate <file>：用 app 采用的同一个验证器，检查文件是否符合 MarsDawn 主题的每条规则。主题有效时以代码 0 结束，无效时以代码 1 结束，并列出每个问题。加上 --require-complete 时，还会要求语法高亮和图表的颜色，公开发布的主题都必须有这些。
css <file>：输出预览为有效主题使用的 CSS。
preview <file> --appearance <light|dark> -o <out.png>：用这个主题把一份示例文稿渲染成 PNG。--width 设置宽度（像素），范围 600 到 2000，默认 1200。文件已存在时，要加上 --force 才会替换。
--json：输出 JSON 结果，而不是文本。

theme 命令从 marsdawn 0.6.1 开始提供。

$MARSDAWN_THEME 环境变量

没有传入 --theme 时，export 会读取 $MARSDAWN_THEME 环境变量，值必须是 dawn、classic、modern 或 vivid 其中之一，其他值都会改用 dawn。这个工具不会读取 App 本身的主题设置，因为读取其他 App 的容器可能触发 macOS 隐私提示。

覆盖文件的规则

export 默认不会覆盖已存在的输出文件，除非加上 --force。

退出代码

代码	意思	怎么处理
`0`	成功。	加了 `--json` 时，读 stdout 上的那一行 JSON
`2`	找不到输入文件。	检查路径和文件名
`3`	尚未安装 MarsDawn（只有 `open` 会用到）。	安装 app，或改用不需要 app 的 `export`
`4`	输出文件已存在（可加上 `--force`）。	加上 `--force` 覆盖，或用 `-o` 写到别处
`5`	导出失败。	读 JSON 结果里的 `message`
`6`	这个版本的 MarsDawn 还不能显示文件夹，所以没有打开任何东西（只有 `open` 会用到）。
`64`	使用方式错误，包括行号超出范围、`--line` 搭配了多个文件或文件夹，或指定了多个文件夹。	修正选项或值；这种错误以文本输出到 stderr，即使加了 `--json` 也一样

--json 输出

成功时，marsdawn open --json 会输出 ok、opened（每个文件的 path，有指定行号时另含 line）、app（App 路径），有文件夹时另含 folder；marsdawn export --json 会输出 ok、output、pages、theme、paper 与 diagramErrors。失败时两者都会输出 ok、error 与 message。