# exporter 命令列

從終端機、cron、備份工具和 AI 代理執行你的匯出。

`exporter` 就是不開視窗執行的 Exporter Mac App。它使用你在 App 中設定的相同連接、匯出資料夾、選取範圍和設定，並寫入相同的匯出記錄。App 關閉時它也能運作，而且從不跳出提示：缺少任何東西時，執行會以結束代碼 2 停止，並以一行文字說明該怎麼做。僅限 macOS。

## 安裝

1. 從 Mac App Store 安裝 Exporter（[下載](https://exporter.dev/download)）並打開它。
2. 連接一個 App（Apple 備忘錄、Bear、Logseq、聯絡人、訊息或螢幕使用時間）或一個文件資料夾，並選擇它的匯出資料夾（[入門](https://exporter.dev/docs/getting-started)）。這些授權只能在 App 中完成。
3. 在 App 的命令列卡片上按「複製安裝指令」，然後在終端機中貼上一次。

App 在沙盒中執行，無法寫入你的 PATH，所以最後一步需要貼上。當 `/opt/homebrew/bin` 存在且屬於你時，這一行會把 `exporter` 安裝到那裡（不需要 sudo），否則會以 sudo 安裝到 `/usr/local/bin`。再貼一次也沒關係，它會取代原本的內容。`exporter help install` 會印出適用於你 Mac 的那一行。

## 來源

`--source` 接受下列其中一個：

| 來源 | 也接受 | 寫出 |
| --- | --- | --- |
| `apple` | `apple-notes`、`applenotes`、`notes` | markdown 或 html |
| `bear` | | markdown 或 html |
| `logseq` | | 一律 markdown |
| `contacts` | `apple-contacts`、`addressbook` | 一律 markdown |
| `messages` | `imessage`、`chats`、`conversations` | 一律 markdown |
| `screentime` | `screen-time`、`usage` | 一律 markdown，每天一個檔案 |
| `documents` | `docs`、`files`、`pdf` | 文件卡片上勾選的格式 |

## 格式

`--format` 接受 `markdown`（或 `md`）或 `html`，不分大小寫。其他任何值都會以 `error: --format pdf: expected markdown | html` 停止，結束代碼為 64。

- 沒有指定時，`sync` 會以各 App 卡片上設定的格式寫出（Apple 備忘錄和 Bear 各有自己的設定），`export` 則以它匯出的那個 App 的設定寫出；`exporter help sync` 和 `exporter help export` 會顯示目前的設定
- Logseq、聯絡人、訊息和螢幕使用時間一律是 markdown，文件則寫出它卡片上勾選的格式，所以對它們而言 `--format html` 會被忽略，並附上提示：`note: logseq export is always markdown, so --format is ignored for this source.`
- Apple 備忘錄會為每則備忘錄寫出一個 `.html` 網頁（[HTML 格式](https://exporter.dev/docs/notes#markdown-and-html)），附件拷貝到它旁邊的 `attachments/` 並加上連結，沒有 front matter。Bear 的 HTML 是把筆記的純文字放進 `<pre>`，沒有任何樣式，附件參照也仍是 Markdown 文字：檔案會被拷貝，但不會被連結
- MCP 伺服器只讀取 markdown 檔案，所以只有 HTML 的匯出對它來說是看不見的
- Apple 備忘錄和 Bear 每次執行只寫出一種格式；只有文件能在一次同步中同時寫出兩種。每次執行只會移除它自己格式的舊檔案，所以切換格式後，另一種格式的檔案會留在資料夾中。如果兩種格式都要，請讓每種格式各用自己的資料夾：

```sh
exporter export --dest ~/Backups/notes-md   --format markdown
exporter export --dest ~/Backups/notes-html --format html
```

## sync

依照你在 App 中的設定，以增量方式執行一次匯出，寫入 App 的匯出資料夾。

```sh
exporter sync [--source <source>]... [--format markdown|html] [--full] [--json] [--quiet]
```

| 旗標 | 作用 | 預設值 |
| --- | --- | --- |
| `--source <source>` | 只處理這個 App，可重複指定 | 所有已連接的 App；未連接的會略過 |
| `--format markdown\|html` | 只套用於這次執行，你的 App 設定不變。它會寫進與另一種格式相同的匯出資料夾；如果兩種都要保留，請用 `export --dest` 各自匯出到自己的資料夾 | 你的 App 設定 |
| `--full` | 重新匯出所有內容。寫入前只會移除 Exporter 寫出的檔案；匯出資料夾中的其他內容都會保留 | 關閉 |
| `--json` | 機器可讀的摘要 | 關閉 |
| `--quiet`、`-q` | 只顯示錯誤 | 關閉 |

```sh
exporter sync --source apple
```

```text
apple notes: exporting…
apple notes: 1204 of 1204 exported · 3 removed · 18.2s · markdown → /Users/me/Documents/notes
```

摘要行的格式是 `<source>: <succeeded> of <selected> exported`，接著視情況加上 `N failed`、`N removed`（已刪除、重新命名或移動的項目所對應的檔案）、`N attachment issues`，然後是耗時、格式和寫入的資料夾。

如果 App 正在執行，`sync` 不會匯出任何東西，以 0 結束並印出 `Exporter is running: real-time sync is live, the export root is already current.`

## export

單次匯出到你選擇的資料夾，適合快照和腳本。App 開著時也能正常執行。

```sh
exporter export --dest <folder> [--source <source>] [--format markdown|html] [--organize folders|tags|smart] [--folder "Name"]... [--tag name]... [--dry-run] [--json] [--quiet]
```

| 旗標 | 作用 | 預設值 |
| --- | --- | --- |
| `--dest <folder>` | 必填。必須位於在 App 命令列卡片上（「加入資料夾」）授權的資料夾內。授權 `~/Backups` 就涵蓋它底下的每個資料夾 | 無 |
| `--source <source>` | 要匯出的 App | `apple` |
| `--format markdown\|html` | 這次執行使用的格式 | 你的 App 設定 |
| `--organize folders\|tags\|smart` | 僅限 Apple 備忘錄：備忘錄在資料夾中的排列方式 | 你的 App 設定 |
| `--folder "Name"` | 只匯出這個 Apple 備忘錄資料夾，可重複指定，名稱比對不分大小寫 | App 中儲存的選取範圍 |
| `--tag name` | 只匯出這個標籤，可重複指定，適用 Apple 備忘錄或 Bear | App 中儲存的選取範圍 |
| `--dry-run` | 印出將會匯出的內容，不寫入任何東西 | 關閉 |
| `--json`、`--quiet`（`-q`） | 與 sync 相同 | 關閉 |

沒有 `--folder` 或 `--tag` 時，Apple 備忘錄和 Bear 會匯出 App 中儲存的選取範圍。Logseq 匯出整個圖譜，聯絡人匯出每張卡片，訊息匯出每個對話，螢幕使用時間匯出每一天；篩選條件對它們無效，並會附上提示。

```sh
exporter export --dest ~/Backups/notes-$(date +%F)
exporter export --dest ~/Backups/work --folder "Work" --format html
exporter export --dest ~/Backups/bear --source bear --tag journal
exporter export --dest ~/Backups/people --source contacts
exporter export --dest ~/Backups/papers --source documents
exporter export --dest ~/Backups/notes --dry-run
```

```text
would export 100 apple notes · markdown → /Users/me/Backups/notes
```

## list

```sh
exporter list sources|folders|tags|dests [--source apple|bear] [--json]
```

| 清單 | 顯示內容 | JSON |
| --- | --- | --- |
| `sources` | 每個 App，無論是否已連接，以及它的數量。文件不會列出 | `[{"source": "apple", "connected": true, "notes": 1204}, {"source": "messages", "connected": true, "conversations": 1532}, {"source": "bear", "connected": false}]`，logseq 用 `pages`，另有 `contacts`，`screen-time` 用 `days` |
| `folders` | Apple 備忘錄資料夾及備忘錄數量，依層級縮排。`--source bear` 會出錯（結束代碼 64） | `[{"name": "Work", "notes": 42, "level": 0}]` |
| `tags` | 標籤及數量，預設為 Apple 備忘錄，加上 `--source bear` 則為 Bear | `[{"name": "journal", "notes": 12}]` |
| `dests` | `export --dest` 可寫入的資料夾，以及每個 App 的匯出資料夾 | `[{"path": "/Users/me/Backups", "kind": "granted"}]`，其中 `kind` 為 `granted`、`granted, volume not mounted` 或 `export root (apple-notes)` |

```sh
exporter list folders --json
```

```json
[{"name": "Work", "notes": 42, "level": 0}]
```

## status

```sh
exporter status [--json]
```

```text
apple notes    connected · last export 2026-09-11 03:00
bear           not connected
logseq         not connected
contacts       not connected
messages       connected · last export 2026-09-11 03:01
screen time    not connected
documents      not connected
root (apple-notes)  /Users/me/Documents/notes
root (messages)  /Users/me/Documents/messages
destinations   /Users/me/Backups
version        3.24 · free · 100 of 100 free notes used
messages       free · 10 of 10 free conversations used
app            not running
```

加上 `--json` 時：每個 App 一個物件，名稱為 `apple-notes`、`bear`、`logseq`、`contacts`、`messages`、`screen-time`、`documents`，每個都是 `{"connected": true, "lastExport": "2026-09-11 03:00"}`（從未匯出時為 `null`）；`destinations`（路徑）；`tier`（`full` 或 `free`，即 Apple 備忘錄的解鎖狀態）和 `freeNotesUsed`；`contactsTier` 和 `freeContactsUsed`；`messagesTier` 和 `freeConversationsUsed`；`screenTimeTier` 和 `freeDaysUsed`；`appRunning`。時間為當地時間，格式 `yyyy-MM-dd HH:mm`。

## log

最近的匯出執行，最新的在前：與 App 顯示的記錄相同，來自每個匯出資料夾和已授權的 `--dest` 資料夾。在已授權資料夾下建立的日期資料夾不會被讀取；它們的記錄在 `<folder>/.exporter/` 中。

```sh
exporter log [--last N] [--json]
```

| 旗標 | 作用 | 預設值 |
| --- | --- | --- |
| `--last N` | 顯示幾次執行 | 10 |
| `--json` | 每次執行一個物件 | 關閉 |

```text
2026-09-11 03:00  apple-notes   1204/1204 exported  3 removed  clean  → /Users/me/Documents/notes
```

JSON：`[{"source", "finishedAt", "selected", "succeeded", "failed", "format", "status", "destination", "prunedFiles", "runError"}]`。`status` 為 `clean`、`warnings`（缺少附件）或 `failures`。

## doctor

檢查無視窗匯出是否能正常運作，每項檢查印出一行：`ok`、下方附 `fix:` 行的 `FAIL`、`warn`，或表示資訊的 `--`。

```sh
exporter doctor
```

它會檢查每個已連接 App 的資料庫是否可讀取、匯出資料夾是否可寫入，每個儲存的資料夾授權是否有效，每個 `--dest` 資料夾是否可寫入，還有索引和已安裝的指令。最後會顯示版本等級、App 是否正在執行，以及最近一次當機（如果有的話）。結束代碼 0 會印出 `all good.`，結束代碼 2 會印出 `N problem(s) found.`

## report

印出一份診斷報告（App 版本、macOS 和硬體、連接狀態、最近的執行、最近一次當機；不含備忘錄內容），並拷貝到剪貼板。

```sh
exporter report [--send] [--email <addr>]
```

| 旗標 | 作用 | 預設值 |
| --- | --- | --- |
| `--send` | 將報告傳送給我們並印出 `sent.`，或 `offline: queued, will send on the next run or app launch.` | 關閉 |
| `--email <addr>` | 附上你的地址，方便我們回覆 | 無 |

## help 和 version

- `exporter help [topic]`：主題有 `sync`、`export`、`list`、`status`、`log`、`doctor`、`report`、`cron`、`install`。指令的說明會以你目前的設定作為預設值顯示
- `sync`、`export`、`list`、`log` 和 `report` 也接受 `--help` 或 `-h`
- `exporter version`（或 `--version`、`-v`）會印出 `exporter 3.24`
- 在終端機中單獨輸入 `exporter` 會印出概覽，並以 64 結束

## JSON 輸出

`--json` 適用於 `sync`、`export`、`list`、`status` 和 `log`。輸出經過排版，鍵依字母排序。`sync` 和 `export` 請加上 `--quiet`：不加的話，進度和備忘錄的行會在 JSON 之前印到 stdout。`export` 印出一個摘要物件，`sync` 印出 `{"runs": [...]}`，每個來源一個：

```json
{
  "attachmentIssues" : 0,
  "durationSec" : 18.2,
  "failed" : 0,
  "format" : "markdown",
  "root" : "/Users/me/Documents/notes",
  "runError" : null,
  "selected" : 1204,
  "source" : "apple-notes",
  "status" : "clean",
  "succeeded" : 1204
}
```

App 正在執行時，`sync` 只印出那一行，不會輸出 JSON。錯誤會以 `error: <what happened and what to do>` 的形式輸出到 stderr。

## 結束代碼

| 代碼 | 意義 |
| --- | --- |
| 0 | 正常，包括因免費額度而提前結束的執行 |
| 1 | 匯出失敗：有項目失敗、執行時發生錯誤，或選取了項目卻一個也沒寫出 |
| 2 | 需要設定：App 未連接、資料夾未授權、找不到資料夾或標籤、沒有東西可匯出；`doctor` 發現問題；已安裝的指令是舊格式，或它指向的 App 已不存在 |
| 64 | 用法錯誤：未知的指令或旗標、缺少或錯誤的值、Bear 搭配 `--folder`、`list folders --source bear`、在終端機中單獨輸入 `exporter` |

## 檔案存放的位置

`sync` 寫入在 Exporter 中為每個 App 設定的匯出資料夾，例如 `~/Documents/notes` 或 `~/Documents/messages`；`export` 寫入 `--dest`。位於個人專屬資料夾這一層或下一層的資料夾，例如 `~/Documents` 本身，會多一個各 App 專屬的子資料夾（`notes-export`、`messages-export` 等），更深層的資料夾則直接使用。摘要行（箭頭之後）和 JSON 的 `root` 會顯示實際的資料夾。

每個匯出資料夾都有 `.exporter/last-export.json` 和 `.exporter/last-export.md`（最近一次執行），以及 `.exporter/history/`（最近 50 次執行）。Apple 備忘錄、聯絡人、訊息、螢幕使用時間和文件另外還保留 `.exporter/files.json`，也就是每次執行寫出的每個檔案：下一次執行只會移除列在其中、且已沒有任何項目產生的檔案（螢幕使用時間從不移除每日檔案）。Bear 和 Logseq 也會在下一次執行時，移除你刪除、重新命名或更改標籤的筆記所對應的檔案。Apple 備忘錄和 Logseq 的匯出另外還有含 Obsidian 檢視的 `bases/`。

## 免費額度

命令列的額度與 App 相同：

| App | 免費 |
| --- | --- |
| Apple 備忘錄 | 100 則備忘錄 |
| 聯絡人 | 100 位聯絡人 |
| 訊息 | 最近 10 個對話 |
| 螢幕使用時間 | 首次同步時最近的 10 天，而且只有這些：之後的日子需要解鎖 |
| 文件 | 最近修改的 10 個文件 |
| Bear 和 Logseq | 不限數量 |

已匯出的項目都能持續免費重新同步；免費額度只會擋下新的項目。達到額度的執行仍會匯出它能匯出的內容，以 0 結束，並印出提示（`--quiet` 時不會印出）：

```text
note: 42 note(s) skipped: free version limit (100 of 100 free notes). upgrade in the app to export everything.
note: 58 contact(s) skipped: free version limit (100 of 100 free contacts). unlock contacts in the app to export everything.
note: 1522 conversation(s) skipped: free version limit (10 of 10 free conversations). unlock messages in the app to export everything.
note: 11 day(s) skipped: free version limit (10 of 10 free days). unlock screen time in the app to archive every day.
note: 5 document(s) skipped: free version limit (10 of 10 free documents). unlock documents in the app to convert every one.
```

`status --json` 會列出 Apple 備忘錄、聯絡人、訊息和螢幕使用時間的版本等級和已使用數量。每個有額度的 App 都能在 Exporter 內各自以一次性 App 內購買解鎖，[價格依國家或地區而定](https://exporter.dev/pricing)，沒有訂閱，也沒有網路結帳。命令列每次執行都會讀取購買狀態；如果 App Store 在 5 秒內沒有回應，執行會以免費額度繼續。

## 排程

`exporter help cron` 會印出下列幾行，並附上指令在你 Mac 上的完整路徑：請使用那個路徑，因為 cron 的 PATH 可能不包含安裝資料夾。在 crontab 中，`%` 要跳脫成 `\%`：

```sh
0 3 * * * exporter sync
0 3 * * * exporter export --dest ~/Backups/notes-$(date +\%F)
```

若使用 Carbon Copy Cloner 和其他備份工具，請將 `exporter sync` 設為執行前腳本，並依結束代碼分支處理。整個匯出期間指令都會保持連線，即使沒有人登入、macOS 將它暫停也一樣。只要 App 在執行，無論視窗是否打開，`sync` 都不會做任何事：即時同步已經讓資料夾保持最新。

## MCP 伺服器

執行本機 MCP 伺服器的是 App，而不是命令列；它讓 Claude、Cursor、VS Code 和其他用戶端能在 `http://localhost:8744/mcp` 搜尋和讀取你的匯出內容。[MCP 伺服器頁面](https://exporter.dev/docs/mcp)涵蓋它的所有內容，從啟動方式到它的六個工具。

## 疑難排解

先執行 `exporter doctor`；每個失敗的檢查都會印出修正方式。[說明](https://exporter.dev/docs/help)也涵蓋 App 顯示的訊息。

- `X is not authorized`：在命令列卡片上加入該資料夾（或它的上層資料夾），然後重新執行。`exporter list dests` 會顯示已授權的項目
- `apple notes is not set up. open Exporter and connect Apple Notes + an export folder.`（每個 App 都一樣）：在 Exporter 中連接它
- `sync` 印出 Exporter 正在執行：不需要做任何事，App 會讓資料夾保持最新。如果要另一份拷貝，請使用 `export --dest`
- `no notes were written. run "exporter doctor" to check folders and permissions.`：這次執行選取了備忘錄，卻一個也沒寫出；`doctor` 會檢查資料夾和權限
- `bookmark broken`：資料夾已被移動、刪除，或它所在的磁碟區未掛載。請在 App 中重新選擇
- 已安裝的指令是舊格式，或 cron 和備份工具看到結束代碼 19：再貼一次安裝指令
- 安裝指令之後 App 被移動了：再貼一次安裝指令
- 已解鎖但執行時顯示免費版：購買檢查最多等待 5 秒，之後以免費額度繼續。請再執行一次
- doctor 無法說明的問題：`exporter report --send --email you@example.com`

## Related

- [MCP server](https://exporter.dev/docs/mcp): Connect Claude and other agents
- [For agents](https://exporter.dev/agents): Skills, command line and MCP for agents
- [Apple Notes](https://exporter.dev/docs/notes): Folders, fields, HTML and fixes
- [Changelog](https://exporter.dev/changelog): What changed in each version

---

human version: https://exporter.dev/zh-hant/docs/cli
every page: https://exporter.dev/llms.txt