imap-agent-cli 0.4.0

• Initialize standard streams as UTF-8 before output or skill synchronization. Read JSON input as UTF-8 and emit lossless ASCII-escaped JSON for reliable capture and piping on Windows.
• Return structured errors for unexpected exceptions and output failures. Add --debug for redacted traceback locations without exception text, source lines, local values, or exception chains.
• Distinguish network timeouts, connection failures, server failures, and missing messages. Include operation, phase, and attempt counts. Retry safe reads once after reconnecting and selecting the folder read-only.
• Keep draft appends single-attempt. Report an unknown outcome after an append network failure so callers can inspect Drafts before creating another message.
• Fetch headers and BODYSTRUCTURE for metadata reads and attachment listings. Fetch only the required text MIME part for body reads and thread context with BODY.PEEK. Read reply source metadata without transferring its attachments.
• Fetch search metadata incrementally for UID ordering and stop after enough qualifying results. Preserve attachment filtering and sort bounded date candidates across folders with timezone-aware comparisons.
• Add search --minimal, --fields, and --timings for smaller responses and optional phase diagnostics.
• Add --no-skill-sync and IMAP_AGENT_CLI_NO_SKILL_SYNC=1 to disable automatic skill checks and writes during ordinary commands and help.
• Document the installed executable as an alternative to uvx in restricted environments. Identify uv cache failures before startup as launcher or environment problems without changing credential locations.
• Update CLI help, the managed skill, and regression coverage for Unicode capture, selective MIME reads, retries, search efficiency, and structured failures.

Compatibility and limits

• Preserve default response keys. JSON uses ASCII escapes on the wire and preserves exact Unicode values after parsing.
• Attachment size_bytes can be null when BODYSTRUCTURE cannot provide the exact decoded size. Explicit downloads report exact decoded sizes.
• Search counts describe inspected candidates and observed matches. Date ordering covers the bounded candidate sets across the requested folders.
• --max-scan applies per folder after the server search. It does not limit server search work or the UID response. --max-body-chars limits returned text after rendering and does not cap transfer of the selected text part.

imap-agent-cli 0.3.0

This release adds one-command onboarding. Setup verifies mailbox access, saves account settings and credentials separately, and installs the managed imap agent skill.

Get started

Run this in your own terminal. Enter your password only at the masked prompt.

uvx imap-agent-cli@latest setup --format plain

Python 3.11 through 3.13 is supported. IMAPClient currently fails under Python 3.14. To request Python 3.13 explicitly, use uvx --python 3.13 imap-agent-cli@latest setup --format plain.

Changes

• Infer connection settings from supported email addresses, webmail URLs, and IMAP URLs. Prompt only for missing information.
• Explain provider credential requirements and mask password input with asterisks.
• Save entered passwords in a separate credentials file with normal inherited permissions. Environment variables remain explicit overrides.
• Preserve multiple profiles, unrelated TOML settings, and protected skill content. Verify replacement credentials before switching the saved account.
• Add read-only config check diagnostics and a --local check that does not connect.
• Verify setup with read-only mailbox selection and bounded metadata access. Do not fetch message bodies, mark messages read, or append drafts during setup.
• Use read-only mailbox selection for ordinary reads without a read-write fallback.
• Add explicit configuration and credential paths for agent, container, and remote execution.
• Update the PowerShell and Bash quick starts and provider guidance.

Compatibility

Existing mailbox commands, environment credentials, and profile commands remain available. Non-empty environment connection settings now override saved profile settings. Saved credentials are bound to their endpoint, username, and transport settings.

Passwords and app passwords are supported. OAuth remains out of scope. Microsoft 365 and Outlook.com accounts are unsupported.

Credentials are stored as plain text in a separate file. They are never displayed by configuration diagnostics. No OS keyring or persistent shell environment changes are required.

Validation

116 tests passed. The opt-in real-mailbox test was skipped. Source distribution and wheel builds passed with uv build --no-sources.

Validated with isolated configuration and dummy credentials on Windows with Python 3.13. Coverage includes clean and repeat setup, failed authentication and replacement, masked input, non-interactive execution, read-only behavior, and skill protections. The local IMAP integration checks unchanged message flags and fresh-process access to saved credentials. Packaging checks cover the wheel, uvx, source archive, editable installation, and local wrapper.

Hosted provider accounts and remote agent environments were not tested.

imap-agent-cli 0.2.1

General email searches now use only the inbox in the installed agent skill. Agents must keep searches within the requested scope and must not automatically broaden empty or incomplete results.

• Preserve specific-folder, recursive, and all-folder searches when requested, including JSON input.
• Clarify CLI help and documentation about folder defaults and the cost of searching large nested archives.
• Preserve the existing CLI behavior of searching only INBOX by default, with a configurable default folder.

Existing pristine managed skills in the standard location synchronize when the installed 0.2.1 CLI runs. Modified skills remain preserved. Start a new agent session to load the updated guidance.

Validation: 73 tests passed with 3 opt-in tests skipped. Source distribution and wheel builds passed with uv build --no-sources.

imap-agent-cli 0.2.0

Existing managed imap skills now synchronize automatically to the running CLI's newer version. Synchronization only checks ~/.agents/skills/imap/SKILL.md. It does not install missing skills, query package indexes, refresh uv, or update the CLI.

Changes

• Store ownership, the exact CLI version, and a normalized SHA-256 content hash in SKILL.md YAML metadata.
• Preserve modified or unverifiable skills with valid versions. Never overwrite unmanaged skills or downgrade newer versions.
• Add read-only skill status with JSON and plain output.
• Add uvx imap-agent-cli skill install --force to replace altered managed content explicitly.
• Preserve the install-skill and remove-skill aliases, custom-directory support, and removal-time --force.
• Replace skill files atomically and keep unrelated files during removal.

Compatibility

Local source and editable builds skip automatic synchronization. Custom skill locations require explicit updates. Legacy managed skills migrate once as version 0. Missing or malformed managed versions receive a fresh replacement without a hash check. The installed skill continues to instruct agents to use uvx.

Updates affect future skill loading. Running agent sessions may retain instructions they have already loaded.

Validation

Validated with the full unit suite, an isolated installed-wheel smoke test covering wheel, local source, editable, and uv tool execution, and source and wheel package builds. Live mailbox tests were not run.

imap-agent-cli 0.1.6

What's changed

• Updated the generated $imap skill to invoke commands with uvx imap-agent-cli ....
• Removed the forced --refresh-package imap-agent-cli cache refresh from every skill command, avoiding unnecessary package-index checks and startup work.
• Added regression coverage for the canonical command form.

Upgrade

Update the installed managed skill after upgrading:

uvx imap-agent-cli install-skill