命令列工具

免費的 marsdawn 命令列工具：從終端機或 LLM agent 把 Markdown 匯出成 PDF；裝了 MarsDawn app 的話，也能用它開啟檔案。

marsdawn 免費、另外發佈，不透過 Mac App Store。用 Homebrew 安裝，在 Apple 晶片的 Mac 上裝好就能直接使用。export 可以單獨使用；open 需要 MarsDawn app。

要從 AI agent 或腳本呼叫 marsdawn？請看給 AI agent 的 marsdawn 參考，裡面有 JSON 輸出、Schema 和所有離開代碼；如果你的 agent 是透過 MCP 呼叫工具，也可以看MCP 伺服器。

安裝

brew tap redtear1115/tap && brew install marsdawn

在用寫程式的 agent 嗎？執行 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 agent 的 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。主題有哪些欄位，請見和你的 agent 一起做主題。

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。