email-cli-tool 0.1.0__py3-none-any.whl

email_cli_tool-0.1.0.dist-info/METADATA

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: email-cli-tool
+Version: 0.1.0
+Summary: A simple CLI tool for sending emails with plain text, HTML, and file attachments
+Project-URL: Homepage, https://github.com/ClaymanTwinkle/email-cli-tool
+Project-URL: Repository, https://github.com/ClaymanTwinkle/email-cli-tool
+Project-URL: Issues, https://github.com/ClaymanTwinkle/email-cli-tool/issues
+Author: ClaymanTwinkle
+License-Expression: MIT
+License-File: LICENSE
+Keywords: attachments,cli,email,smtp
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# email-cli-tool
+
+> A simple CLI tool for sending emails with plain text, HTML, and file attachments.
+>
+> [中文文档](README_CN.md)
+
+## Features
+
+- Send plain text / HTML / mixed format emails
+- Attach multiple files and images
+- Multiple recipients support
+- Direct SMTP connection (SSL / STARTTLS)
+- Interactive configuration wizard
+- Read body content from stdin
+
+## Installation
+
+```bash
+# From PyPI
+pip install email-cli-tool
+
+# Or with uv
+uv tool install email-cli-tool
+```
+
+## Quick Start
+
+### 1. Initialize Configuration
+
+```bash
+emailcli init
+```
+
+Follow the prompts to enter your SMTP settings. Example for Gmail:
+
+| Field | Value |
+|-------|-------|
+| From address | `yourname@gmail.com` |
+| SMTP host | `smtp.gmail.com` |
+| SMTP port | `465` |
+| SMTP username | `yourname@gmail.com` |
+| SMTP password | App password |
+| Encryption | `ssl` |
+
+### 2. Send Emails
+
+```bash
+# Plain text
+emailcli send --to user@example.com --subject "Hello" --body "Hello World"
+
+# HTML format
+emailcli send --to user@example.com --subject "Notice" \
+  --html "<h1>Title</h1><p>Body content</p>"
+
+# With attachments
+emailcli send --to user@example.com --subject "Report" \
+  --body "Please see attachments" \
+  --attach report.pdf \
+  --attach photo.png
+
+# Multiple recipients
+emailcli send \
+  --to a@example.com \
+  --to b@example.com \
+  --subject "Broadcast" --body "Hello everyone"
+
+# HTML body from file
+emailcli send --to user@example.com --subject "Newsletter" \
+  --html-file template.html
+
+# Read body from stdin
+echo "Content" | emailcli send \
+  --to user@example.com --subject "Piped" --body -
+```
+
+## Command Reference
+
+### `emailcli send`
+
+| Option | Required | Repeatable | Description |
+|--------|:--------:|:----------:|-------------|
+| `--to` | ✅ | ✅ | Recipient email address |
+| `--subject` | ✅ | | Email subject |
+| `--body` | | | Plain text body, `-` reads from stdin |
+| `--html` | | | HTML body string (mutually exclusive with `--html-file`) |
+| `--html-file` | | | Read HTML body from file (mutually exclusive with `--html`) |
+| `--attach` | | ✅ | Attachment file path |
+| `--from` | | | Override sender address from config |
+
+> At least one of `--body`, `--html`, or `--html-file` is required.
+
+### `emailcli init`
+
+Interactively create the configuration file at `~/.emailcli/config.yaml`.
+
+### `emailcli config show`
+
+Display current configuration (password is masked).
+
+## Configuration
+
+Path: `~/.emailcli/config.yaml`
+
+```yaml
+from: yourname@gmail.com
+smtp:
+  host: smtp.gmail.com
+  port: 465
+  username: yourname@gmail.com
+  password: your-app-password
+  encryption: ssl  # ssl | starttls | none
+```
+
+## Development
+
+```bash
+# Install dependencies
+uv sync
+
+# Run tests
+uv run pytest -v
+
+# Run locally
+uv run emailcli --help
+```
+
+## License
+
+MIT

email_cli_tool-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+emailcli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+emailcli/cli.py,sha256=pu7j_r9G2dmi0Of-Jm2ky22keFsqm_S0ce72baCA6iI,5005
+emailcli/config.py,sha256=y1gvAowozFxxBr0VCc0Cm8D1MDw1b8_Ba64wdCgml4E,1435
+emailcli/exceptions.py,sha256=PAXFwwBjkr82VfNmR3_14PyN6E5g4HZZjJO6pSqjGUY,288
+emailcli/message.py,sha256=zL6JA4gtxoytafvr07d3ZydGEUl4OYJjOjAXSlhu50Y,1833
+emailcli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+emailcli/sender.py,sha256=0LzMlMa8-v9cvfgBtrSZ3-B8CjaBSvmDFoAzgTdDWUs,1158
+email_cli_tool-0.1.0.dist-info/METADATA,sha256=N-M6kdsGGh_oG84G92tqa1U8oRWkRKBeMS_yzhfbG00,3844
+email_cli_tool-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+email_cli_tool-0.1.0.dist-info/entry_points.txt,sha256=v4g4XtxIoMN04iG6hnBI5JOKYe5yxmTZF88Bmi30w1A,46
+email_cli_tool-0.1.0.dist-info/licenses/LICENSE,sha256=uyHV-GMpScxptcV957gUjyAk0nceqdisWpm0KaDuA68,1071
+email_cli_tool-0.1.0.dist-info/RECORD,,

email_cli_tool-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

email_cli_tool-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+emailcli = emailcli.cli:cli

email_cli_tool-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClaymanTwinkle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

emailcli/cli.py

@@ -0,0 +1,142 @@
+import sys
+from pathlib import Path
+
+import click
+
+from emailcli.config import load_config
+from emailcli.exceptions import EmailCliError
+from emailcli.message import build_message
+from emailcli.sender import SmtpSender
+
+
+@click.group()
+def cli():
+    """CLI tool for sending emails with attachments."""
+
+
+@cli.command()
+@click.option("--to", "to_addrs", required=True, multiple=True, help="Recipient email address (repeatable).")
+@click.option("--subject", required=True, help="Email subject.")
+@click.option("--body", default=None, help="Plain text body. Use '-' to read from stdin.")
+@click.option("--html", "html_content", default=None, help="HTML body string.")
+@click.option("--html-file", "html_file_path", default=None, type=click.Path(exists=True), help="Read HTML body from file.")
+@click.option("--attach", "attachments", multiple=True, type=click.Path(exists=True), help="Attachment file path (repeatable).")
+@click.option("--from", "from_addr", default=None, help="Sender address (overrides config).")
+@click.option("--config-dir", default=None, type=click.Path(), hidden=True, help="Config directory (for testing).")
+def send(to_addrs, subject, body, html_content, html_file_path, attachments, from_addr, config_dir):
+    """Send an email."""
+    try:
+        # Validate --html and --html-file mutual exclusivity
+        if html_content and html_file_path:
+            raise click.UsageError("--html and --html-file are mutually exclusive.")
+
+        # Read stdin if body is "-"
+        if body == "-":
+            body = click.get_text_stream("stdin").read()
+
+        # Load config
+        cfg_dir = Path(config_dir) if config_dir else None
+        config = load_config(cfg_dir)
+
+        # Determine from address
+        sender_addr = from_addr or config.from_addr
+        if not sender_addr:
+            raise EmailCliError("No sender address. Set 'from' in config or use --from.")
+
+        # Build message
+        msg = build_message(
+            from_addr=sender_addr,
+            to_addrs=list(to_addrs),
+            subject=subject,
+            body=body,
+            html=html_content,
+            html_file=Path(html_file_path) if html_file_path else None,
+            attachments=[Path(a) for a in attachments] if attachments else None,
+        )
+
+        # Send
+        sender = SmtpSender(
+            host=config.smtp_host,
+            port=config.smtp_port,
+            username=config.smtp_username,
+            password=config.smtp_password,
+            encryption=config.smtp_encryption,
+        )
+        sender.send(msg)
+
+        click.echo("Email sent successfully.")
+    except click.UsageError:
+        raise
+    except EmailCliError as e:
+        click.echo(f"Error: {e}", err=True)
+        raise SystemExit(1)
+
+
+@cli.command()
+@click.option("--config-dir", default=None, type=click.Path(), hidden=True, help="Config directory (for testing).")
+def init(config_dir):
+    """Initialize emailcli configuration."""
+    import os
+
+    import yaml
+
+    cfg_dir = Path(config_dir) if config_dir else Path.home() / ".emailcli"
+    config_file = cfg_dir / "config.yaml"
+
+    if config_file.exists():
+        if not click.confirm(f"Config already exists at {config_file}. Overwrite?"):
+            click.echo("Aborted.")
+            return
+
+    click.echo("Setting up emailcli configuration...\n")
+
+    from_addr = click.prompt("From address (sender email)")
+    smtp_host = click.prompt("SMTP host")
+    smtp_port = click.prompt("SMTP port", type=int, default=465)
+    smtp_username = click.prompt("SMTP username")
+    smtp_password = click.prompt("SMTP password", hide_input=True)
+    smtp_encryption = click.prompt(
+        "Encryption (starttls/ssl/none)", default="ssl"
+    )
+
+    config_data = {
+        "from": from_addr,
+        "smtp": {
+            "host": smtp_host,
+            "port": smtp_port,
+            "username": smtp_username,
+            "password": smtp_password,
+            "encryption": smtp_encryption,
+        },
+    }
+
+    cfg_dir.mkdir(parents=True, exist_ok=True)
+    with open(config_file, "w") as f:
+        yaml.dump(config_data, f, default_flow_style=False)
+    os.chmod(config_file, 0o600)
+
+    click.echo(f"\nConfig saved to {config_file}")
+
+
+@cli.group(name="config")
+def config_group():
+    """Manage emailcli configuration."""
+
+
+@config_group.command()
+@click.option("--config-dir", default=None, type=click.Path(), hidden=True, help="Config directory (for testing).")
+def show(config_dir):
+    """Show current configuration."""
+    try:
+        cfg_dir = Path(config_dir) if config_dir else None
+        cfg = load_config(cfg_dir)
+
+        click.echo(f"From:       {cfg.from_addr}")
+        click.echo(f"SMTP Host:  {cfg.smtp_host}")
+        click.echo(f"SMTP Port:  {cfg.smtp_port}")
+        click.echo(f"Username:   {cfg.smtp_username}")
+        click.echo(f"Password:   ***")
+        click.echo(f"Encryption: {cfg.smtp_encryption}")
+    except EmailCliError as e:
+        click.echo(f"Error: {e}", err=True)
+        raise SystemExit(1)

emailcli/config.py

@@ -0,0 +1,53 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from emailcli.exceptions import ConfigError
+
+
+@dataclass(frozen=True)
+class ConfigData:
+    from_addr: str
+    smtp_host: str
+    smtp_port: int
+    smtp_username: str
+    smtp_password: str
+    smtp_encryption: str  # "starttls" | "ssl" | "none"
+
+
+def load_config(config_dir: Path | None = None) -> ConfigData:
+    if config_dir is None:
+        config_dir = Path.home() / ".emailcli"
+
+    config_file = config_dir / "config.yaml"
+
+    if not config_file.exists():
+        raise ConfigError(
+            f"Config file not found: {config_file}\n"
+            "Run 'emailcli init' to create one."
+        )
+
+    with open(config_file) as f:
+        data = yaml.safe_load(f)
+
+    if not isinstance(data, dict):
+        raise ConfigError(f"Invalid config format in {config_file}")
+
+    smtp = data.get("smtp", {})
+    if not isinstance(smtp, dict):
+        raise ConfigError("'smtp' must be a mapping")
+
+    required = ["host", "username", "password"]
+    for field in required:
+        if field not in smtp:
+            raise ConfigError(f"Missing required smtp field: '{field}'")
+
+    return ConfigData(
+        from_addr=data.get("from", ""),
+        smtp_host=smtp["host"],
+        smtp_port=smtp.get("port", 587),
+        smtp_username=smtp["username"],
+        smtp_password=smtp["password"],
+        smtp_encryption=smtp.get("encryption", "starttls"),
+    )

emailcli/exceptions.py

@@ -0,0 +1,14 @@
+class EmailCliError(Exception):
+    """Base exception for emailcli."""
+
+
+class ConfigError(EmailCliError):
+    """Configuration file errors."""
+
+
+class MessageError(EmailCliError):
+    """Email message building errors."""
+
+
+class SendError(EmailCliError):
+    """Email sending errors."""

emailcli/message.py

@@ -0,0 +1,65 @@
+import mimetypes
+from email.message import EmailMessage
+from pathlib import Path
+
+from emailcli.exceptions import MessageError
+
+
+def build_message(
+    from_addr: str,
+    to_addrs: list[str],
+    subject: str,
+    body: str | None = None,
+    html: str | None = None,
+    html_file: Path | None = None,
+    attachments: list[Path] | None = None,
+) -> EmailMessage:
+    # Resolve html_file to html string
+    if html_file is not None:
+        if not html_file.exists():
+            raise MessageError(f"HTML file not found: {html_file}")
+        html = html_file.read_text(encoding="utf-8")
+
+    if not body and not html:
+        raise MessageError("Must provide at least one of: --body, --html, --html-file")
+
+    # Validate attachments exist before building
+    if attachments:
+        for path in attachments:
+            if not path.exists():
+                raise MessageError(f"Attachment not found: {path}")
+
+    msg = EmailMessage()
+    msg["From"] = from_addr
+    msg["To"] = ", ".join(to_addrs)
+    msg["Subject"] = subject
+
+    # Build content
+    if body and html:
+        msg.set_content(body)
+        msg.add_alternative(html, subtype="html")
+    elif body:
+        msg.set_content(body)
+    else:
+        msg.set_content(html, subtype="html")
+
+    # Add attachments
+    if attachments:
+        for path in attachments:
+            mime_type, _ = mimetypes.guess_type(str(path))
+            if mime_type is None:
+                maintype, subtype = "application", "octet-stream"
+            else:
+                maintype, subtype = mime_type.split("/", 1)
+
+            with open(path, "rb") as f:
+                data = f.read()
+
+            msg.add_attachment(
+                data,
+                maintype=maintype,
+                subtype=subtype,
+                filename=path.name,
+            )
+
+    return msg

emailcli/sender.py

@@ -0,0 +1,43 @@
+import smtplib
+from abc import ABC, abstractmethod
+from email.message import EmailMessage
+
+from emailcli.exceptions import SendError
+
+
+class Sender(ABC):
+    @abstractmethod
+    def send(self, message: EmailMessage) -> None: ...
+
+
+class SmtpSender(Sender):
+    def __init__(
+        self,
+        host: str,
+        port: int,
+        username: str,
+        password: str,
+        encryption: str,
+    ):
+        self.host = host
+        self.port = port
+        self.username = username
+        self.password = password
+        self.encryption = encryption
+
+    def send(self, message: EmailMessage) -> None:
+        try:
+            if self.encryption == "ssl":
+                smtp_cls = smtplib.SMTP_SSL
+            else:
+                smtp_cls = smtplib.SMTP
+
+            with smtp_cls(self.host, self.port) as server:
+                if self.encryption == "starttls":
+                    server.starttls()
+                server.login(self.username, self.password)
+                server.send_message(message)
+        except SendError:
+            raise
+        except Exception as e:
+            raise SendError(f"Failed to send email: {e}") from e