feature: add export command that exports mails to markdown

README.md

@@ -248,6 +248,50 @@ If a worktree for that reference already exists it is replaced.
 
 ---
 
+### `export`
+
+Export the archive as Markdown files — one `.md` per message — with YAML frontmatter and a human-readable body.
+
+```sh
+backmail export
+backmail export --only-folder INBOX --only-folder Sent
+backmail export --exclude-folder Spam --verbose
+```
+
+| Option | Description |
+|--------|-------------|
+| `--exclude-folder <name>` | Skip a folder (repeatable) |
+| `--only-folder <name>` | Restrict to a folder (repeatable) |
+| `--verbose` | Log one line per folder and per message |
+
+`--exclude-folder` and `--only-folder` are mutually exclusive.
+
+Output is written to `export/` next to `archive/`, mirroring the folder structure. Each file contains:
+
+- YAML frontmatter with `messageId`, `from`, `to`, `subject`, `received`, `folders`, `formats`, and `attachments`
+- The subject as a top-level heading
+- Plain text body (when present)
+- HTML body converted to Markdown, preceded by a labelled separator block (when both parts are present — layout tables are unwrapped to prose, external images stripped, inline attachments preserved)
+
+Running `export` again is idempotent — existing files are overwritten with identical content.
+
+Output:
+
+```
+export: =42 exported
+```
+
+If any message fails the export continues and the summary line is tagged `[partial]`:
+
+```
+export [partial]: =38 exported
+folder INBOX/Archive failed: read error
+```
+
+Exit code is non-zero when any folder fails.
+
+---
+
 ### `restore`
 
 Re-upload messages from a backup to an IMAP server. Useful for migrating to a new provider or recovering deleted mail.
@@ -290,6 +334,9 @@ archive/            # git repository
 worktrees/          # point-in-time checkouts (outside the git repo)
   2024-01-15/
   abc1234/
+export/             # Markdown export (created by `backmail export`)
+  INBOX/
+    2024-01-15_subject_aabbccdd.md
 ```
 
 Messages are content-addressed by Message-ID, so identical emails that appear in multiple IMAP folders (common with Gmail labels) are stored only once.

package.json

@@ -48,6 +48,7 @@
   "devDependencies": {
     "@types/mailparser": "^3.4.6",
     "@types/node": "25.6.0",
+    "@types/turndown": "^5.0.6",
     "@vitest/coverage-v8": "^4.1.5",
     "tsx": "4.21.0",
     "typescript": "6.0.3",
@@ -63,6 +64,8 @@
     "mailparser": "^3.9.8",
     "simple-git": "3.36.0",
     "slugify": "^1.6.9",
+    "turndown": "^7.2.4",
+    "turndown-plugin-gfm": "^1.0.2",
     "zod": "^4.3.6"
   }
 }

src/cli/index.ts

@@ -39,7 +39,7 @@ function getRepoRoot(): string {
   return repoRoot
 }
 
-import { syncAccount, getLog, checkoutCommit, listFolders, listMessages, viewMessage, restoreAccount } from '../core/index.js'
+import { syncAccount, getLog, checkoutCommit, listFolders, listMessages, viewMessage, restoreAccount, exportAccount } from '../core/index.js'
 
 function getErrorMessage(err: unknown): string {
   if (err instanceof Error) {
@@ -373,4 +373,48 @@ program
     }
   })
 
+// ── export ───────────────────────────────────────────────────────────────────
+program
+  .command('export')
+  .description('Export archive messages as Markdown files')
+  .option('--exclude-folder <name>', 'skip this folder (repeatable)', collectRepeatable, [])
+  .option('--only-folder <name>', 'restrict to this folder (repeatable)', collectRepeatable, [])
+  .option('--verbose', 'log one line per exported file')
+  .action(async (opts: { excludeFolder: string[]; onlyFolder: string[]; verbose?: boolean }) => {
+    if (opts.excludeFolder.length > 0 && opts.onlyFolder.length > 0) {
+      console.error('Error: --exclude-folder and --only-folder are mutually exclusive')
+      process.exit(1)
+    }
+
+    try {
+      const repoRoot = getRepoRoot()
+      const archivePath = path.join(repoRoot, 'archive')
+      const exportPath = path.join(repoRoot, 'export')
+      const verbose = opts.verbose ?? false
+
+      const result = await exportAccount(archivePath, exportPath, {
+        excludeFolders: opts.excludeFolder,
+        onlyFolders: opts.onlyFolder,
+        verbose,
+        onLog: verbose ? (msg) => console.log(msg) : undefined,
+      })
+
+      const partialTag = result.errors > 0 ? ' [partial]' : ''
+      console.log(`export${partialTag}: =${result.exported} exported`)
+
+      for (const fr of result.folderResults) {
+        if (fr.error) {
+          console.error(`folder ${fr.path} failed: ${fr.error.message}`)
+        }
+      }
+
+      if (result.errors > 0) {
+        process.exit(1)
+      }
+    } catch (err) {
+      console.error(getErrorMessage(err))
+      process.exit(1)
+    }
+  })
+
 program.parse(process.argv)