Bale Chat Exporter is a Python command-line tool for exporting conversations that the user is authorized to archive. It turns a chat history into structured JSON and an organized local media directory while keeping privacy and safety visible in the workflow.

A deliberate export flow

The tool is organized around a predictable pipeline:

1. inspect the available dialogs,
2. select a conversation explicitly,
3. fetch history with pagination and duplicate protection,
4. normalize message, sender, timestamp, reply, forward, and media data,
5. write a timestamped export with categorized media folders.

The result contains result.json, a short README, and media folders such as images, videos, audio, voice, and documents.

Safety is part of the interface

Session files, raw provider data, direct media URLs, and exported conversations are sensitive. The tool therefore uses explicit confirmation, safe filenames, optional --no-raw output, optional --no-media smoke tests, and does not treat a successful request as permission to publish the resulting data.

Technical details

The implementation separates the command-line lifecycle, export orchestration, provider-object introspection, dataclass output models, and filename safety. Tests cover pagination, repeated-page protection, normalization, and media fallback without needing a real Bale account or session. This is a small project, but it captures a kind of engineering I care about: turning a risky manual process into a clear, testable, and privacy-aware workflow.