The exporter command line

exporter is the Exporter Mac app run without a window. It uses the same connections, export folders, selection and settings you set up in the app, and it writes to the same export log. It works while the app is closed and it never prompts: anything missing stops the run with exit code 2 and one line saying what to do. macOS only.

Install

1. Install Exporter from the Mac App Store (download) and open it.
2. Connect an app (Apple Notes, Bear, Logseq, Contacts, Messages or Screen Time) or a Documents folder, and choose its export folder (getting started). These grants can only be made in the app.
3. On the app’s Command Line card, press “copy install command” and paste it once in Terminal.

The app is sandboxed and cannot write to your PATH, which is why the last step is a paste. The line installs exporter into /opt/homebrew/bin when that folder exists and belongs to you (no sudo), otherwise into /usr/local/bin with sudo. Pasting it again is safe; it replaces whatever was there. exporter help install prints the line for your Mac.

Sources

--source takes one of these:

source	also accepted	writes
apple	apple-notes, applenotes, notes	markdown or html
bear		markdown or html
logseq		always markdown
contacts	apple-contacts, addressbook	always markdown
messages	imessage, chats, conversations	always markdown
screentime	screen-time, usage	always markdown, one file per day
documents	docs, files, pdf	the formats ticked on the Documents card

Formats

--format takes markdown (or md) or html; case does not matter. Anything else stops with error: --format pdf: expected markdown | html and exit 64.

• without it, sync writes each app in the format set on its card (Apple Notes and Bear each have their own) and export writes the setting of the app it exports; exporter help sync and exporter help export show the current ones
• Logseq, Contacts, Messages and Screen Time are always markdown, and Documents writes the formats ticked on its card, so for them --format html is ignored with a note: note: logseq export is always markdown, so --format is ignored for this source.
• Apple Notes writes one .html page per note (the HTML format), attachments copied into attachments/ next to it and linked, no front matter. Bear’s HTML is the note’s plain text inside a <pre>, with no styling, and attachment references left as Markdown text: the files are copied, not linked
• the MCP server reads only markdown files, so an export that is only HTML is invisible to it
• Apple Notes and Bear write one format per run; only Documents writes both in one sync. A run removes only old files of its own format, so switching leaves the other format’s files in the folder. For both formats, give each its own folder:

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

sync

Runs the export you configured in the app, once, incrementally, into the app’s export folders.

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

flag	what it does	default
--source <source>	only this app, repeatable	every connected app; unconnected ones are skipped
--format markdown|html	this run only, your app setting is unchanged. It lands in the same export folder as the other format; to keep both, export each to its own folder with export --dest	your app setting
--full	re-export everything. It removes only the files Exporter wrote before writing; anything else in the export folder stays	off
--json	a machine-readable summary	off
--quiet, -q	errors only	off

exporter sync --source apple

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

The summary line is <source>: <succeeded> of <selected> exported, then when present N failed, N removed (files of items that were deleted, renamed or moved), N attachment issues, then the duration, the format and the folder written.

If the app is running, sync exports nothing, exits 0 and prints Exporter is running: real-time sync is live, the export root is already current.

export

A one-shot export to a folder of your choice, for snapshots and scripts. It runs fine while the app is open.

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

flag	what it does	default
--dest <folder>	required. Must be inside a folder granted on the app’s Command Line card (“add folder”). A grant on ~/Backups covers every folder below it	none
--source <source>	the app to export	apple
--format markdown|html	the format for this run	your app setting
--organize folders|tags|smart	Apple Notes only: how notes are laid out in folders	your app setting
--folder "Name"	only this Apple Notes folder, repeatable, name matched without case	the selection saved in the app
--tag name	only this tag, repeatable, Apple Notes or Bear	the selection saved in the app
--dry-run	print what would be exported, write nothing	off
--json, --quiet (-q)	as for sync	off

With no --folder or --tag, Apple Notes and Bear export the selection saved in the app. Logseq exports the whole graph, Contacts every card, Messages every conversation, Screen Time every day; filters are ignored for them with a note.

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

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

list

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

list	what it shows	JSON
sources	each app, connected or not, with its count. Documents is not listed	[{"source": "apple", "connected": true, "notes": 1204}, {"source": "messages", "connected": true, "conversations": 1532}, {"source": "bear", "connected": false}], with pages for logseq, contacts, and days for screen-time
folders	Apple Notes folders with note counts, indented by depth. --source bear is an error (exit 64)	[{"name": "Work", "notes": 42, "level": 0}]
tags	tags with counts, Apple Notes by default, Bear with --source bear	[{"name": "journal", "notes": 12}]
dests	folders export --dest may write to, plus each app’s export folder	[{"path": "/Users/me/Backups", "kind": "granted"}], where kind is granted, granted, volume not mounted or export root (apple-notes)

exporter list folders --json

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

status

exporter status [--json]

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

With --json: one object per app, named apple-notes, bear, logseq, contacts, messages, screen-time, documents, each {"connected": true, "lastExport": "2026-09-11 03:00"} (null when never exported); destinations (paths); tier (full or free, the Apple Notes unlock) and freeNotesUsed; contactsTier and freeContactsUsed; messagesTier and freeConversationsUsed; screenTimeTier and freeDaysUsed; appRunning. Times are local, yyyy-MM-dd HH:mm.

log

The recent export runs, newest first: the same log the app shows, from every export folder and granted --dest folder. Dated folders created under a granted folder are not read; their record is in <folder>/.exporter/.

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

flag	what it does	default
--last N	how many runs	10
--json	one object per run	off

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 is clean, warnings (attachments missing) or failures.

doctor

Checks that headless export will work and prints one line per check: ok, FAIL with a fix: line under it, warn, or -- for information.

exporter doctor

It checks that each connected app’s database is readable and its export folder writable, that every stored folder grant resolves, that every --dest folder is writable, the index, and the installed command. It ends with the version tier, whether the app is running, and the last crash if there was one. Exit 0 prints all good., exit 2 prints N problem(s) found.

report

Prints a diagnostic report (app version, macOS and hardware, connection state, recent runs, last crash; no note contents) and copies it to the clipboard.

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

flag	what it does	default
--send	submits the report to us and prints sent., or offline: queued, will send on the next run or app launch.	off
--email <addr>	adds your address so we can reply	none

help and version

• exporter help [topic]: topics sync, export, list, status, log, doctor, report, cron, install. Help for a command shows your current settings as the defaults
• sync, export, list, log and report also take --help or -h
• exporter version (or --version, -v) prints exporter 3.24
• exporter alone in a terminal prints the overview and exits 64

JSON output

--json works on sync, export, list, status and log. Output is pretty-printed with sorted keys. For sync and export add --quiet: without it the progress and note lines are printed on stdout before the JSON. export prints one summary object, sync prints {"runs": [...]} with one per source:

{
  "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
}

While the app is running, sync prints its one line and no JSON. Errors go to stderr as error: <what happened and what to do>.

Exit codes

code	meaning
0	ok, including a run the free allowance cut short
1	export failures: an item failed, the run hit an error, or it selected items and wrote none
2	needs setup: app not connected, folder not granted, folder or tag not found, nothing to export; doctor found problems; the installed command is an old format or the app it points at is gone
64	usage: unknown command or flag, missing or bad value, --folder with Bear, list folders --source bear, exporter alone in a terminal

Where files land

sync writes to the export folder set for each app in Exporter, like ~/Documents/notes or ~/Documents/messages; export writes to --dest. A folder at your home level or one below it, like ~/Documents itself, gets a per-app subfolder (notes-export, messages-export and so on), and a deeper folder is used as it is. The summary line (after the arrow) and the JSON root show the real folder.

Each export folder holds .exporter/last-export.json and .exporter/last-export.md (the last run) and .exporter/history/ (the last 50 runs). Apple Notes, Contacts, Messages, Screen Time and Documents also keep .exporter/files.json, every file a run wrote: the next run removes only files listed there that no item produces any more (Screen Time never removes a day file). Bear and Logseq also remove the files of notes you deleted, renamed or retagged on the next run. Apple Notes and Logseq exports also get bases/ with Obsidian views.

Free allowance

The command line has the same allowances as the app:

app	free
Apple Notes	100 notes
Contacts	100 contacts
Messages	the 10 most recent conversations
Screen Time	the 10 most recent days at the first sync, and only those: later days need the unlock
Documents	the 10 most recently modified documents
Bear and Logseq	unlimited

Items already exported keep re-syncing free; the allowance only stops new ones. A run that reaches it still exports what it may, exits 0, and prints a note (not under --quiet):

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 carries the tier and used count for Apple Notes, Contacts, Messages and Screen Time. Each limited app unlocks with its own one-time in-app purchase inside Exporter, priced per country, no subscription and no web checkout. The command line reads the purchase on every run; if the App Store does not answer within 5 seconds, the run continues on the free allowance.

Scheduling

exporter help cron prints these lines with the full path of the command on your Mac: use that, because cron’s PATH may not include the install folder. In a crontab, escape % as \%:

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

For Carbon Copy Cloner and other backup tools, run exporter sync as a pre-flight script and branch on the exit code. The command stays attached for the whole export, even when macOS suspends it with no one logged in. While the app is running, with its window open or closed, sync is a no-op: real-time sync already keeps the folder current.

MCP server

The app, not the command line, runs a local MCP server that lets Claude, Cursor, VS Code and other clients search and read your exports, at http://localhost:8744/mcp. The MCP server page covers everything about it, from starting it to its six tools.

Troubleshooting

Run exporter doctor first; every failing check prints its fix. Help covers the app’s messages too.

• X is not authorized: add the folder (or a parent) on the Command Line card, then re-run. exporter list dests shows what is granted
• apple notes is not set up. open Exporter and connect Apple Notes + an export folder. (the same for each app): connect it in Exporter
• sync prints that Exporter is running: nothing to do, the app keeps the folder current. Use export --dest for a separate copy
• no notes were written. run "exporter doctor" to check folders and permissions.: the run selected notes and wrote none; doctor checks the folders and permissions
• bookmark broken: the folder was moved, deleted, or its volume is not mounted. Choose it again in the app
• the installed command is an old format, or cron and backup tools see exit 19: paste the install command again
• the app moved since you installed the command: paste the install command again
• unlocked but the run says free: the purchase check waits at most 5 seconds, then continues on the free allowance. Run again
• a problem doctor cannot explain: exporter report --send --email you@example.com