imexp 0.1.0

Interactive CLI wrapper for imessage-exporter with contact name resolution and post-processing

imexp

An interactive CLI wrapper for imessage-exporter that adds contact name resolution and post-processing to your iMessage exports.

Features

• Interactive wizard — run imexp with no arguments for a guided export experience
• Natural language dates — use phrases like "last 6 months" or "2 weeks ago"
• Contact resolution — automatically maps phone numbers and emails to names from your macOS or iOS Contacts database
• iOS backup support — auto-detects backups and lets you pick by device name/date
• Post-processing — renames exported files and replaces raw handles with contact names
• Export history — tracks your last export date to avoid duplicates

Requirements

• Python 3.12+
• macOS or Windows for the official wheels

macOS local Address Book lookups require macOS. iOS backup exports work on both macOS and Windows.

Installation

Install from PyPI:

pip install imexp

Official wheels bundle the matching imessage-exporter binary for:

• macOS Apple Silicon
• macOS Intel
• Windows x86_64

Source installs do not bundle the exporter binary. For editable or source installs, either:

• install imessage-exporter separately and keep it on PATH
• point IMEXP_EXPORTER_PATH at a local binary

Example source install:

git clone https://github.com/code-switched/imexp.git
cd imexp
pip install -e .

Usage

Interactive mode

Simply run with no arguments for the guided wizard:

imexp

You'll be prompted for:

• Platform (macOS or iOS backup)
• Date range (natural language supported)
• Export location

Command-line mode

imexp export --start-date "2024-01-01" --end-date "2024-06-01" --format txt

Relabel existing exports

Re-run contact resolution on a previous export:

imexp relabel --export-path ./data/messages/sms/2024-01-15-10-30-00

Common options

Option	Description
--start-date	Start date (natural language or YYYY-MM-DD)
--end-date	End date (defaults to now)
--format	Output format: txt, html (default: txt)
--platform	macOS or iOS
--db-path	Path to iOS backup or custom chat.db
--export-path	Custom output directory
--non-interactive	Disable prompts for scripted use
-v, --verbose	Enable debug logging

How it works

1. Runs imessage-exporter with your specified options
2. Loads contacts from macOS Contacts.app or iOS backup
3. Post-processes exported files:
   • Renames files from phone numbers to contact names
   • Replaces raw handles in file contents with names
4. Saves unknown number → name mappings to contacts.json for future exports
5. Tracks export history in history.json for incremental exports

Configuration files

By default, files are stored in ./data/messages/sms/:

• contacts.json — custom name overrides for unknown numbers
• history.json — tracks last export date

License

imexp is distributed under GPL-3.0-or-later.

The official wheels bundle the upstream imessage-exporter binary, which is also licensed under GPL-3.0.