Metadata-Version: 2.4
Name: imap-migration-tools
Version: 1.7.0
Summary: Tools for migrating IMAP emails
Author-email: Javier Callico <jcallico@callicode.com>, Nathan Moinvaziri <nathan@nathanm.com>
Project-URL: Homepage, https://github.com/jcallico/imap-migration-tools
Project-URL: Bug Tracker, https://github.com/jcallico/imap-migration-tools/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-auth-oauthlib
Requires-Dist: msal
Requires-Dist: msal-extensions>=1.3.1
Requires-Dist: python-dotenv>=1.2.1
Provides-Extra: gui
Requires-Dist: platformdirs<5,>=3.6; extra == "gui"
Requires-Dist: wxPython<5,>=4.3; sys_platform == "darwin" and extra == "gui"
Requires-Dist: wxPython<5,>=4.2.1; sys_platform != "darwin" and extra == "gui"
Provides-Extra: dotenv
Provides-Extra: linux-keyring
Requires-Dist: PyGObject>=3.42; sys_platform == "linux" and extra == "linux-keyring"
Provides-Extra: tui
Requires-Dist: platformdirs<5,>=3.6; extra == "tui"
Requires-Dist: textual<9,>=8.2; extra == "tui"
Dynamic: license-file

# IMAP Email Migration Tools

![CI](https://github.com/JCallico/imap-migration-tools/actions/workflows/ci.yml/badge.svg)
[![codecov](https://codecov.io/github/JCallico/imap-migration-tools/graph/badge.svg?token=SDF29GC5VV)](https://codecov.io/github/JCallico/imap-migration-tools)
![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)
![License](https://img.shields.io/badge/license-MIT-green)

A collection of command-line tools for migrating, backing up, restoring, counting, and comparing email on IMAP
servers. The tools were created for large migrations where simpler clients timed out or could not resume reliably.

They support password and OAuth2 authentication, incremental operation, Gmail labels, standard IMAP flags, local
`.eml` backups, and destination synchronization.

> These tools can copy and delete email. Test with non-critical data, verify counts and backups, and review destructive
> options before using them on an important account. The software is provided without warranty.

## Commands

| Installed command | Source entry point | Purpose |
|---|---|---|
| `imap-migrate` | `src/imap_migrate.py` | Copy or move email between IMAP accounts |
| `imap-backup` | `src/imap_backup.py` | Download an IMAP account as `.eml` files |
| `imap-restore` | `src/imap_restore.py` | Upload a local backup to an IMAP account |
| `imap-compare` | `src/imap_compare.py` | Compare folder counts across IMAP or local sources |
| `imap-count` | `src/imap_count.py` | Count messages on an account or in a local backup |
| `imap-tools` | `src/tui/app.py` | Configure and run all tools in a full-screen terminal interface |
| `imap-tools-gui` | `src/gui/app.py` | Configure and run all tools in a native desktop GUI |

Legacy script names remain available as compatibility wrappers.

## Installation

Python 3.10 or newer is required. Install the standard commands using `pipx`:

```bash
pipx install imap-migration-tools
```

Or use pip in a virtual environment on macOS or Linux:

```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install imap-migration-tools
```

On Windows PowerShell:

```powershell
py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install imap-migration-tools
```

On Windows Command Prompt:

```batch
py -m venv .venv
.venv\Scripts\activate.bat
python -m pip install imap-migration-tools
```

The standard installation supports command-line arguments, OS environment variables, and automatic `.env` loading.
The legacy `imap-migration-tools[dotenv]` spelling remains accepted, but the extra is no longer necessary.

## Quick start

To configure the tools with the included `.env` support, copy the safe template:

```bash
cp .env.example .env
```

Edit `.env` with source and destination credentials. The template enables password authentication by default; OAuth2
values are empty. Configure only one authentication method per account.

Migrate all folders:

```bash
imap-migrate
```

Or provide a complete account directly:

```bash
imap-migrate \
  --src-host "imap.gmail.com" \
  --src-user "source@gmail.com" \
  --src-pass "source-app-password" \
  --dest-host "imap.example.com" \
  --dest-user "destination@example.com" \
  --dest-pass "destination-password"
```

Back up and verify an account:

```bash
imap-backup \
  --src-host "imap.gmail.com" \
  --src-user "you@gmail.com" \
  --src-pass "app-password" \
  --dest-path "./mail-backup"

imap-compare \
  --src-host "imap.gmail.com" \
  --src-user "you@gmail.com" \
  --src-pass "app-password" \
  --dest-path "./mail-backup"
```

## Interfaces

### Python library

The installed distribution also provides the `imap_services` Python package. Services take explicit configuration,
return structured results, and optionally publish structured progress events; unlike the command-line adapters, they do
not read `.env` or configure logging.

```python
from imap_services import AccountConfig, CountService, ImapTarget

account = AccountConfig(
    host="imap.example.com",
    username="person@example.com",
    password="app-password",
)
service = CountService(ImapTarget(account), on_event=lambda event: print(event.message))
result = service.run()
print(result.total)
```

`BackupService`, `RestoreService`, `MigrationService`, and `ComparisonService` use the same configuration and callback
model. Applications may configure handlers for the `imap_services` logger hierarchy when diagnostic logs are needed;
normal progress is delivered only through callbacks.

### Full-screen terminal interface

The Textual interface provides one responsive, full-terminal application for configuring and running Count,
Compare, Backup, Restore, and Migrate. Install the optional TUI dependencies with `pipx`:

```bash
pipx install "imap-migration-tools[tui]"
```

If `imap-migration-tools` is already installed through `pipx`, reinstall it with the TUI extra:

```bash
pipx install --force "imap-migration-tools[tui]"
```

Launch the interface with the installed command:

```bash
imap-tools
```

For a standard virtual environment:

```bash
python -m pip install "imap-migration-tools[tui]"
imap-tools
```

The interface provides a guided autosaving `.env` form, operation readiness guidance, live output, cancellation, and
local run history.

<p align="left">
  <img src="https://raw.githubusercontent.com/JCallico/imap-migration-tools/1.7.0/docs/images/tui-overview.jpg" width="800" alt="IMAP Migration Tools TUI showing Configuration, Tools, Operation, History, and Output panels">
</p>

Review the generated command in the Output panel and verify backups and counts before enabling destructive options.

The interface organizes configurations as [projects](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/docs/configuration.md#projects): `default` and named projects
are stored as `.env` files in `~/.imap-migration-tools`, and a `.env` discovered from the current directory or its
parents appears as the `local` project. Values use the same precedence as the scripts: per-run choices, existing OS
environment variables, the project's `.env`, then defaults. Passwords and OAuth client secrets are
masked in the form; new `.env` files and saved history use owner-only permissions where the platform supports them.
Destructive options require typing `DELETE` before a run starts. Press `F1` for help or `F2` for the keyboard reference.

See the [Terminal interface guide](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/docs/tui.md) for responsive layouts, panel controls, ASCII mode, configuration
reloads, and History behavior across multiple instances.

Basic password authentication needs no additional authentication package. OAuth2 provider dependencies are installed
by the project. Encrypted persistent caching on Linux requires the `linux-keyring` extra and native system libraries.
See [Installation](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/docs/installation.md) for platform and source setup.

### Native Android application

The Android project provides a Kotlin and Jetpack Compose application for Count, Compare, Backup, Restore, and Migrate.
It embeds the existing Python service engine with Chaquopy, runs user-started network operations as Android
user-initiated data-transfer jobs on Android 14 and newer (with a foreground-service compatibility path on older
versions), streams structured progress, supports cooperative cancellation, and keeps credentials out of persisted
configuration and history.

Android builds currently target developers and CI rather than Play distribution. See the
[Android application guide](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/docs/android.md) for its architecture, build requirements, storage model, and platform
execution constraints. The [Google Play publication checklist](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/docs/android-publishing.md) tracks the separate signing,
identity-provider approval, policy, store-listing, testing, and rollout work required for public distribution.

### Native desktop GUI

The wxPython interface provides one native desktop workspace for configuring and running Count, Compare, Backup,
Restore, and Migrate on Linux, macOS, and Windows. Install the optional desktop dependencies with `pipx`:

```bash
pipx install "imap-migration-tools[gui]"
```

If `imap-migration-tools` is already installed through `pipx`, reinstall it with the desktop extra:

```bash
pipx install --force "imap-migration-tools[gui]"
```

Launch the desktop application with the installed command:

```bash
imap-tools-gui
```

For a standard virtual environment:

```bash
python -m pip install "imap-migration-tools[gui]"
imap-tools-gui
```

The application provides an autosaving `.env` form, operation readiness guidance, confirmations, live output,
cancellation, and shared local run history. It uses native GTK, Cocoa, or Windows controls, detects the operating-system
theme on first launch, and provides explicit System, Light, and Dark appearance choices. View also includes persistent
zoom and transparency controls; transparency depends on compositor support.

#### Desktop theme previews

| Theme | Linux | Windows | macOS |
| --- | --- | --- | --- |
| Light | <img src="https://raw.githubusercontent.com/JCallico/imap-migration-tools/1.7.0/docs/images/gui-overview-linux-light.png" alt="IMAP Migration Tools light theme on Linux" width="420"> | <img src="https://raw.githubusercontent.com/JCallico/imap-migration-tools/1.7.0/docs/images/gui-overview-windows-light.png" alt="IMAP Migration Tools light theme on Windows" width="420"> | <img src="https://raw.githubusercontent.com/JCallico/imap-migration-tools/1.7.0/docs/images/gui-overview-macos-light.png" alt="IMAP Migration Tools light theme on macOS" width="420"> |
| Dark | <img src="https://raw.githubusercontent.com/JCallico/imap-migration-tools/1.7.0/docs/images/gui-overview-linux-dark.png" alt="IMAP Migration Tools dark theme on Linux" width="420"> | <img src="https://raw.githubusercontent.com/JCallico/imap-migration-tools/1.7.0/docs/images/gui-overview-windows-dark.png" alt="IMAP Migration Tools dark theme on Windows" width="420"> | <img src="https://raw.githubusercontent.com/JCallico/imap-migration-tools/1.7.0/docs/images/gui-overview-macos-dark.png" alt="IMAP Migration Tools dark theme on macOS" width="420"> |

On macOS, the selected Light or Dark palette also updates native Cocoa controls, dialogs, menus, and window chrome.
System mode follows the operating-system appearance.

The desktop application shares the TUI's [projects](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/docs/configuration.md#projects), so the `default` and named
projects are available however it is launched. Select a project or a specific file at launch when needed:

```bash
imap-tools-gui --project "Acme Corp"
imap-tools-gui --env /path/to/project/.env
```

Configuration precedence and secret handling match the TUI. Passwords and OAuth client secrets are masked,
destructive operations require typing `DELETE`, and logs use the shared redaction and owner-only history storage.
Review the readiness message and confirmation before starting a destructive operation.

Windows and macOS normally install wxPython from published wheels. Linux may require the distribution's wxPython
package or GTK development libraries. See the [Native desktop GUI guide](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/docs/gui.md) for source installation,
Linux prerequisites, appearance controls, testing, bundle creation, and platform evaluation.

## Configuration essentials

Configuration precedence is:

1. Command-line arguments
2. Existing OS environment variables
3. `.env` values
4. Script defaults

Authentication is resolved as one choice, so a higher-precedence password cannot be displaced by a lower-precedence
OAuth client ID, or vice versa. A host is an account boundary: when overriding a host, provide its username and password
or OAuth client ID from the same or a higher-precedence source.

Environment-backed booleans have positive and negative CLI forms. For example:

```bash
imap-migrate --src-delete
imap-migrate --no-src-delete
imap-backup --dest-delete
imap-backup --no-dest-delete
```

When local, source, and destination count targets coexist, choose explicitly:

```bash
imap-count --target local
imap-count --target source
imap-count --target destination
```

See [Configuration](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/docs/configuration.md) for all precedence, authentication, mode-selection, namespace, and boolean
rules.

## Common workflows

- [Migration, backup, restore, count, and comparison examples](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/docs/workflows.md)
- [Full-screen terminal interface](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/docs/tui.md)
- [Native desktop GUI](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/docs/gui.md)
- [Native Android app and emulator setup](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/docs/android.md)
- [OAuth2 setup for Microsoft and Google](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/docs/oauth2.md)
- [Troubleshooting and operational safety](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/docs/troubleshooting.md)
- [Development, testing, and CI](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/docs/development.md)
- [Product backlog](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/docs/backlog.md)

For large migrations, start with a count, run a non-destructive copy, compare the result, and only then consider
deletion or synchronization options.

## Contributing

Create a virtual environment, install the project and development requirements, then run:

```bash
make ci
```

See [Development](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/docs/development.md) and [AGENTS.md](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/AGENTS.md) for the complete contributor workflow and repository
conventions.

## License

Licensed under the [MIT License](https://github.com/JCallico/imap-migration-tools/blob/1.7.0/LICENSE).
