命令行工具

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

安装

使用 Homebrew：

brew tap redtear1115/tap && brew install marsdawn

在 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。

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

• path:line：请 MarsDawn 定位到那一行。后面再接列号，例如 notes.md:120:8，会被忽略。如果有文件的完整名称就是这个参数，则视为那个文件。
• --line <n>：同样的功能，只用于单一文件，也可以用在文件名本身以冒号加数字结尾的情况。只能搭配一个文件。
• 行号范围是 1 到 999999999。
• MarsDawn 1.0 会打开文件，但还不会跳到指定的行。
• --json：输出 JSON 结果，而不是文本。

行号功能从 marsdawn 0.3.0 开始提供。

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。
• --allow-remote-images：输出时加载网络图片，默认关闭。
• --force：如果输出文件已存在就直接覆盖。
• --json：输出 JSON 结果，而不是文本。

$MARSDAWN_THEME 环境变量

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

覆盖文件的规则

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

退出代码

• 0：成功。
• 2：找不到输入文件。
• 3：尚未安装 MarsDawn（只有 open 会用到）。
• 4：输出文件已存在（可加上 --force）。
• 5：输出失败。
• 64：使用方式错误，包括行号超出范围，或 --line 搭配了多个文件。

--json 输出

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