Metadata-Version: 2.4
Name: imap-migration-tools
Version: 1.6.2
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.2.1; 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/main/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 discovers `.env` from the current directory and its parents, using the same precedence as the scripts:
per-run choices, existing OS environment variables, `.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](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](docs/installation.md) for platform and source setup.

### 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 and follows the active
operating-system theme. View includes persistent zoom and transparency controls; transparency depends on compositor
support.

| Linux | macOS | Windows |
| --- | --- | --- |
| ![IMAP Migration Tools native desktop interface on Linux](https://raw.githubusercontent.com/JCallico/imap-migration-tools/main/docs/images/gui-overview-linux.png) | ![IMAP Migration Tools native desktop interface on macOS](https://raw.githubusercontent.com/JCallico/imap-migration-tools/main/docs/images/gui-overview-macos.png) | ![IMAP Migration Tools native desktop interface on Windows](https://raw.githubusercontent.com/JCallico/imap-migration-tools/main/docs/images/gui-overview-windows.png) |

The desktop application discovers `.env` from the current directory and its parents. Desktop launchers may start in a
different directory, so select a configuration explicitly when needed:

```bash
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](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](docs/configuration.md) for all precedence, authentication, mode-selection, namespace, and boolean
rules.

## Common workflows

- [Migration, backup, restore, count, and comparison examples](docs/workflows.md)
- [Full-screen terminal interface](docs/tui.md)
- [Native desktop GUI](docs/gui.md)
- [OAuth2 setup for Microsoft and Google](docs/oauth2.md)
- [Troubleshooting and operational safety](docs/troubleshooting.md)
- [Development, testing, and CI](docs/development.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](docs/development.md) and [AGENTS.md](AGENTS.md) for the complete contributor workflow and repository
conventions.

## License

Licensed under the [MIT License](LICENSE).
