imap-agent-cli 0.2.1__tar.gz → 0.3.0__tar.gz

{imap_agent_cli-0.2.1 → imap_agent_cli-0.3.0}/AGENTS.md

@@ -25,7 +25,7 @@ The core safety boundary is strict: never add support for sending email, deletin
 - Keep the root wrapper thin; application logic belongs under `src/imap_agent_cli/`.
 - Preserve stable JSON payloads on stdout. Diagnostics, warnings, progress, and errors must go to stderr.
 - Do not print secrets, credentials, full message bodies, or attachment contents in logs.
-- Keep credentials in environment variables or config references to environment variables. Do not add config examples that store passwords directly.
+- Keep secrets separate from ordinary configuration. Credentials may come from environment variables, explicit stdin, or the separate credentials file written by setup. Never include real credentials in examples. Use normal inherited filesystem permissions. Do not require an OS keyring or persist shell environment variables.
 - Keep README and skill language platform-neutral and agent-tool-neutral. Avoid shell-specific syntax unless explicitly documenting a shell-specific example.
 - If changing installed-skill behavior or wording, update `src/imap_agent_cli/skill.py` and `tests/test_skill.py` together.
 - If changing MIME parsing, body rendering, draft creation, or search behavior, add focused tests for the contract being changed.

{imap_agent_cli-0.2.1 → imap_agent_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: imap-agent-cli
-Version: 0.2.1
+Version: 0.3.0
 Summary: Agent-first IMAP CLI for safe email search, read, attachment download, and draft creation
 Project-URL: Homepage, https://github.com/pseudosavant/imap-agent-cli
 Project-URL: Repository, https://github.com/pseudosavant/imap-agent-cli
@@ -21,13 +21,16 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Communications :: Email
 Classifier: Topic :: Communications :: Email :: Post-Office :: IMAP
 Classifier: Topic :: Utilities
-Requires-Python: >=3.11
+Requires-Python: <3.14,>=3.11
 Requires-Dist: beautifulsoup4>=4.12.0
 Requires-Dist: bleach>=6.2.0
+Requires-Dist: filelock>=3.16.0
 Requires-Dist: imapclient>=3.0.0
 Requires-Dist: markdownify>=0.14.0
 Requires-Dist: packaging>=23.2
+Requires-Dist: prompt-toolkit>=3.0.43
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: tomlkit>=0.13.0
 Provides-Extra: test
 Requires-Dist: pymap>=0.36.0; extra == 'test'
 Requires-Dist: pytest>=8.0.0; extra == 'test'
@@ -39,40 +42,51 @@ Description-Content-Type: text/markdown
 
 It never sends email and cannot change existing messages or folders.
 
-## Prerequisite
+## Quick start with an agent
 
-`imap-agent-cli` is designed to be used with [`uv`](https://docs.astral.sh/uv/getting-started/installation/). Install `uv` before continuing. The documented workflows and managed agent skill use `uvx` to run the tool without requiring a global installation.
+You need an IMAP-enabled email account and a compatible password or app password. Setup explains credential creation for Gmail, Fastmail, and iCloud. Other IMAP servers need their provider's hostname and login details. Microsoft 365 and Outlook.com require OAuth and are not supported. Microsoft app passwords are not a workaround.
 
-## Quick start with an agent
+Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) if needed. The managed skill runs the tool with `uvx`. You do not need a global tool installation. uv can obtain a compatible Python automatically. Direct Python installs require Python 3.11 through 3.13. IMAPClient is currently incompatible with Python 3.14.
 
-Install the managed `imap` agent skill:
+PowerShell:
 
-```text
-uvx imap-agent-cli skill install
+```powershell
+# Skip this command if uv is already installed.
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# Open a new PowerShell window after installation.
+uv --version
+uvx imap-agent-cli setup --format plain
 ```
 
-Configure a default IMAP account through environment variables:
+Bash on Linux or macOS:
 
-```text
-IMAP_AGENT_CLI_HOST=imap.example.com
-IMAP_AGENT_CLI_PORT=993
-IMAP_AGENT_CLI_USERNAME=me@example.com
-IMAP_AGENT_CLI_PASSWORD=your-password-or-app-password
-IMAP_AGENT_CLI_TLS=true
-IMAP_AGENT_CLI_SSL_MODE=required
+```bash
+# Skip these two commands if uv is already installed.
+curl -LsSf https://astral.sh/uv/install.sh | sh
+. "$HOME/.local/bin/env"
+
+uv --version
+uvx imap-agent-cli setup --format plain
 ```
 
-Check the connection without reading message bodies:
+Enter your credential only at the masked terminal prompt. Never paste a credential into agent chat. Setup saves account settings and credentials separately, verifies read-only mailbox access, and installs the managed `imap` skill. No separate test command is needed after successful setup.
+
+You can provide information you already know:
 
 ```text
-uvx imap-agent-cli config check
+uvx imap-agent-cli setup "me@gmail.com"
+uvx imap-agent-cli setup "https://app.fastmail.com/"
+uvx imap-agent-cli setup --host imap.example.com --username me@example.com
 ```
 
-Then use `$imap` in Codex, Claude Code, or another agentic tool that supports skills:
+A webmail URL is only a provider hint. It is not fetched. Custom email domains require a provider hostname. See [setup and credential guidance](docs/setup.md) for provider requirements and recovery commands.
+
+Start a new agent session if the skill is not available. Then ask:
 
-> Use $imap to find the five most recent emails about the Acme renewal. Summarize the latest thread and create a reply draft asking for the updated contract. Do not download attachments.
+> Use $imap to list the five newest messages in INBOX. Show senders and subjects only.
 
-The skill teaches the agent to search before reading, keep operations bounded, download attachments only when requested, and create drafts without sending them.
+The agent must have access to `uvx`, the saved files, and the IMAP server. A remote host or container needs its own runtime and credential provision. If terminal use works but agent use fails, ask the agent to run `uvx imap-agent-cli config check`. Do not ask it to open the credentials file.
 
 ## What it can do
 
@@ -130,51 +144,63 @@ The usual workflow is to search first, select a result by folder and UID, read o
 
 ## Configure accounts
 
-### One account with environment variables
-
-For a single account, environment variables are enough:
+### Saved accounts
 
 ```text
-IMAP_AGENT_CLI_HOST=imap.example.com
-IMAP_AGENT_CLI_PORT=993
-IMAP_AGENT_CLI_USERNAME=me@example.com
-IMAP_AGENT_CLI_PASSWORD=your-password-or-app-password
-IMAP_AGENT_CLI_TLS=true
-IMAP_AGENT_CLI_SSL_MODE=required
-IMAP_AGENT_CLI_DRAFTS_FOLDER=Drafts
+uvx imap-agent-cli setup
+uvx imap-agent-cli setup --profile work
+uvx imap-agent-cli setup --profile work --set-default
+uvx imap-agent-cli profiles
+uvx imap-agent-cli config show
 ```
 
-`IMAP_AGENT_CLI_DRAFTS_FOLDER` is optional. When omitted, the CLI tries the server's IMAP special-use metadata and common Drafts folder names.
+The first account uses the name `default`. Adding an account preserves the existing default. Pass `--profile work` to mailbox commands to select it.
 
-Validate the resolved configuration, login, folders, default folder, and Drafts detection without reading message bodies:
+Non-secret settings live in `~/.imap-agent-cli/config.toml`. Setup saves entered passwords in `~/.imap-agent-cli/credentials.toml` with normal inherited permissions. It does not require a keyring, change ACLs, or persist shell variables. The credential file is plain text. Keep it out of repositories and shared exports.
 
-```text
-uvx imap-agent-cli config check
-```
+Repeated setup reuses existing credentials and preserves unrelated configuration and skill content. Use `setup --replace-password` to verify and save a replacement. Unset password environment overrides first. Existing configuration remains usable if verification or saving fails.
 
-### Multiple account profiles
+### Environment overrides
 
-Create a config file when you need named accounts:
+Environment variables remain available. Connection flags take priority over non-empty environment overrides, followed by the selected saved profile and built-in defaults. Password resolution uses explicit stdin, the profile's named password variable, the global password variable, and finally the matching saved credential. Rejected credentials do not trigger fallback to another source.
 
-```text
-uvx imap-agent-cli config init
-uvx imap-agent-cli config add-profile work --host imap.example.com --port 993 --username me@example.com --password-env IMAP_AGENT_CLI_WORK_PASSWORD
-uvx imap-agent-cli config set-default-profile work
+PowerShell:
+
+```powershell
+$env:IMAP_AGENT_CLI_HOST = "imap.example.com"
+$env:IMAP_AGENT_CLI_USERNAME = "me@example.com"
+$imapCredential = Read-Host "IMAP password or app password" -AsSecureString
+$env:IMAP_AGENT_CLI_PASSWORD = [System.Net.NetworkCredential]::new("", $imapCredential).Password
+Remove-Variable imapCredential
+uvx imap-agent-cli setup --non-interactive
+```
+
+Bash:
+
+```bash
+export IMAP_AGENT_CLI_HOST="imap.example.com"
+export IMAP_AGENT_CLI_USERNAME="me@example.com"
+read -rs -p "IMAP password or app password: " IMAP_AGENT_CLI_PASSWORD
+printf '\n'
+export IMAP_AGENT_CLI_PASSWORD
+uvx imap-agent-cli setup --non-interactive
 ```
 
-The config file is stored at `~/.imap-agent-cli/config.toml`. Keep passwords in environment variables. Profiles store the name of the password environment variable, not the password itself.
+These variables affect the current shell and its children. An already-running agent does not inherit later changes. Setup uses an environment password without saving its value. Secure defaults supply port `993`, `tls=true`, and `ssl_mode=required`.
 
-The CLI uses standard IMAP username and password authentication. It does not provide OAuth setup. Providers that disable account-password login may require an app password.
+The existing `config init`, `config add-profile`, and `config set-default-profile` commands remain available. `config init` creates a starter file. Prefer `setup` to complete onboarding. Existing `password_env` references continue to work.
 
-Inspect resolved settings without exposing secrets, or list available profiles:
+### Check configuration
 
 ```text
-uvx imap-agent-cli config show
-uvx imap-agent-cli profiles
-uvx imap-agent-cli config check --profile work
+uvx imap-agent-cli config check
+uvx imap-agent-cli config check --profile work --format plain
+uvx imap-agent-cli config check --local
 ```
 
-Pass `--profile NAME` to any mailbox command to select a non-default profile. Direct commands also accept connection flags and `--password-stdin` for one-off use.
+Checks never write configuration, credentials, or skills. The network check verifies login, opens the default mailbox read-only, and checks bounded metadata access. It never reads bodies or appends a test message. Missing Drafts is a warning for reading. Finding Drafts does not verify append permission or quota. An empty mailbox leaves metadata fetching untested.
+
+Use `--config PATH` or `IMAP_AGENT_CLI_CONFIG` for another configuration file. Use `--credentials-file PATH` or `IMAP_AGENT_CLI_CREDENTIALS_FILE` for a separate credential file. Explicit paths work with setup, diagnostics, and mailbox commands. Relative command-line paths resolve from the working directory. Setup saves an explicitly selected credential file path for later use. Custom skill locations use `--skills-dir PATH`.
 
 ### Connection security
 
@@ -296,7 +322,7 @@ uvx imap-agent-cli skill status
 uvx imap-agent-cli skill status --format plain
 ```
 
-Normal invocations of an installed CLI update a pristine older managed skill to the running CLI version. Synchronization is local. It does not query PyPI, refresh uv's cache, or update the CLI. Missing skills are never installed automatically. Unmanaged, modified, equal-version, and newer skills are preserved.
+Normal mailbox invocations and top-level help, version, and about commands of an installed CLI update a pristine older managed skill to the running CLI version. Synchronization is local. It does not query PyPI, refresh uv's cache, or update the CLI. Missing skills are never installed automatically. Unmanaged, modified, equal-version, and newer skills are preserved.
 
 Restore altered managed content explicitly:
 
@@ -336,7 +362,7 @@ uvx imap-agent-cli draft create --json draft.json
 uvx imap-agent-cli draft reply --json reply.json
 ```
 
-Use `--json -` to read the JSON request from stdin. Failures leave stdout empty and write a compact JSON error to stderr. Logs do not include passwords, message bodies, or attachment content.
+Use `--json -` to read the JSON request from stdin. Operational failures leave stdout empty and write a compact JSON error to stderr. Setup and configuration checks return structured readiness reports when verification or a later step fails. Check the exit status and the `ready` or `ok` field. Human diagnostics go to stderr. Add `--format plain` to setup or config check for a readable report. Logs do not include passwords, message bodies, or attachment content.
 
 Default guardrails keep work bounded:
 
@@ -355,6 +381,7 @@ Commands expose targeted overrides such as `--max-results`, `--max-scan`, `--max
 
 | Command | Purpose |
 | --- | --- |
+| `setup` | Verify and save an account, then install the managed skill |
 | `config` | Initialize, inspect, validate, and manage profile configuration |
 | `profiles` | List configured profile names |
 | `skill` | Install, inspect, or remove the managed agent skill |

{imap_agent_cli-0.2.1 → imap_agent_cli-0.3.0}/README.md

@@ -4,40 +4,51 @@
 
 It never sends email and cannot change existing messages or folders.
 
-## Prerequisite
+## Quick start with an agent
 
-`imap-agent-cli` is designed to be used with [`uv`](https://docs.astral.sh/uv/getting-started/installation/). Install `uv` before continuing. The documented workflows and managed agent skill use `uvx` to run the tool without requiring a global installation.
+You need an IMAP-enabled email account and a compatible password or app password. Setup explains credential creation for Gmail, Fastmail, and iCloud. Other IMAP servers need their provider's hostname and login details. Microsoft 365 and Outlook.com require OAuth and are not supported. Microsoft app passwords are not a workaround.
 
-## Quick start with an agent
+Install [`uv`](https://docs.astral.sh/uv/getting-started/installation/) if needed. The managed skill runs the tool with `uvx`. You do not need a global tool installation. uv can obtain a compatible Python automatically. Direct Python installs require Python 3.11 through 3.13. IMAPClient is currently incompatible with Python 3.14.
 
-Install the managed `imap` agent skill:
+PowerShell:
 
-```text
-uvx imap-agent-cli skill install
+```powershell
+# Skip this command if uv is already installed.
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# Open a new PowerShell window after installation.
+uv --version
+uvx imap-agent-cli setup --format plain
 ```
 
-Configure a default IMAP account through environment variables:
+Bash on Linux or macOS:
 
-```text
-IMAP_AGENT_CLI_HOST=imap.example.com
-IMAP_AGENT_CLI_PORT=993
-IMAP_AGENT_CLI_USERNAME=me@example.com
-IMAP_AGENT_CLI_PASSWORD=your-password-or-app-password
-IMAP_AGENT_CLI_TLS=true
-IMAP_AGENT_CLI_SSL_MODE=required
+```bash
+# Skip these two commands if uv is already installed.
+curl -LsSf https://astral.sh/uv/install.sh | sh
+. "$HOME/.local/bin/env"
+
+uv --version
+uvx imap-agent-cli setup --format plain
 ```
 
-Check the connection without reading message bodies:
+Enter your credential only at the masked terminal prompt. Never paste a credential into agent chat. Setup saves account settings and credentials separately, verifies read-only mailbox access, and installs the managed `imap` skill. No separate test command is needed after successful setup.
+
+You can provide information you already know:
 
 ```text
-uvx imap-agent-cli config check
+uvx imap-agent-cli setup "me@gmail.com"
+uvx imap-agent-cli setup "https://app.fastmail.com/"
+uvx imap-agent-cli setup --host imap.example.com --username me@example.com
 ```
 
-Then use `$imap` in Codex, Claude Code, or another agentic tool that supports skills:
+A webmail URL is only a provider hint. It is not fetched. Custom email domains require a provider hostname. See [setup and credential guidance](docs/setup.md) for provider requirements and recovery commands.
+
+Start a new agent session if the skill is not available. Then ask:
 
-> Use $imap to find the five most recent emails about the Acme renewal. Summarize the latest thread and create a reply draft asking for the updated contract. Do not download attachments.
+> Use $imap to list the five newest messages in INBOX. Show senders and subjects only.
 
-The skill teaches the agent to search before reading, keep operations bounded, download attachments only when requested, and create drafts without sending them.
+The agent must have access to `uvx`, the saved files, and the IMAP server. A remote host or container needs its own runtime and credential provision. If terminal use works but agent use fails, ask the agent to run `uvx imap-agent-cli config check`. Do not ask it to open the credentials file.
 
 ## What it can do
 
@@ -95,51 +106,63 @@ The usual workflow is to search first, select a result by folder and UID, read o
 
 ## Configure accounts
 
-### One account with environment variables
-
-For a single account, environment variables are enough:
+### Saved accounts
 
 ```text
-IMAP_AGENT_CLI_HOST=imap.example.com
-IMAP_AGENT_CLI_PORT=993
-IMAP_AGENT_CLI_USERNAME=me@example.com
-IMAP_AGENT_CLI_PASSWORD=your-password-or-app-password
-IMAP_AGENT_CLI_TLS=true
-IMAP_AGENT_CLI_SSL_MODE=required
-IMAP_AGENT_CLI_DRAFTS_FOLDER=Drafts
+uvx imap-agent-cli setup
+uvx imap-agent-cli setup --profile work
+uvx imap-agent-cli setup --profile work --set-default
+uvx imap-agent-cli profiles
+uvx imap-agent-cli config show
 ```
 
-`IMAP_AGENT_CLI_DRAFTS_FOLDER` is optional. When omitted, the CLI tries the server's IMAP special-use metadata and common Drafts folder names.
+The first account uses the name `default`. Adding an account preserves the existing default. Pass `--profile work` to mailbox commands to select it.
 
-Validate the resolved configuration, login, folders, default folder, and Drafts detection without reading message bodies:
+Non-secret settings live in `~/.imap-agent-cli/config.toml`. Setup saves entered passwords in `~/.imap-agent-cli/credentials.toml` with normal inherited permissions. It does not require a keyring, change ACLs, or persist shell variables. The credential file is plain text. Keep it out of repositories and shared exports.
 
-```text
-uvx imap-agent-cli config check
-```
+Repeated setup reuses existing credentials and preserves unrelated configuration and skill content. Use `setup --replace-password` to verify and save a replacement. Unset password environment overrides first. Existing configuration remains usable if verification or saving fails.
 
-### Multiple account profiles
+### Environment overrides
 
-Create a config file when you need named accounts:
+Environment variables remain available. Connection flags take priority over non-empty environment overrides, followed by the selected saved profile and built-in defaults. Password resolution uses explicit stdin, the profile's named password variable, the global password variable, and finally the matching saved credential. Rejected credentials do not trigger fallback to another source.
 
-```text
-uvx imap-agent-cli config init
-uvx imap-agent-cli config add-profile work --host imap.example.com --port 993 --username me@example.com --password-env IMAP_AGENT_CLI_WORK_PASSWORD
-uvx imap-agent-cli config set-default-profile work
+PowerShell:
+
+```powershell
+$env:IMAP_AGENT_CLI_HOST = "imap.example.com"
+$env:IMAP_AGENT_CLI_USERNAME = "me@example.com"
+$imapCredential = Read-Host "IMAP password or app password" -AsSecureString
+$env:IMAP_AGENT_CLI_PASSWORD = [System.Net.NetworkCredential]::new("", $imapCredential).Password
+Remove-Variable imapCredential
+uvx imap-agent-cli setup --non-interactive
+```
+
+Bash:
+
+```bash
+export IMAP_AGENT_CLI_HOST="imap.example.com"
+export IMAP_AGENT_CLI_USERNAME="me@example.com"
+read -rs -p "IMAP password or app password: " IMAP_AGENT_CLI_PASSWORD
+printf '\n'
+export IMAP_AGENT_CLI_PASSWORD
+uvx imap-agent-cli setup --non-interactive
 ```
 
-The config file is stored at `~/.imap-agent-cli/config.toml`. Keep passwords in environment variables. Profiles store the name of the password environment variable, not the password itself.
+These variables affect the current shell and its children. An already-running agent does not inherit later changes. Setup uses an environment password without saving its value. Secure defaults supply port `993`, `tls=true`, and `ssl_mode=required`.
 
-The CLI uses standard IMAP username and password authentication. It does not provide OAuth setup. Providers that disable account-password login may require an app password.
+The existing `config init`, `config add-profile`, and `config set-default-profile` commands remain available. `config init` creates a starter file. Prefer `setup` to complete onboarding. Existing `password_env` references continue to work.
 
-Inspect resolved settings without exposing secrets, or list available profiles:
+### Check configuration
 
 ```text
-uvx imap-agent-cli config show
-uvx imap-agent-cli profiles
-uvx imap-agent-cli config check --profile work
+uvx imap-agent-cli config check
+uvx imap-agent-cli config check --profile work --format plain
+uvx imap-agent-cli config check --local
 ```
 
-Pass `--profile NAME` to any mailbox command to select a non-default profile. Direct commands also accept connection flags and `--password-stdin` for one-off use.
+Checks never write configuration, credentials, or skills. The network check verifies login, opens the default mailbox read-only, and checks bounded metadata access. It never reads bodies or appends a test message. Missing Drafts is a warning for reading. Finding Drafts does not verify append permission or quota. An empty mailbox leaves metadata fetching untested.
+
+Use `--config PATH` or `IMAP_AGENT_CLI_CONFIG` for another configuration file. Use `--credentials-file PATH` or `IMAP_AGENT_CLI_CREDENTIALS_FILE` for a separate credential file. Explicit paths work with setup, diagnostics, and mailbox commands. Relative command-line paths resolve from the working directory. Setup saves an explicitly selected credential file path for later use. Custom skill locations use `--skills-dir PATH`.
 
 ### Connection security
 
@@ -261,7 +284,7 @@ uvx imap-agent-cli skill status
 uvx imap-agent-cli skill status --format plain
 ```
 
-Normal invocations of an installed CLI update a pristine older managed skill to the running CLI version. Synchronization is local. It does not query PyPI, refresh uv's cache, or update the CLI. Missing skills are never installed automatically. Unmanaged, modified, equal-version, and newer skills are preserved.
+Normal mailbox invocations and top-level help, version, and about commands of an installed CLI update a pristine older managed skill to the running CLI version. Synchronization is local. It does not query PyPI, refresh uv's cache, or update the CLI. Missing skills are never installed automatically. Unmanaged, modified, equal-version, and newer skills are preserved.
 
 Restore altered managed content explicitly:
 
@@ -301,7 +324,7 @@ uvx imap-agent-cli draft create --json draft.json
 uvx imap-agent-cli draft reply --json reply.json
 ```
 
-Use `--json -` to read the JSON request from stdin. Failures leave stdout empty and write a compact JSON error to stderr. Logs do not include passwords, message bodies, or attachment content.
+Use `--json -` to read the JSON request from stdin. Operational failures leave stdout empty and write a compact JSON error to stderr. Setup and configuration checks return structured readiness reports when verification or a later step fails. Check the exit status and the `ready` or `ok` field. Human diagnostics go to stderr. Add `--format plain` to setup or config check for a readable report. Logs do not include passwords, message bodies, or attachment content.
 
 Default guardrails keep work bounded:
 
@@ -320,6 +343,7 @@ Commands expose targeted overrides such as `--max-results`, `--max-scan`, `--max
 
 | Command | Purpose |
 | --- | --- |
+| `setup` | Verify and save an account, then install the managed skill |
 | `config` | Initialize, inspect, validate, and manage profile configuration |
 | `profiles` | List configured profile names |
 | `skill` | Install, inspect, or remove the managed agent skill |

imap_agent_cli-0.3.0/docs/setup.md

@@ -0,0 +1,127 @@
+# Setup and credentials
+
+Run `uvx imap-agent-cli setup` in your own terminal. The tool prompts only for missing settings and credentials. Password input is masked with asterisks. It never requests a secret in agent chat.
+
+## Provider requirements
+
+| Provider | Credential and creation steps | Renewal |
+| --- | --- | --- |
+| Generic IMAP | Ask your provider for its IMAP hostname, login identity, and authentication requirements. Prefer an app password when offered. An administrator may need to enable IMAP. | Follow the provider's expiration and revocation policy. There is no universal IMAP credential lifetime. |
+| Gmail | Enable 2-Step Verification. Open [Google App Passwords](https://myaccount.google.com/apppasswords) and create one named imap-agent-cli. The server is `imap.gmail.com:993`. | Google revokes app passwords when the account password changes. Generate a replacement. There is no refresh-token flow or configurable expiry in this tool. |
+| Google Workspace | App passwords are usable only when account and organization policy permit them. Administrators control IMAP access and allowed clients. Do not enable legacy less-secure-app access. | Administrator policy or account changes may require a new credential or prevent this authentication method entirely. |
+| Fastmail | Open Settings, Privacy & Security, then Connected apps & API tokens. Create an app password with mail-only access. Use `imap.fastmail.com:993` and your Fastmail login address. Your plan must support third-party IMAP clients. | Replace the credential if disabled or removed. The reviewed guidance gives no fixed expiration. Ordinary Fastmail passwords do not work. |
+| iCloud | Enable two-factor authentication. At [Apple Account](https://account.apple.com/), open Sign-In and Security, then App-Specific Passwords. Generate a password named imap-agent-cli. Use `imap.mail.me.com:993`. | Changing or resetting the primary Apple Account password revokes app-specific passwords. Generate a replacement. |
+| Microsoft 365 and Outlook.com | Unsupported. These services require OAuth. The tool does not register a Microsoft application or implement OAuth. Microsoft app passwords are not a workaround. | Not applicable. |
+
+Google recommends OAuth when supported. App passwords may be unavailable for Advanced Protection, security-key-only 2-Step Verification, or organization accounts. Personal Gmail always enables IMAP. Workspace administrators control it separately. Apple documents both short and full-address IMAP usernames. Use `--username` to correct a login identity and `--sender` when the draft sender address differs from it.
+
+Official requirements:
+
+- [Google app passwords](https://support.google.com/accounts/answer/185833?hl=en)
+- [Gmail client access](https://support.google.com/mail/answer/7126229?hl=en)
+- [Google IMAP endpoint](https://developers.google.com/workspace/gmail/imap/imap-smtp)
+- [Workspace app-password exception](https://knowledge.workspace.google.com/admin/sync/transition-from-less-secure-apps-to-oauth)
+- [Workspace administrator controls](https://knowledge.workspace.google.com/admin/sync/turn-pop-and-imap-on-or-off-for-users)
+- [Fastmail app passwords](https://www.fastmail.help/hc/en-us/articles/360058752854-App-passwords)
+- [Fastmail server settings](https://www.fastmail.help/hc/en-us/articles/1500000278342-Server-names-and-ports)
+- [Apple app-specific passwords](https://support.apple.com/en-us/102654)
+- [iCloud server settings](https://support.apple.com/en-us/102525)
+- [Exchange Online authentication requirements](https://learn.microsoft.com/en-us/exchange/clients-and-mobile-in-exchange-online/deprecation-of-basic-authentication-exchange-online)
+- [Outlook.com IMAP requirements](https://support.microsoft.com/en-US/Outlook/pop-imap-and-smtp-settings-for-outlook-com)
+
+Provider presets are connection hints, not a claim that a particular account was tested. Custom domains do not identify their IMAP server reliably. Setup never sends credentials to a guessed server or fetches a webmail URL.
+
+## Permissions and verification
+
+Reading needs mailbox lookup and read access. On servers implementing standard IMAP ACLs, these are `l` and `r`. Draft append needs `i` on the selected Drafts folder. The current draft command does not request flags during append. The CLI needs no SMTP sending permission, deletion permission, or folder-management permission. See [IMAP ACL rights](https://www.rfc-editor.org/rfc/rfc4314.html#section-2.1).
+
+Provider app passwords may grant broader access, including writes and sending through another program. The CLI enforces its own restrictions. The credential itself is not necessarily read-only.
+
+Setup and `config check` authenticate, inspect capabilities and folder names, open the default mailbox with `EXAMINE`, and inspect at most one message's metadata. The search covers at most 250 possible UIDs. No message body or attachment is fetched. No draft is appended. An empty mailbox or unavailable UIDNEXT leaves metadata fetching untested. Missing or ambiguous Drafts is advisory for reading.
+
+Verification uses configured connection and read timeouts, a 60-second operation budget after sign-in, and a limit of 1000 returned folders. These are socket timeouts, not a hard wall-clock limit on DNS resolution or a server that sends a slow continuous response. The IMAP library materializes the LIST response before the folder count is checked. This is not a streaming response-size limit.
+
+`EXAMINE` avoids changing permanent mailbox state, including `\Recent`. Fetches in ordinary read commands use `BODY.PEEK`. There is no read-write selection fallback. See [IMAP read-only selection](https://www.rfc-editor.org/rfc/rfc3501.html#section-6.3.2).
+
+Success establishes only the tested operations from the current execution environment. It does not establish draft append permission, quota, message-body rendering, attachment download, access to every folder, or future credential validity. Sign-in can create provider audit records or security notifications.
+
+## Storage and precedence
+
+Ordinary settings live in `~/.imap-agent-cli/config.toml`. Entered credentials live in the separate `credentials.toml`. Profile records contain credential references, never passwords. Saved credentials are bound to the hostname, port, username, transport settings, and authentication method. An endpoint override cannot silently reuse a saved credential for another endpoint.
+
+Files use normal inherited ACLs and the process umask. The tool does not require a keyring, change permissions, or encrypt these files. Keep them outside repositories and shared exports. A stolen credential may grant more access than the CLI exposes.
+
+Connection settings resolve from flags or the supplied setup target, non-empty environment overrides, the selected saved profile, then built-in defaults. This makes environment settings explicit overrides, including when a saved default profile exists. Password resolution is:
+
+1. Explicit `--password-stdin` input.
+2. The selected profile's `password_env` variable.
+3. `IMAP_AGENT_CLI_PASSWORD`.
+4. A matching saved credential.
+
+Environment passwords are never automatically saved. A rejected credential does not trigger another source. A valid environment or stdin credential can bypass an unavailable credentials file. Password characters are preserved, including whitespace.
+
+Use `--config PATH` or `IMAP_AGENT_CLI_CONFIG` for a different configuration. Use `--credentials-file PATH` or `IMAP_AGENT_CLI_CREDENTIALS_FILE` for credentials. Explicit path flags override path variables. Relative CLI paths are relative to the working directory. A relative credential path saved in a profile is relative to the configuration directory. An explicit setup `--credentials-file` is saved as an absolute profile reference. A path environment override must also be present in later executions.
+
+Replacement verifies before saving. The credential record is staged first, then the profile pointer commits atomically. A failed configuration write cannot replace the credential used by the old profile. Superseded records in the same file that are unreferenced by other profiles in the same configuration are removed after commit. Switching credential files preserves the old file. Use a separate credentials file for each independent configuration file. Do not share internal credential identifiers across independent configurations.
+
+File locks coordinate simultaneous CLI writers. Concurrent changes detected before replacement abort the write. Lock files may remain alongside the TOML files. They contain no credentials. Configuration updates preserve unrelated tables, comments, and profiles. An external editor does not participate in the CLI's advisory locking.
+
+## Repair setup
+
+Inspect without modifying local files:
+
+```text
+uvx imap-agent-cli config check --profile work --format plain
+uvx imap-agent-cli config check --profile work --local
+```
+
+Replace a saved password in your terminal:
+
+```text
+uvx imap-agent-cli setup --profile work --replace-password
+```
+
+If an environment override is active, unset it first. The diagnostic identifies the exact variable. For the global variable:
+
+PowerShell:
+
+```powershell
+Remove-Item Env:IMAP_AGENT_CLI_PASSWORD -ErrorAction SilentlyContinue
+uvx imap-agent-cli setup --profile work --replace-password
+```
+
+Bash:
+
+```bash
+unset IMAP_AGENT_CLI_PASSWORD
+uvx imap-agent-cli setup --profile work --replace-password
+```
+
+Correct a connection or folder:
+
+```text
+uvx imap-agent-cli setup --profile work --host imap.example.com
+uvx imap-agent-cli setup --profile work --default-folder INBOX
+uvx imap-agent-cli setup --profile work --drafts-folder "Drafts"
+```
+
+Changing the endpoint with a saved credential requires an explicit replacement credential. TLS certificate errors need a corrected hostname, trust configuration, or network route. Do not disable encryption as a repair.
+
+Inspect a protected skill before deciding whether to replace it:
+
+```text
+uvx imap-agent-cli skill status --format plain
+uvx imap-agent-cli skill install
+```
+
+Setup never forces a skill replacement. Modified and unmanaged skills are preserved. Explicit `skill install --force` still refuses unmanaged content and newer versions. Use `--skills-dir PATH` consistently for custom skill roots.
+
+## Agent execution
+
+Mailbox commands never prompt. `setup --non-interactive` fails without writing account settings when required input is missing. It uses provisioned environment or file credentials. Explicit `--password-stdin` can accept a credential from a trusted secret source and saves it during setup. Never put a literal credential in a shell command. Do not combine credential stdin with JSON stdin.
+
+Setup does not persist shell variables. An already-running desktop agent does not receive environment changes from another terminal. Sandboxes need access to the selected files and IMAP network endpoint. Remote hosts and containers need their own runtime and credentials, preferably a separate app password per host. Do not automatically copy secrets between hosts. The CLI does not infer that terminal permissions apply to an agent.
+
+A successful CLI check does not prove that the harness loaded the installed skill. Start a new agent session if needed. The agent should use diagnostics rather than open credential files. A missing skill is reported separately from mailbox readiness.
+
+Initial uv package resolution needs access to package and Python downloads. Offline execution requires a provisioned runtime or a usable cache. The managed skill does not automatically update the CLI.

{imap_agent_cli-0.2.1 → imap_agent_cli-0.3.0}/imap_agent_cli.py

@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.11"
+# requires-python = ">=3.11,<3.14"
 # dependencies = [
 #   "IMAPClient>=3.0.0",
 #   "beautifulsoup4>=4.12.0",
@@ -7,6 +7,9 @@
 #   "markdownify>=0.14.0",
 #   "packaging>=23.2",
 #   "PyYAML>=6.0",
+#   "prompt-toolkit>=3.0.43",
+#   "tomlkit>=0.13.0",
+#   "filelock>=3.16.0",
 # ]
 # ///
 """Local development wrapper for imap-agent-cli."""

{imap_agent_cli-0.2.1 → imap_agent_cli-0.3.0}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "hatchling.build"
 
 [project]
 name = "imap-agent-cli"
-version = "0.2.1"
+version = "0.3.0"
 description = "Agent-first IMAP CLI for safe email search, read, attachment download, and draft creation"
 readme = "README.md"
 license = "MIT"
-requires-python = ">=3.11"
+requires-python = ">=3.11,<3.14"
 authors = [
   { name = "Paul" },
 ]
@@ -34,6 +34,9 @@ dependencies = [
   "markdownify>=0.14.0",
   "packaging>=23.2",
   "PyYAML>=6.0",
+  "prompt-toolkit>=3.0.43",
+  "tomlkit>=0.13.0",
+  "filelock>=3.16.0",
 ]
 
 [project.optional-dependencies]