feat(core): improve robustness of IMAP/SMTP client and add CLI reference doc

.github/ISSUE_TEMPLATE/bug_report.yml → .github/ISSUE_TEMPLATE/1_bug_report.yml

@@ -1,15 +1,14 @@
 name: 🐛 Bug report
 description: Create a report to help us improve the project
-assignees:
-
+labels: ["bug"]
 body:
   - type: markdown
     attributes:
       value: >
         #### Before reporting a bug, please check that the issue hasn't already been addressed in [the existing and past issues](https://github.com/relaycli/relay/issues?q=is%3Aissue).
   - type: textarea
     attributes:
-      label: Bug description
+      label: Summary
       description: |
         A clear and concise description of what the bug is.
 
@@ -23,18 +22,18 @@ body:
     attributes:
       label: Code snippet to reproduce the bug
       description: |
-        Sample code to reproduce the problem.
+        Minimal code snippet to reproduce the problem.
 
         Please wrap your code snippet with ```` ```triple quotes blocks``` ```` for readability.
       placeholder: |
         ```python
-        Sample code to reproduce the problem
+        Minimal code snippet to reproduce the problem
         ```
     validations:
       required: true
   - type: textarea
     attributes:
-      label: Error traceback
+      label: Console output
       description: |
         The error message you received running the code snippet, with the full traceback.
 
@@ -45,15 +44,34 @@ body:
         ```
     validations:
       required: true
+  - type: input
+    attributes:
+      label: Platform
+      description: What operating system and architecture are you using? (see `uname -orsm`)
+      placeholder: e.g., macOS 14 arm64, Windows 11 x86_64, Ubuntu 20.04 amd64
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: Version
+      description: What version of relaycli are you using? (see `relay version`)
+      placeholder: e.g., relay 0.0.1
+    validations:
+      required: true
+  - type: input
+    attributes:
+      label: Python version
+      description: What version of Python are you using? (see `python --version`)
+      placeholder: e.g., Python 3.11.10
+    validations:
+      required: false
   - type: textarea
     attributes:
-      label: Environment
+      label: Additional information
       description: |
         Being able to reproduce the behaviour is key to resolving bugs. Share a few information about your setup:
       placeholder: |
-        - OS: Mac/Windows/Linux
         - From source: Y/N
-        - Release version:
         - Commit hash:
     validations:
       required: true

.github/ISSUE_TEMPLATE/feature_request.yml → .github/ISSUE_TEMPLATE/2_feature_request.yml

@@ -1,5 +1,5 @@
 name: 🚀 Feature request
-description: Submit a proposal/request for a new feature for the companion API
+description: Submit a proposal/request for a new feature for the CLI
 assignees:
 
 body:

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,11 @@
 blank_issues_enabled: true
 contact_links:
+  - name: Documentation
+    url: https://docs.relaycli.com/
+    about: Please consult the documentation before creating an issue.
+  - name: Community
+    url: https://discord.gg/T4zbT7RcVy
+    about: Join our Discord community to ask questions and collaborate.
   - name: Usage questions
     url: https://github.com/relaycli/relay/discussions
     about: Ask questions and discuss with other Relay community members

.github/labeler.yml

@@ -90,12 +90,12 @@
 # CLI-specific
 ########################################################
 
-'commands: account':
+'commands: accounts':
 - changed-files:
   - any-glob-to-any-file:
     - relay/cli/commands/account/*
 
-'commands: auth':
+'commands: messages':
 - changed-files:
   - any-glob-to-any-file:
-    - relay/cli/commands/auth/*
+    - relay/cli/commands/messages/*

.github/release.yml

@@ -3,17 +3,11 @@ changelog:
     labels:
       - ignore-for-release
   categories:
-    - title: Breaking Changes 🛠
+    - title: Breaking changes 🛠
       labels: ["type: breaking change"]
-    - title: New Features ✨
-      labels: ["type: feat"]
+    - title: New features & enhancements ✨
+      labels: ["type: feat", "type: enhancement"]
     - title: Bug Fixes 🐛
       labels: ["type: fix"]
-    - title: Dependencies
-      labels: ["dependencies"]
     - title: Documentation 📖
       labels: ["service: docs"]
-    - title: Improvements
-      labels: ["type: improvement"]
-    - title: Other changes
-      labels: ["*"]

.github/workflows/core.yml → .github/workflows/package.yml

@@ -1,22 +1,22 @@
-name: core
+name: package
 
 on:
   push:
     branches: main
     paths:
+      - '.github/workflows/package.yml'
       - 'relay/**'
-      - 'cli/**'
+      - 'tests/**'
       - 'pyproject.toml'
       - 'Makefile'
-      - '.github/workflows/core.yml'
   pull_request:
     branches: main
     paths:
+      - '.github/workflows/package.yml'
       - 'relay/**'
-      - 'cli/**'
+      - 'tests/**'
       - 'pyproject.toml'
       - 'Makefile'
-      - '.github/workflows/core.yml'
   release:
     types: [published]
 
@@ -28,12 +28,16 @@ env:
 jobs:
   install:
     if: github.event_name == 'pull_request'
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ['3.11', '3.12', '3.13']
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
-          python-version: ${{ env.PYTHON_VERSION }}
+          python-version: ${{ matrix.python }}
           architecture: x64
       - uses: astral-sh/setup-uv@v6
         with:
@@ -126,13 +130,18 @@ jobs:
           fail_ci_if_error: true
 
   build:
-    if: github.event_name != 'release'
-    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    needs: install
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ['3.11', '3.12', '3.13']
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
         with:
-          python-version: ${{ env.PYTHON_VERSION }}
+          python-version: ${{ matrix.python }}
           architecture: x64
       - uses: astral-sh/setup-uv@v6
         with:
@@ -170,20 +179,21 @@ jobs:
           echo "package_version=${BUILD_VERSION}" >> $GITHUB_OUTPUT
           echo "BUILD_VERSION=${BUILD_VERSION}" >> $GITHUB_ENV
       - name: Publish to PyPI
-        env:
-          UV_PUBLISH_USERNAME: __token__
-          UV_PUBLISH_PASSWORD: ${{ secrets.PYPI_TOKEN }}
         run: |
           make set-version
           make build && make publish
 
   verify-publish:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python: ['3.11', '3.12', '3.13']
     needs: publish
     steps:
       - uses: actions/setup-python@v5
         with:
-          python-version: ${{ env.PYTHON_VERSION }}
+          python-version: ${{ matrix.python }}
           architecture: x64
       - uses: astral-sh/setup-uv@v6
         with:

Makefile

@@ -60,7 +60,7 @@ build: ${PYPROJECT_CONFIG_FILE} ## Build the package
 	uv build ${ENGINE_DIR}
 
 publish: ${ENGINE_DIR} ## Publish the package to PyPI
-	uv publish
+	uv publish --trusted-publishing always
 
 lock: ${PYPROJECT_CONFIG_FILE}
 	uv lock --project ${ENGINE_DIR}

README.md

@@ -51,8 +51,9 @@ Relay helps builds create apps on email workflows. See it as a crossover between
 ### Fetching your unread emails
 
 ```shell
-$ relay messages ls --limit 10 --unread
-
+relay messages ls --limit 10 --unread
+```
+```
 Using account: piedpiper
                             Messages from [email protected]
 ┏━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
@@ -80,8 +81,9 @@ Showing 5 of 5 unread messages
 ### Reading email details
 
 ```shell
-$ relay messages cat 15443
-
+relay messages cat 15443
+```
+```
 Using account: piedpiper
 
 Message Details
@@ -96,7 +98,7 @@ BCC: N/A
 Message Body:
 The migration is done. Obviously.
 
-While you were all probably panicking about downtime (which never happened), 
+While you were all probably panicking about downtime (which never happened),
 I successfully migrated our entire server infrastructure to the new data center.
 
 Key accomplishments:
@@ -105,13 +107,13 @@ Key accomplishments:
 - Optimized database queries by 340%
 - Fixed 23 security vulnerabilities
 
-Richard, the system is now running at 99.97% efficiency. The remaining 0.03% 
+Richard, the system is now running at 99.97% efficiency. The remaining 0.03%
 is due to the laws of physics, which even I cannot override.
 
-Dinesh, I've documented everything in a way that even you might comprehend, 
+Dinesh, I've documented everything in a way that even you might comprehend,
 though I make no guarantees.
 
-The servers are purring like a well-fed cat. You may now return to your 
+The servers are purring like a well-fed cat. You may now return to your
 regularly scheduled mediocrity.
 
 --
@@ -137,15 +139,16 @@ pip install relaycli
 ```
 #### 2 - Connect your email account
 ```shell
-relay account add
+relay accounts add
 ```
 Follow the instructions to connect your email account.
 
 #### 3 - Play with the CLI
 
 ```shell
-$ relay messages --help
-
+relay messages --help
+```
+```
  Usage: relay messages [OPTIONS] COMMAND [ARGS]...
 
  Email message commands

docs/changelog/overview.mdx

@@ -13,8 +13,8 @@ The changelog below reflects new product developments and updates on a monthly b
 
   ### 🔧 CLI Commands
 
-  * `relay account add` - Connect your email accounts (Gmail, Outlook, Yahoo, custom IMAP)
-  * `relay account ls` - List all connected accounts
+  * `relay accounts add` - Connect your email accounts (Gmail, Outlook, Yahoo, custom IMAP)
+  * `relay accounts ls` - List all connected accounts
   * `relay messages ls` - Fetch and list recent emails
   * `relay messages grep` - Search your inbox with powerful text matching
   * `relay messages cat` - Read full message content and metadata
@@ -40,6 +40,6 @@ The changelog below reflects new product developments and updates on a monthly b
 
   ### 🚀 Getting Started
 
-  Install with `pip install relaycli` and run `relay account add` to connect your first inbox.
+  Install with `pip install relaycli` and run `relay accounts add` to connect your first inbox.
   Check out our [quickstart guide](/documentation/getting-started/quickstart) for a 5-minute setup walkthrough.
 </Update>

docs/docs.json

@@ -36,6 +36,18 @@
           }
         ]
       },
+      {
+        "tab": "Reference",
+        "groups": [
+          {
+            "group": "CLI reference",
+            "pages": [
+              "reference/cli/accounts",
+              "reference/cli/messages"
+            ]
+          }
+        ]
+      },
       {
         "tab": "Changelog",
         "groups": [
@@ -76,8 +88,9 @@
   "navbar": {
     "links": [
       {
-        "label": "Support",
-        "href": "mailto:[email protected]"
+        "label": "Community",
+        "icon": "discord",
+        "href": "https://discord.gg/T4zbT7RcVy"
       }
     ],
     "primary": {

docs/documentation/getting-started/introduction.mdx

@@ -24,7 +24,7 @@ Your credentials stay local. Your data stays yours. No gatekeepers, no vendor lo
 
 ## Why we built it
 
-Email is a billion-person communication protocol, but building on it sucks. 
+Email is a billion-person communication protocol, but building on it sucks.
 We hit this wall building a voice assistant for founders when we received the bill for the security audit to validate Gmail permissions. You can read the full story [here](https://relaycli.com/manifesto).
 So we built Relay: a clean, local-first CLI and Python library that handles the complexity while keeping you in control. No middlemen, no data harvesting, no artificial limits.