imap-agent-cli 0.1.3__tar.gz → 0.1.4__tar.gz

imap_agent_cli-0.1.4/AGENTS.md

@@ -0,0 +1,88 @@
+# Agent Instructions
+
+## Project Purpose
+
+`imap-agent-cli` is a Python CLI for safe agentic email access over generic IMAP. It can search mailboxes, read messages without marking them read, inspect or download attachments when explicitly requested, and append messages to Drafts.
+
+The core safety boundary is strict: never add support for sending email, deleting messages, moving messages, archiving messages, labeling messages, flagging messages, starring messages, marking messages read/unread, or creating/deleting/renaming folders.
+
+## Repository Layout
+
+- `imap_agent_cli.py` is the root local-development wrapper with PEP 723 metadata.
+- `src/imap_agent_cli/cli.py` owns argument parsing and command dispatch.
+- `src/imap_agent_cli/config.py` owns env-var and profile config behavior.
+- `src/imap_agent_cli/imap_client.py` owns IMAP interactions.
+- `src/imap_agent_cli/mime.py` owns MIME parsing and draft composition.
+- `src/imap_agent_cli/render.py` owns body format rendering and sanitization.
+- `src/imap_agent_cli/search.py` owns search criteria construction.
+- `src/imap_agent_cli/skill.py` owns the installed `imap` skill text.
+- `tests/` contains unit tests and the opt-in local `pymap` integration test.
+- `spec.md` is the product behavior target.
+
+## Development Rules
+
+- Keep the PyPI package name, GitHub repository name, and console command aligned as `imap-agent-cli`.
+- 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 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.
+
+## Safety-Sensitive Implementation Notes
+
+- Reads must avoid changing message state. Preserve no-seen fetch behavior.
+- Draft creation is allowed only by appending a new MIME message to the detected or configured Drafts folder.
+- Reply drafts should preserve appropriate reply headers such as `In-Reply-To` and `References`.
+- Attachment downloads require explicit user/agent intent and an output directory.
+- Folder-wide or all-folder operations should remain bounded by defaults and overridable limits.
+- HTML email is untrusted input. Sanitize before returning HTML and keep Markdown conversion intentionally lossy but predictable.
+
+## Common Commands
+
+Run the CLI locally:
+
+```text
+uv run ./imap_agent_cli.py --help
+uv run ./imap_agent_cli.py folders
+uv run ./imap_agent_cli.py search --subject invoice
+```
+
+Run no-network tests:
+
+```text
+python -m unittest discover -v
+```
+
+Run the optional local IMAP integration test:
+
+```text
+uv run --extra test python -m unittest tests.test_pymap_integration -v
+```
+
+Set `IMAP_AGENT_CLI_TEST_PYMAP=1` in the shell before running the integration test. The test starts `pymap dict --demo-data` locally and logs in with demo credentials.
+
+Build the package:
+
+```text
+uv build --no-sources
+```
+
+## Publishing Notes
+
+- Package metadata lives in `pyproject.toml`.
+- The GitHub Actions publish workflow is `.github/workflows/publish.yml`.
+- PyPI Trusted Publishing uses:
+  - Project: `imap-agent-cli`
+  - Owner: `pseudosavant`
+  - Repository: `imap-agent-cli`
+  - Workflow: `publish.yml`
+  - Environment: `pypi`
+
+## Before Finishing Changes
+
+- Run the smallest relevant tests for the change.
+- For broad behavior changes, run `python -m unittest discover -v`.
+- For packaging or release changes, also run `uv build --no-sources`.
+- Check `git status --short` and mention any uncommitted or unverified work.

{imap_agent_cli-0.1.3 → imap_agent_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: imap-agent-cli
-Version: 0.1.3
+Version: 0.1.4
 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
@@ -37,79 +37,98 @@ Description-Content-Type: text/markdown
 
 It can inspect mailboxes and append messages to Drafts. It cannot send email, delete messages, move messages, archive messages, change labels, alter flags, or mark messages read/unread.
 
-## Status
+## Using imap-agent-cli
 
-This repo is under active development. The behavior target is defined in [`spec.md`](./spec.md).
+### Quick Start
+
+Install or update the `imap` agent skill:
 
-## Quick Start
+```text
+uvx imap-agent-cli install-skill
+```
 
-Single-profile env-var setup:
+Configure the default IMAP account with environment variables:
 
 ```text
 IMAP_AGENT_CLI_HOST=imap.example.com
 IMAP_AGENT_CLI_PORT=993
 IMAP_AGENT_CLI_USERNAME=me@example.com
-IMAP_AGENT_CLI_PASSWORD=...
+IMAP_AGENT_CLI_PASSWORD=your-password-or-app-password
 IMAP_AGENT_CLI_TLS=true
 ```
 
-Local development:
+Then ask your agentic tool to use the `imap` skill for mailbox search, email reading, attachment inspection/download, or draft creation.
+
+### Use From PyPI
+
+Use the published CLI directly with `uvx`:
 
 ```text
-uv run ./imap_agent_cli.py --help
-uv run ./imap_agent_cli.py folders
-uv run ./imap_agent_cli.py search --subject invoice
+uvx imap-agent-cli --help
+uvx imap-agent-cli folders
+uvx imap-agent-cli search --subject invoice
 ```
 
-Packaged execution:
+Install it as a persistent `uv` tool when you want to call `imap-agent-cli` directly:
 
 ```text
-uvx imap-agent-cli --help
+uv tool install imap-agent-cli
+uv tool update-shell
+imap-agent-cli --help
 ```
 
-## Examples
+Restart your shell after `uv tool update-shell` if `imap-agent-cli` is not found.
+
+Or install it into a Python environment:
 
 ```text
-imap-agent-cli folders
-imap-agent-cli search --folder INBOX --subject "invoice" --max-results 10
-imap-agent-cli read --folder INBOX --uid 12345 --body-format html
-imap-agent-cli attachments --folder INBOX --uid 12345
-imap-agent-cli attachments download --folder INBOX --uid 12345 --part-id 2 --output-dir ./email-attachments
-imap-agent-cli draft create --to person@example.com --subject "Hello" --body "Draft only."
-imap-agent-cli draft reply --folder INBOX --uid 12345 --body "Thanks. I will review this."
+python -m pip install imap-agent-cli
+imap-agent-cli --help
 ```
 
 All command payloads are JSON on stdout. Diagnostics and errors go to stderr.
 
-## Config
+Use `imap-agent-cli --about` for project URL and license attribution. Use `imap-agent-cli --version` to print only the version number.
+
+### Configuration
 
-Create a starter config:
+For a single account, environment variables are enough:
 
 ```text
-imap-agent-cli config init
+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_DRAFTS_FOLDER=Drafts
 ```
 
-Add a named profile:
+`IMAP_AGENT_CLI_DRAFTS_FOLDER` is optional. When omitted, the CLI tries to auto-detect the Drafts folder.
+
+For multiple accounts, create a config file:
 
 ```text
+imap-agent-cli config init
 imap-agent-cli config add-profile work --host imap.example.com --port 993 --username me@example.com --password-env IMAP_AGENT_CLI_WORK_PASSWORD
 imap-agent-cli config set-default-profile work
 ```
 
-Config path:
+The config file is stored at:
 
 ```text
 ~/.imap-agent-cli/config.toml
 ```
 
-Secrets should stay in environment variables, not the config file.
+Keep secrets in environment variables. The config file should reference password environment variable names, not contain passwords.
 
-## Agent Skill
+### Agent Skill
+
+The installed skill teaches an agentic tool how to use `imap-agent-cli` safely and effectively.
 
 Install or update the user-scoped `imap` skill:
 
 ```text
-imap-agent-cli install-skill
+uvx imap-agent-cli install-skill
 ```
 
 This writes:
@@ -121,16 +140,16 @@ This writes:
 Remove the managed skill:
 
 ```text
-imap-agent-cli remove-skill
+uvx imap-agent-cli remove-skill
 ```
 
-Use `--skills-dir PATH` to install into a nonstandard skills directory, for example:
+Use `--skills-dir PATH` to install into a nonstandard skills directory:
 
 ```text
-imap-agent-cli install-skill --skills-dir ~/.agents/skills
+uvx imap-agent-cli install-skill --skills-dir ~/.agents/skills
 ```
 
-## Safety Boundary
+### Safety Boundary
 
 Allowed:
 
@@ -150,32 +169,61 @@ Not allowed:
 - mark read/unread
 - create/delete/rename folders
 
-## Testing
+### Example Commands
 
-No-network unit tests:
+These examples are mostly useful for validating configuration or debugging what an agentic tool is doing:
 
 ```text
-python -m unittest discover -v
+imap-agent-cli folders
+imap-agent-cli search --folder INBOX --subject "invoice" --max-results 10
+imap-agent-cli read --folder INBOX --uid 12345 --body-format html
+imap-agent-cli attachments --folder INBOX --uid 12345
+imap-agent-cli attachments download --folder INBOX --uid 12345 --part-id 2 --output-dir ./email-attachments
+imap-agent-cli draft create --to person@example.com --subject "Hello" --body "Draft only."
+imap-agent-cli draft reply --folder INBOX --uid 12345 --body "Thanks. I will review this."
 ```
 
-Package build:
+## Development
+
+### Local Development
+
+Run the CLI from the repository:
+
+```text
+uv run ./imap_agent_cli.py --help
+uv run ./imap_agent_cli.py folders
+uv run ./imap_agent_cli.py search --subject invoice
+```
+
+Build the package:
 
 ```text
 uv build --no-sources
 ```
 
-The spec targets `pymap` for future local IMAP integration tests on Windows without Docker.
+### Testing
 
-Opt-in local IMAP integration test:
+Run no-network unit tests:
+
+```text
+python -m unittest discover -v
+```
+
+Run the opt-in local IMAP integration test:
+
+Set `IMAP_AGENT_CLI_TEST_PYMAP=1` in your shell, then run:
 
 ```text
-$env:IMAP_AGENT_CLI_TEST_PYMAP = "1"
 uv run --extra test python -m unittest tests.test_pymap_integration -v
 ```
 
 The integration test starts `pymap dict --demo-data` locally and logs in with `demouser` / `demopass`.
 
-## Publishing
+### Project Status
+
+This repo is under active development. The behavior target is defined in [`spec.md`](./spec.md).
+
+### Publishing
 
 The GitHub Actions workflow is `.github/workflows/publish.yml`.
 

{imap_agent_cli-0.1.3 → imap_agent_cli-0.1.4}/README.md

@@ -4,79 +4,98 @@
 
 It can inspect mailboxes and append messages to Drafts. It cannot send email, delete messages, move messages, archive messages, change labels, alter flags, or mark messages read/unread.
 
-## Status
+## Using imap-agent-cli
 
-This repo is under active development. The behavior target is defined in [`spec.md`](./spec.md).
+### Quick Start
+
+Install or update the `imap` agent skill:
 
-## Quick Start
+```text
+uvx imap-agent-cli install-skill
+```
 
-Single-profile env-var setup:
+Configure the default IMAP account with environment variables:
 
 ```text
 IMAP_AGENT_CLI_HOST=imap.example.com
 IMAP_AGENT_CLI_PORT=993
 IMAP_AGENT_CLI_USERNAME=me@example.com
-IMAP_AGENT_CLI_PASSWORD=...
+IMAP_AGENT_CLI_PASSWORD=your-password-or-app-password
 IMAP_AGENT_CLI_TLS=true
 ```
 
-Local development:
+Then ask your agentic tool to use the `imap` skill for mailbox search, email reading, attachment inspection/download, or draft creation.
+
+### Use From PyPI
+
+Use the published CLI directly with `uvx`:
 
 ```text
-uv run ./imap_agent_cli.py --help
-uv run ./imap_agent_cli.py folders
-uv run ./imap_agent_cli.py search --subject invoice
+uvx imap-agent-cli --help
+uvx imap-agent-cli folders
+uvx imap-agent-cli search --subject invoice
 ```
 
-Packaged execution:
+Install it as a persistent `uv` tool when you want to call `imap-agent-cli` directly:
 
 ```text
-uvx imap-agent-cli --help
+uv tool install imap-agent-cli
+uv tool update-shell
+imap-agent-cli --help
 ```
 
-## Examples
+Restart your shell after `uv tool update-shell` if `imap-agent-cli` is not found.
+
+Or install it into a Python environment:
 
 ```text
-imap-agent-cli folders
-imap-agent-cli search --folder INBOX --subject "invoice" --max-results 10
-imap-agent-cli read --folder INBOX --uid 12345 --body-format html
-imap-agent-cli attachments --folder INBOX --uid 12345
-imap-agent-cli attachments download --folder INBOX --uid 12345 --part-id 2 --output-dir ./email-attachments
-imap-agent-cli draft create --to person@example.com --subject "Hello" --body "Draft only."
-imap-agent-cli draft reply --folder INBOX --uid 12345 --body "Thanks. I will review this."
+python -m pip install imap-agent-cli
+imap-agent-cli --help
 ```
 
 All command payloads are JSON on stdout. Diagnostics and errors go to stderr.
 
-## Config
+Use `imap-agent-cli --about` for project URL and license attribution. Use `imap-agent-cli --version` to print only the version number.
+
+### Configuration
 
-Create a starter config:
+For a single account, environment variables are enough:
 
 ```text
-imap-agent-cli config init
+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_DRAFTS_FOLDER=Drafts
 ```
 
-Add a named profile:
+`IMAP_AGENT_CLI_DRAFTS_FOLDER` is optional. When omitted, the CLI tries to auto-detect the Drafts folder.
+
+For multiple accounts, create a config file:
 
 ```text
+imap-agent-cli config init
 imap-agent-cli config add-profile work --host imap.example.com --port 993 --username me@example.com --password-env IMAP_AGENT_CLI_WORK_PASSWORD
 imap-agent-cli config set-default-profile work
 ```
 
-Config path:
+The config file is stored at:
 
 ```text
 ~/.imap-agent-cli/config.toml
 ```
 
-Secrets should stay in environment variables, not the config file.
+Keep secrets in environment variables. The config file should reference password environment variable names, not contain passwords.
 
-## Agent Skill
+### Agent Skill
+
+The installed skill teaches an agentic tool how to use `imap-agent-cli` safely and effectively.
 
 Install or update the user-scoped `imap` skill:
 
 ```text
-imap-agent-cli install-skill
+uvx imap-agent-cli install-skill
 ```
 
 This writes:
@@ -88,16 +107,16 @@ This writes:
 Remove the managed skill:
 
 ```text
-imap-agent-cli remove-skill
+uvx imap-agent-cli remove-skill
 ```
 
-Use `--skills-dir PATH` to install into a nonstandard skills directory, for example:
+Use `--skills-dir PATH` to install into a nonstandard skills directory:
 
 ```text
-imap-agent-cli install-skill --skills-dir ~/.agents/skills
+uvx imap-agent-cli install-skill --skills-dir ~/.agents/skills
 ```
 
-## Safety Boundary
+### Safety Boundary
 
 Allowed:
 
@@ -117,32 +136,61 @@ Not allowed:
 - mark read/unread
 - create/delete/rename folders
 
-## Testing
+### Example Commands
 
-No-network unit tests:
+These examples are mostly useful for validating configuration or debugging what an agentic tool is doing:
 
 ```text
-python -m unittest discover -v
+imap-agent-cli folders
+imap-agent-cli search --folder INBOX --subject "invoice" --max-results 10
+imap-agent-cli read --folder INBOX --uid 12345 --body-format html
+imap-agent-cli attachments --folder INBOX --uid 12345
+imap-agent-cli attachments download --folder INBOX --uid 12345 --part-id 2 --output-dir ./email-attachments
+imap-agent-cli draft create --to person@example.com --subject "Hello" --body "Draft only."
+imap-agent-cli draft reply --folder INBOX --uid 12345 --body "Thanks. I will review this."
 ```
 
-Package build:
+## Development
+
+### Local Development
+
+Run the CLI from the repository:
+
+```text
+uv run ./imap_agent_cli.py --help
+uv run ./imap_agent_cli.py folders
+uv run ./imap_agent_cli.py search --subject invoice
+```
+
+Build the package:
 
 ```text
 uv build --no-sources
 ```
 
-The spec targets `pymap` for future local IMAP integration tests on Windows without Docker.
+### Testing
 
-Opt-in local IMAP integration test:
+Run no-network unit tests:
+
+```text
+python -m unittest discover -v
+```
+
+Run the opt-in local IMAP integration test:
+
+Set `IMAP_AGENT_CLI_TEST_PYMAP=1` in your shell, then run:
 
 ```text
-$env:IMAP_AGENT_CLI_TEST_PYMAP = "1"
 uv run --extra test python -m unittest tests.test_pymap_integration -v
 ```
 
 The integration test starts `pymap dict --demo-data` locally and logs in with `demouser` / `demopass`.
 
-## Publishing
+### Project Status
+
+This repo is under active development. The behavior target is defined in [`spec.md`](./spec.md).
+
+### Publishing
 
 The GitHub Actions workflow is `.github/workflows/publish.yml`.
 

{imap_agent_cli-0.1.3 → imap_agent_cli-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "imap-agent-cli"
-version = "0.1.3"
+version = "0.1.4"
 description = "Agent-first IMAP CLI for safe email search, read, attachment download, and draft creation"
 readme = "README.md"
 license = "MIT"

{imap_agent_cli-0.1.3 → imap_agent_cli-0.1.4}/src/imap_agent_cli/__init__.py

@@ -1,3 +1,3 @@
 """Agent-first IMAP CLI."""
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"

{imap_agent_cli-0.1.3 → imap_agent_cli-0.1.4}/src/imap_agent_cli/cli.py

@@ -15,6 +15,68 @@ from .render import write_error, write_json
 from .skill import install_skill, remove_skill
 
 
+PROJECT_URL = "https://github.com/pseudosavant/imap-agent-cli"
+LICENSE_NAME = "MIT"
+
+TOP_LEVEL_HELP = f"""imap-agent-cli - safe IMAP email access for agentic tools
+
+Safety:
+  Can: list folders, search, read without marking read, inspect/download attachments, create Drafts
+  Cannot: send, delete, move, archive, label, flag, mark read/unread
+
+Setup:
+  Required env vars for the default profile:
+    IMAP_AGENT_CLI_HOST
+    IMAP_AGENT_CLI_PORT
+    IMAP_AGENT_CLI_USERNAME
+    IMAP_AGENT_CLI_PASSWORD
+    IMAP_AGENT_CLI_TLS
+
+Common workflows:
+  imap-agent-cli folders
+  imap-agent-cli search --folder INBOX --from "Justin" --max-results 10
+  imap-agent-cli read --folder INBOX --uid 12345 --body-format metadata
+  imap-agent-cli read --folder INBOX --uid 12345 --body-format html --max-body-chars 12000
+  imap-agent-cli attachments --folder INBOX --uid 12345
+  imap-agent-cli attachments download --folder INBOX --uid 12345 --part-id 2 --output-dir ./email-attachments
+  imap-agent-cli draft create --to person@example.com --subject "Subject" --body-file ./draft.txt
+  imap-agent-cli draft reply --folder INBOX --uid 12345 --body-file ./reply.txt
+
+Output:
+  stdout is JSON payload only for operational commands
+  stderr is diagnostics/errors only
+
+Commands:
+  config          initialize and manage profile configuration
+  profiles        list configured profile names
+  install-skill   install or update the imap agent skill
+  remove-skill    remove the managed imap agent skill
+  folders         list folders
+  search          search messages
+  read            read a message by folder and UID
+  attachments     list or download attachments
+  draft           create new or reply drafts
+
+More help:
+  imap-agent-cli <command> --help
+  imap-agent-cli --about
+  imap-agent-cli --version
+
+Project:
+  {PROJECT_URL}
+License:
+  {LICENSE_NAME}
+"""
+
+ABOUT_TEXT = f"""imap-agent-cli {__version__}
+
+Safe IMAP email access for agentic tools.
+
+Project: {PROJECT_URL}
+License: {LICENSE_NAME}
+"""
+
+
 def _read_json_arg(value: str) -> dict[str, Any]:
     if value == "-":
         text = sys.stdin.read()
@@ -287,21 +349,25 @@ def cmd_draft_reply(args: argparse.Namespace) -> int:
 
 
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="imap-agent-cli")
-    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    parser = argparse.ArgumentParser(
+        prog="imap-agent-cli",
+        description="Safe IMAP email access for agentic tools.",
+    )
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.add_argument("--about", action="store_true", help="show project and license information and exit")
     sub = parser.add_subparsers(dest="command", required=True)
 
-    config = sub.add_parser("config")
+    config = sub.add_parser("config", help="initialize and manage profile configuration")
     config_sub = config.add_subparsers(dest="config_command", required=True)
-    config_init = config_sub.add_parser("init")
+    config_init = config_sub.add_parser("init", help="create a starter config file")
     config_init.add_argument("--from-env", action="store_true")
     config_init.set_defaults(func=cmd_config)
-    config_show = config_sub.add_parser("show")
+    config_show = config_sub.add_parser("show", help="show resolved config metadata without secrets")
     config_show.set_defaults(func=cmd_config)
-    config_default = config_sub.add_parser("set-default-profile")
+    config_default = config_sub.add_parser("set-default-profile", help="set the default profile")
     config_default.add_argument("name")
     config_default.set_defaults(func=cmd_config)
-    config_add = config_sub.add_parser("add-profile")
+    config_add = config_sub.add_parser("add-profile", help="add or update a named profile")
     config_add.add_argument("name")
     config_add.add_argument("--host", required=True)
     config_add.add_argument("--port", type=int, default=993)
@@ -312,27 +378,27 @@ def build_parser() -> argparse.ArgumentParser:
     config_add.add_argument("--ssl-mode", choices=["required", "preferred", "disabled"], default="required")
     config_add.add_argument("--drafts-folder", default="")
     config_add.set_defaults(func=cmd_config)
-    config_remove = config_sub.add_parser("remove-profile")
+    config_remove = config_sub.add_parser("remove-profile", help="remove a named profile from config")
     config_remove.add_argument("name")
     config_remove.set_defaults(func=cmd_config)
 
-    profiles = sub.add_parser("profiles")
+    profiles = sub.add_parser("profiles", help="list configured profile names")
     profiles.set_defaults(func=cmd_profiles)
 
-    install_skill_parser = sub.add_parser("install-skill")
+    install_skill_parser = sub.add_parser("install-skill", help="install or update the imap agent skill")
     install_skill_parser.add_argument("--skills-dir")
     install_skill_parser.set_defaults(func=cmd_install_skill)
 
-    remove_skill_parser = sub.add_parser("remove-skill")
+    remove_skill_parser = sub.add_parser("remove-skill", help="remove the managed imap agent skill")
     remove_skill_parser.add_argument("--skills-dir")
     remove_skill_parser.add_argument("--force", action="store_true")
     remove_skill_parser.set_defaults(func=cmd_remove_skill)
 
-    folders = sub.add_parser("folders")
+    folders = sub.add_parser("folders", help="list folders and folder metadata")
     _common_profile_args(folders)
     folders.set_defaults(func=cmd_folders)
 
-    search = sub.add_parser("search")
+    search = sub.add_parser("search", help="search messages by folder, subject, sender, or date range")
     _common_profile_args(search)
     search.add_argument("--json", dest="json_input")
     search.add_argument("--folder")
@@ -345,7 +411,7 @@ def build_parser() -> argparse.ArgumentParser:
     search.add_argument("--max-results", type=int)
     search.set_defaults(func=cmd_search)
 
-    read = sub.add_parser("read")
+    read = sub.add_parser("read", help="read a message by folder and UID without marking it read")
     _common_profile_args(read)
     read.add_argument("--json", dest="json_input")
     read.add_argument("--folder")
@@ -354,13 +420,13 @@ def build_parser() -> argparse.ArgumentParser:
     read.add_argument("--max-body-chars", type=int)
     read.set_defaults(func=cmd_read)
 
-    attachments = sub.add_parser("attachments")
+    attachments = sub.add_parser("attachments", help="list attachment metadata for a message")
     _common_profile_args(attachments)
     attachments.add_argument("--folder")
     attachments.add_argument("--uid", type=int)
     attachments.set_defaults(func=cmd_attachments)
     attachments_sub = attachments.add_subparsers(dest="attachment_command")
-    download = attachments_sub.add_parser("download")
+    download = attachments_sub.add_parser("download", help="download selected attachments to a directory")
     _common_profile_args(download)
     download.add_argument("--folder", required=True)
     download.add_argument("--uid", required=True, type=int)
@@ -371,9 +437,9 @@ def build_parser() -> argparse.ArgumentParser:
     download.add_argument("--overwrite", action="store_true")
     download.set_defaults(func=cmd_attachments_download)
 
-    draft = sub.add_parser("draft")
+    draft = sub.add_parser("draft", help="create new or reply drafts")
     draft_sub = draft.add_subparsers(dest="draft_command", required=True)
-    create = draft_sub.add_parser("create")
+    create = draft_sub.add_parser("create", help="append a new message to Drafts")
     _common_profile_args(create)
     create.add_argument("--json", dest="json_input")
     create.add_argument("--to", action="append")
@@ -387,7 +453,7 @@ def build_parser() -> argparse.ArgumentParser:
     create.add_argument("--drafts-folder")
     create.set_defaults(func=cmd_draft_create)
 
-    reply = draft_sub.add_parser("reply")
+    reply = draft_sub.add_parser("reply", help="append a reply draft for an existing message")
     _common_profile_args(reply)
     reply.add_argument("--json", dest="json_input")
     reply.add_argument("--folder")
@@ -407,6 +473,17 @@ def build_parser() -> argparse.ArgumentParser:
 
 
 def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+    if not argv or argv in (["--help"], ["-h"]):
+        sys.stdout.write(TOP_LEVEL_HELP)
+        return 0
+    if argv == ["--about"]:
+        sys.stdout.write(ABOUT_TEXT)
+        return 0
+    if argv == ["--version"]:
+        sys.stdout.write(f"{__version__}\n")
+        return 0
     parser = build_parser()
     args = parser.parse_args(argv)
     try:

imap_agent_cli-0.1.4/tests/test_cli.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import json
+import tempfile
+import unittest
+from io import StringIO
+from pathlib import Path
+from unittest.mock import patch
+
+from tests import _bootstrap  # noqa: F401
+
+from imap_agent_cli import __version__
+from imap_agent_cli.cli import build_parser, main
+
+
+class CliTests(unittest.TestCase):
+    def test_help_parser_has_expected_commands(self) -> None:
+        parser = build_parser()
+        parsed = parser.parse_args(["search", "--subject", "invoice"])
+        self.assertEqual(parsed.command, "search")
+        self.assertEqual(parsed.subject, "invoice")
+
+    def test_no_args_prints_agent_quick_reference(self) -> None:
+        stdout = StringIO()
+        stderr = StringIO()
+        with patch("sys.stdout", stdout), patch("sys.stderr", stderr):
+            code = main([])
+        output = stdout.getvalue()
+        self.assertEqual(code, 0)
+        self.assertEqual(stderr.getvalue(), "")
+        self.assertIn("safe IMAP email access for agentic tools", output)
+        self.assertIn("Safety:", output)
+        self.assertIn("IMAP_AGENT_CLI_HOST", output)
+        self.assertIn("imap-agent-cli search --folder INBOX", output)
+        self.assertIn("stdout is JSON payload only", output)
+        self.assertIn("https://github.com/pseudosavant/imap-agent-cli", output)
+        self.assertIn("License:\n  MIT", output)
+
+    def test_top_level_help_prints_agent_quick_reference(self) -> None:
+        stdout = StringIO()
+        with patch("sys.stdout", stdout):
+            code = main(["--help"])
+        output = stdout.getvalue()
+        self.assertEqual(code, 0)
+        self.assertIn("Common workflows:", output)
+        self.assertIn("imap-agent-cli <command> --help", output)
+
+    def test_about_prints_project_and_license(self) -> None:
+        stdout = StringIO()
+        with patch("sys.stdout", stdout):
+            code = main(["--about"])
+        self.assertEqual(code, 0)
+        self.assertEqual(
+            stdout.getvalue(),
+            f"""imap-agent-cli {__version__}
+
+Safe IMAP email access for agentic tools.
+
+Project: https://github.com/pseudosavant/imap-agent-cli
+License: MIT
+""",
+        )
+
+    def test_version_prints_only_semver(self) -> None:
+        stdout = StringIO()
+        with patch("sys.stdout", stdout):
+            code = main(["--version"])
+        self.assertEqual(code, 0)
+        self.assertEqual(stdout.getvalue(), f"{__version__}\n")
+
+    def test_config_init_outputs_json(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            config_path = Path(tmp) / "config.toml"
+            with patch("imap_agent_cli.cli.init_config", return_value=config_path):
+                stdout = StringIO()
+                with patch("sys.stdout", stdout):
+                    code = main(["config", "init"])
+        self.assertEqual(code, 0)
+        payload = json.loads(stdout.getvalue())
+        self.assertTrue(payload["created"])
+        self.assertEqual(payload["path"], str(config_path))
+
+    def test_read_missing_folder_errors_to_stderr(self) -> None:
+        stderr = StringIO()
+        with patch("sys.stderr", stderr):
+            code = main(["read", "--uid", "1"])
+        self.assertEqual(code, 1)
+        payload = json.loads(stderr.getvalue())
+        self.assertEqual(payload["error"]["code"], "invalid_request")
+
+    def test_attachments_missing_folder_errors_to_stderr(self) -> None:
+        stderr = StringIO()
+        with patch("sys.stderr", stderr):
+            code = main(["attachments"])
+        self.assertEqual(code, 1)
+        payload = json.loads(stderr.getvalue())
+        self.assertEqual(payload["error"]["code"], "invalid_request")
+
+
+if __name__ == "__main__":
+    unittest.main()

imap_agent_cli-0.1.3/tests/test_cli.py

@@ -1,52 +0,0 @@
-from __future__ import annotations
-
-import json
-import tempfile
-import unittest
-from io import StringIO
-from pathlib import Path
-from unittest.mock import patch
-
-from tests import _bootstrap  # noqa: F401
-
-from imap_agent_cli.cli import build_parser, main
-
-
-class CliTests(unittest.TestCase):
-    def test_help_parser_has_expected_commands(self) -> None:
-        parser = build_parser()
-        parsed = parser.parse_args(["search", "--subject", "invoice"])
-        self.assertEqual(parsed.command, "search")
-        self.assertEqual(parsed.subject, "invoice")
-
-    def test_config_init_outputs_json(self) -> None:
-        with tempfile.TemporaryDirectory() as tmp:
-            config_path = Path(tmp) / "config.toml"
-            with patch("imap_agent_cli.cli.init_config", return_value=config_path):
-                stdout = StringIO()
-                with patch("sys.stdout", stdout):
-                    code = main(["config", "init"])
-        self.assertEqual(code, 0)
-        payload = json.loads(stdout.getvalue())
-        self.assertTrue(payload["created"])
-        self.assertEqual(payload["path"], str(config_path))
-
-    def test_read_missing_folder_errors_to_stderr(self) -> None:
-        stderr = StringIO()
-        with patch("sys.stderr", stderr):
-            code = main(["read", "--uid", "1"])
-        self.assertEqual(code, 1)
-        payload = json.loads(stderr.getvalue())
-        self.assertEqual(payload["error"]["code"], "invalid_request")
-
-    def test_attachments_missing_folder_errors_to_stderr(self) -> None:
-        stderr = StringIO()
-        with patch("sys.stderr", stderr):
-            code = main(["attachments"])
-        self.assertEqual(code, 1)
-        payload = json.loads(stderr.getvalue())
-        self.assertEqual(payload["error"]["code"], "invalid_request")
-
-
-if __name__ == "__main__":
-    unittest.main()