# exporter 命令行

从终端、cron、备份工具和智能体运行你的导出。

`exporter` 就是不带窗口运行的 Exporter Mac 应用。它使用你在应用中设置好的同样的连接、导出文件夹、选择和设置，并写入同一个导出日志。应用关闭时它也能工作，而且从不弹出提示：缺少任何东西时，运行会以退出码 2 停止，并用一行文字说明该怎么做。仅限 macOS。

## 安装

1. 从 Mac App Store 安装 Exporter（[下载](https://exporter.dev/download)）并打开它。
2. 连接一个应用（Apple 备忘录、Bear、Logseq、通讯录、信息或屏幕使用时间）或一个文档文件夹，并选择它的导出文件夹（[入门](https://exporter.dev/docs/getting-started)）。这些授权只能在应用中完成。
3. 在应用的命令行卡片上点按“复制安装命令”，然后在终端中粘贴一次。

应用运行在沙盒中，无法写入你的 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` 按每个应用卡片上设置的格式写出（Apple 备忘录和 Bear 各有自己的设置），`export` 按它所导出的应用的设置写出；`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

运行你在应用中配置的导出，执行一次、增量进行，写入应用的导出文件夹。

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

| 选项 | 作用 | 默认值 |
| --- | --- | --- |
| `--source <source>` | 只处理这个应用，可重复 | 所有已连接的应用；未连接的会被跳过 |
| `--format markdown\|html` | 仅用于本次运行，你在应用中的设置不变。它会写入与另一种格式相同的导出文件夹；如果两种都要保留，请用 `export --dest` 把它们分别导出到各自的文件夹 | 你在应用中的设置 |
| `--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`，接着是耗时、格式和写入的文件夹。

如果应用正在运行，`sync` 不导出任何内容，以 0 退出，并打印 `Exporter is running: real-time sync is live, the export root is already current.`

## export

一次性导出到你选择的文件夹，适合快照和脚本。应用打开时也能正常运行。

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

| 选项 | 作用 | 默认值 |
| --- | --- | --- |
| `--dest <folder>` | 必填。必须位于在应用命令行卡片上授权过的文件夹内（“添加文件夹”）。对 `~/Backups` 的授权涵盖其下的所有文件夹 | 无 |
| `--source <source>` | 要导出的应用 | `apple` |
| `--format markdown\|html` | 本次运行使用的格式 | 你在应用中的设置 |
| `--organize folders\|tags\|smart` | 仅限 Apple 备忘录：备忘录如何按文件夹排列 | 你在应用中的设置 |
| `--folder "Name"` | 只导出这个 Apple 备忘录文件夹，可重复，名称匹配不区分大小写 | 应用中保存的选择 |
| `--tag name` | 只导出这个标签，可重复，适用于 Apple 备忘录或 Bear | 应用中保存的选择 |
| `--dry-run` | 打印将要导出的内容，不写入任何东西 | 关闭 |
| `--json`、`--quiet`（`-q`） | 与 sync 相同 | 关闭 |

不带 `--folder` 或 `--tag` 时，Apple 备忘录和 Bear 导出应用中保存的选择。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` | 每个应用，无论是否已连接，以及它的数量。文档不会列出 | `[{"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` 可以写入的文件夹，以及每个应用的导出文件夹 | `[{"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` 时：每个应用一个对象，名称为 `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

最近的导出运行，最新的在前：与应用中显示的是同一个日志，来自每个导出文件夹和已授权的 `--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`、`FAIL`（下方附一行 `fix:`）、`warn`，或者表示信息的 `--`。

```sh
exporter doctor
```

它会检查每个已连接应用的数据库是否可读、导出文件夹是否可写，每个已保存的文件夹授权能否解析，每个 `--dest` 文件夹是否可写，还有索引和已安装的命令。最后会显示版本级别、应用是否在运行，以及上次崩溃（如果有的话）。退出码 0 时打印 `all good.`，退出码 2 时打印 `N problem(s) found.`

## report

打印一份诊断报告（应用版本、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
}
```

应用运行时，`sync` 只打印那一行，不输出 JSON。错误以 `error: <what happened and what to do>` 的形式输出到 stderr。

## 退出码

| 代码 | 含义 |
| --- | --- |
| 0 | 正常，包括因免费额度而提前结束的运行 |
| 1 | 导出失败：有条目导出失败、运行出错，或选中了条目却一个都没写出 |
| 2 | 需要设置：应用未连接、文件夹未授权、找不到文件夹或标签、没有可导出的内容；`doctor` 发现了问题；已安装的命令是旧格式，或者它指向的应用已不存在 |
| 64 | 用法错误：未知的命令或选项、缺少值或值无效、对 Bear 使用 `--folder`、`list folders --source bear`、在终端中单独运行 `exporter` |

## 文件存放在哪里

`sync` 写入在 Exporter 中为每个应用设置的导出文件夹，例如 `~/Documents/notes` 或 `~/Documents/messages`；`export` 写入 `--dest`。如果选择的是个人文件夹本身或它下一层的文件夹，比如 `~/Documents` 本身，会在其中为每个应用新建一个子文件夹（`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/`。

## 免费额度

命令行的免费额度与应用相同：

| 应用 | 免费 |
| --- | --- |
| Apple 备忘录 | 100 条备忘录 |
| 通讯录 | 100 位联系人 |
| 信息 | 最近 10 个对话 |
| 屏幕使用时间 | 首次同步时最近的 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 备忘录、通讯录、信息和屏幕使用时间的版本级别和已用数量。每个有额度限制的应用都通过 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 挂起也一样。只要应用在运行，无论窗口打开还是关闭，`sync` 都不会执行任何操作：实时同步已经让文件夹保持最新。

## MCP 服务器

运行本地 MCP 服务器的是应用，而不是命令行。它让 Claude、Cursor、VS Code 和其他客户端在 `http://localhost:8744/mcp` 搜索和读取你的导出。[MCP 服务器页面](https://exporter.dev/docs/mcp)介绍了它的全部内容，从启动它到它的六个工具。

## 故障排除

先运行 `exporter doctor`；每项未通过的检查都会打印修复方法。[帮助](https://exporter.dev/docs/help)也涵盖了应用中的提示信息。

- `X is not authorized`：在命令行卡片上添加该文件夹（或它的上级文件夹），然后重新运行。`exporter list dests` 会显示已授权的文件夹
- `apple notes is not set up. open Exporter and connect Apple Notes + an export folder.`（每个应用都一样）：在 Exporter 中连接它
- `sync` 打印出 Exporter 正在运行：无需任何操作，应用会让文件夹保持最新。如需单独的副本，请使用 `export --dest`
- `no notes were written. run "exporter doctor" to check folders and permissions.`：本次运行选中了备忘录却一个都没写出；`doctor` 会检查文件夹和权限
- `bookmark broken`：文件夹被移动、删除，或者它所在的卷未装载。请在应用中重新选择它
- 已安装的命令是旧格式，或者 cron 和备份工具收到退出码 19：再粘贴一次安装命令
- 安装命令后应用的位置变了：再粘贴一次安装命令
- 已经解锁，但运行时显示免费版：购买检查最多等待 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-hans/docs/cli
every page: https://exporter.dev/llms.txt