@mailmodo/cli 0.0.58-beta.pr60.110 → 0.0.59-beta.pr61.111

package/README.md

@@ -1,125 +1,827 @@
-# mailmodo-cli
+# @mailmodo/cli
+
+[![npm version](https://img.shields.io/npm/v/@mailmodo/cli.svg)](https://www.npmjs.com/package/@mailmodo/cli)
+[![npm downloads](https://img.shields.io/npm/dm/@mailmodo/cli.svg)](https://www.npmjs.com/package/@mailmodo/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+
+**Email lifecycle automation for the AI-native builder generation.**
+
+`@mailmodo/cli` is a command-line tool that analyzes your product, generates a full onboarding and lifecycle email sequence using AI, and deploys it — all from your terminal. It manages everything from domain setup and HTML template generation to live deployment, performance monitoring, and contact management.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Commands Reference](#commands-reference)
+  - [login](#login)
+  - [logout](#logout)
+  - [init](#init)
+  - [emails](#emails)
+  - [edit](#edit)
+  - [preview](#preview)
+  - [deploy](#deploy)
+  - [deployments](#deployments)
+  - [sdk](#sdk)
+  - [domain](#domain)
+  - [settings](#settings)
+  - [status](#status)
+  - [logs](#logs)
+  - [contacts](#contacts)
+  - [billing](#billing)
+  - [report](#report)
+- [SDK / App Integration](#sdk--app-integration)
+- [Configuration](#configuration)
+- [AI Agent Support](#ai-agent-support)
+- [Contributing](#contributing)
+
+---
+
+## Installation
+
+```bash
+npm install -g @mailmodo/cli
+```
 
-Email lifecycle automation for the AI-native builder generation.
+Requires **Node.js >= 18**.
 
-## Prerequisites
+Verify the installation:
 
-- **Node.js** v24.14.1
+```bash
+mailmodo --version
+mailmodo --help
+```
 
-## Setup
+---
 
-```sh
-git clone https://github.com/Mailmodo/mailmodo-cli.git
-cd mailmodo-cli
-npm install
+## Quick Start
+
+The primary workflow from zero to deployed email sequence:
+
+**1. Authenticate**
+
+```bash
+mailmodo login
 ```
 
-## Development
+You will be prompted to enter your Mailmodo API key. Get one at [app.mailmodo.dev](https://app.mailmodo.dev).
 
-### Run in dev mode (without building)
+**2. Analyze your product and generate emails**
 
-```sh
-node ./bin/run.js <command>
+```bash
+mailmodo init --url https://yourapp.com
 ```
 
-Example:
+The CLI scrapes your product URL, detects your business model, and generates a full email sequence with HTML templates. A `mailmodo.yaml` config file and a `mailmodo/` directory of HTML templates are created in your current working directory.
 
-```sh
-node ./bin/run.js signup
+**3. Preview an email**
+
+```bash
+mailmodo preview welcome
 ```
 
-### Build the project
+Opens a local preview server in your browser. Use `--send me@example.com` to send yourself a test.
 
-```sh
-npm run build
+**4. Set up your sending domain**
+
+```bash
+mailmodo domain
+```
+
+Follow the prompts to register your domain and sender details. The CLI displays the DNS records you need to add. Verify once propagated:
+
+```bash
+mailmodo domain --verify
+```
+
+**5. Deploy**
+
+```bash
+mailmodo deploy
+```
+
+Validates your configuration, deploys all email sequences, and prints the `track()` and `identify()` SDK snippets to wire into your app.
+
+**6. Monitor**
+
+```bash
+mailmodo status      # quota usage and per-email metrics
+mailmodo logs        # delivery event log
+```
+
+---
+
+## Commands Reference
+
+All commands support two universal flags:
+
+| Flag     | Alias | Description                                                    |
+| -------- | ----- | -------------------------------------------------------------- |
+| `--json` |       | Output as machine-readable JSON instead of formatted text      |
+| `--yes`  | `-y`  | Skip all confirmation prompts (non-interactive / scripted use) |
+
+---
+
+### login
+
+Authenticate with Mailmodo using your API key.
+
+```bash
+mailmodo login
 ```
 
-### Run after build
+Validates your API key against the Mailmodo API, saves credentials to `~/.mailmodo/config`, and performs a silent cloud backup of any existing `mailmodo.yaml`. If credentials are already saved, displays current account status.
+
+**Environment variable shortcut (for CI/CD):**
+
+```bash
+# Linux / macOS
+MAILMODO_API_KEY=your_key mailmodo login
+
+# Windows PowerShell
+$env:MAILMODO_API_KEY="your_key"; mailmodo login
 
-```sh
-./bin/run.js <command>
+# Windows CMD
+set MAILMODO_API_KEY=your_key && mailmodo login
 ```
 
-### Link globally for local testing
+**JSON output shape:**
+
+```json
+{
+  "status": "logged_in",
+  "email": "you@example.com",
+  "plan": "free",
+  "totalFreeRemaining": 500,
+  "paidEmailsRemaining": 0,
+  "yamlRestored": false
+}
+```
+
+---
 
-This registers the `mailmodo` binary on your system so you can use it from anywhere:
+### logout
 
-```sh
-npm link
+Remove saved credentials from this machine.
+
+```bash
+mailmodo logout
 ```
 
-Then run commands directly:
+Deletes `~/.mailmodo/config`. Does not affect the server-side account.
+
+**JSON output shape:**
 
-```sh
-mailmodo signup
+```json
+{ "status": "logged_out" }
 ```
 
-To unlink:
+---
 
-```sh
-npm unlink -g @mailmodo/cli
+### init
+
+Analyze your product and generate a full email sequence.
+
+```bash
+mailmodo init
+mailmodo init --url https://yourapp.com
+mailmodo init --url https://yourapp.com --yes
 ```
 
-## Commands
+| Flag    | Type   | Description                                                |
+| ------- | ------ | ---------------------------------------------------------- |
+| `--url` | string | Product URL to analyze (prompted interactively if omitted) |
+
+What `init` does:
 
-### `mailmodo signup`
+1. Calls the Mailmodo AI to analyze your product URL and detect business model, target user, SaaS model, and brand details.
+2. Generates email copy and HTML templates for a complete lifecycle sequence (welcome, onboarding, trial expiry, etc.).
+3. Writes `mailmodo.yaml` to the current directory.
+4. Creates a `mailmodo/` directory containing one `.html` file per email.
+5. Silently backs up the config and templates to the cloud.
 
-Sign up for Mailmodo. Prompts for an email address interactively.
+**JSON output shape:**
 
-```sh
-mailmodo signup
+```json
+{
+  "brand": { "name": "...", "color": "...", "url": "..." },
+  "emailConfigs": [...],
+  "emailStyle": "branded",
+  "monthlyCap": 5
+}
 ```
 
-### `mailmodo help [COMMAND]`
+---
 
-Display help for any command.
+### emails
 
-```sh
-mailmodo help
-mailmodo help signup
+List and inspect your configured email sequences.
+
+```bash
+mailmodo emails
+mailmodo emails --json
 ```
 
-## Scripts
+Reads `mailmodo.yaml` locally and displays a table of all configured emails: ID, trigger event, delay, and subject. In interactive mode, you can select any email to view its full details or open the template in your editor.
+
+**JSON output shape:**
+
+```json
+{
+  "emails": [
+    {
+      "id": "welcome",
+      "trigger": "user.signup",
+      "delay": 0,
+      "subject": "Welcome to MyApp"
+    }
+  ],
+  "total": 4
+}
+```
 
-| Script          | Description                          |
-| --------------- | ------------------------------------ |
-| `npm run build` | Clean `dist/` and compile TypeScript |
-| `npm run lint`  | Run ESLint                           |
-| `npm test`      | Run tests with Mocha                 |
+---
 
-## CI/CD & Release Automation
+### edit
 
-### Beta releases (on PR)
+Edit an email using AI-assisted natural language changes.
 
-Every time a pull request targeting `main` is opened or updated, a **beta version** is automatically published to npm. A comment is posted on the PR with install instructions:
+```bash
+mailmodo edit <id>
+mailmodo edit welcome
+mailmodo edit welcome --change "make the subject more urgent"
+mailmodo edit welcome --change "rewrite the body focusing on onboarding" --yes
+```
 
-```sh
-npm install -g @mailmodo/cli@beta
+| Argument | Description                          |
+| -------- | ------------------------------------ |
+| `id`     | Email template ID to edit (required) |
+
+| Flag       | Type   | Description                                                                        |
+| ---------- | ------ | ---------------------------------------------------------------------------------- |
+| `--change` | string | Natural language description of what to change (prompted interactively if omitted) |
+
+The CLI sends the current template and your change description to the Mailmodo AI, previews the diff (changed vs. unchanged fields), and lets you accept, retry, or skip.
+
+**JSON output shape:**
+
+Returns the updated email object with a `diff` property showing which fields changed and which were preserved.
+
+---
+
+### preview
+
+Preview an email in the browser, as plain text, or send a test.
+
+```bash
+mailmodo preview
+mailmodo preview <id>
+mailmodo preview welcome --text
+mailmodo preview welcome --send me@example.com
 ```
 
-This lets anyone on the team test the PR changes without checking out the branch locally.
+| Argument | Description                                                                  |
+| -------- | ---------------------------------------------------------------------------- |
+| `id`     | Email template ID (optional; defaults to the first email in `mailmodo.yaml`) |
+
+| Flag     | Type    | Description                                                      |
+| -------- | ------- | ---------------------------------------------------------------- |
+| `--text` | boolean | Print a plain-text rendering of the email (useful for AI agents) |
+| `--send` | string  | Send a test email to the specified address                       |
 
-> **Note:** npm publishing requires the `NPM_AUTH_TOKEN_WRITE` secret to be configured in the repo settings. Until then, the publish step will be skipped but all other steps (build, version bump, release) still work.
+In browser mode (default), a local server starts at `http://localhost:3421` and opens your browser.
 
-### Automatic versioning (on merge)
+---
 
-When a PR is merged into `main`, the version in `package.json` is bumped automatically, a GitHub Release is created, and the new version is published to npm.
+### deploy
 
-The bump type is determined by a tag in the **PR title**:
+Deploy, pause, or resume an email sequence.
 
-| PR title contains | Bump type | Example           |
-| ----------------- | --------- | ----------------- |
-| `[major]`         | major     | `1.2.3` → `2.0.0` |
-| `[minor]`         | minor     | `1.2.3` → `1.3.0` |
-| `[patch]`         | patch     | `1.2.3` → `1.2.4` |
-| _(nothing)_       | patch     | `1.2.3` → `1.2.4` |
+```bash
+# Deploy all configured sequences
+mailmodo deploy
+mailmodo deploy --yes
+
+# Pause a live sequence
+mailmodo deploy --pause <sequenceId>
+
+# Resume a paused sequence
+mailmodo deploy --resume <sequenceId>
+mailmodo deploy --resume <sequenceId> --json
+```
+
+| Flag       | Type   | Description                                                               |
+| ---------- | ------ | ------------------------------------------------------------------------- |
+| `--pause`  | string | Pause a deployed sequence by ID (stops all scheduled and triggered sends) |
+| `--resume` | string | Resume a paused sequence by ID                                            |
+
+`--pause` and `--resume` are mutually exclusive.
+
+**Deploy flow:**
+
+1. Checks domain verification status; runs domain setup if needed.
+2. Validates your email sequence configuration.
+3. Shows a pre-deploy summary: domain, sender, email count, and a diff of changes since the last deploy.
+4. Prompts for confirmation (skipped with `--yes`).
+5. Deploys and prints the `@mailmodo/sdk` code snippets to add to your app.
+
+**Deploy JSON output shape:**
+
+```json
+{
+  "deployed": true,
+  "emailsLive": 4,
+  "sequenceId": "seq_abc123",
+  "diff": { "added": [], "changed": [], "removed": [] },
+  "sdkSnippet": "..."
+}
+```
+
+**Pause/Resume JSON output shape:**
+
+```json
+{
+  "sequenceId": "seq_abc123",
+  "status": "paused",
+  "alreadyInStatus": false
+}
+```
+
+---
+
+### deployments
+
+List every deployed sequence on this account.
+
+```bash
+mailmodo deployments
+mailmodo deployments --json
+```
+
+Displays a table with product name, status (`active` / `paused`), email count, sequence ID, and last-updated date. The sequence IDs shown here are the values to pass to `deploy --pause` and `deploy --resume`.
+
+**JSON output shape:**
+
+```json
+{
+  "sequences": [
+    {
+      "sequenceId": "seq_abc123",
+      "product": "MyApp",
+      "status": "active",
+      "emailCount": 4,
+      "updatedAt": "2025-06-01T10:00:00Z"
+    }
+  ],
+  "total": 1
+}
+```
+
+---
+
+### sdk
+
+Show SDK `track()` and `identify()` reference for your deployed sequences.
+
+```bash
+mailmodo sdk
+mailmodo sdk --sequence-id seq_abc123
+mailmodo sdk --json
+```
+
+| Flag            | Type   | Description                                                               |
+| --------------- | ------ | ------------------------------------------------------------------------- |
+| `--sequence-id` | string | Limit output to a specific sequence by ID (default: all active sequences) |
+
+Displays the install command, import line, and copy-ready `track()` / `identify()` function calls for each active sequence. See [SDK / App Integration](#sdk--app-integration) for details on using these in your app.
+
+---
+
+### domain
+
+Set up and verify your sending domain.
+
+```bash
+# Interactive setup (register domain and get DNS records)
+mailmodo domain
+
+# Verify DNS records after adding them
+mailmodo domain --verify
+
+# Show domain health metrics
+mailmodo domain --status
+```
+
+| Flag       | Type    | Description                                                             |
+| ---------- | ------- | ----------------------------------------------------------------------- |
+| `--verify` | boolean | Check SPF, DKIM, and DMARC record status                                |
+| `--status` | boolean | Display domain health metrics (bounce rate, spam rate, verified status) |
+
+During setup, you are prompted for: domain, sender email (must be `@<domain>`), from name, reply-to address, and physical business address (required by CAN-SPAM). The CLI outputs the exact DNS records to add to your registrar.
+
+> **Note:** DNS changes take 5–30 minutes to propagate before verification will pass.
+
+---
+
+### settings
+
+View and update project settings.
+
+```bash
+mailmodo settings
+mailmodo settings --set brand_color=#0F3460
+mailmodo settings --json
+```
+
+| Flag    | Type   | Description                                   |
+| ------- | ------ | --------------------------------------------- |
+| `--set` | string | Set a single setting using `key=value` syntax |
+
+In interactive mode (no flags), displays all settings grouped by category and prompts to edit each one. With `--set`, updates the specified key directly without prompting.
+
+**Settable keys:**
+
+| Category         | Keys                                                                            |
+| ---------------- | ------------------------------------------------------------------------------- |
+| Project Info     | `name`, `url`, `description`, `type`, `targetUser`, `saasModel`, `pricingModel` |
+| Branding         | `brand_color`, `email_style` (`plain` \| `branded`), `logo_url`, `logo_file`    |
+| Domain / Sending | `domain`, `from_email`, `from_name`, `reply_to`, `address`                      |
+| Billing          | `monthly_cap` (paid tier only), `webhook_url`                                   |
+
+---
+
+### status
+
+View email performance metrics and quota usage.
+
+```bash
+mailmodo status
+mailmodo status --json
+```
+
+Displays per-email metrics (sent, open rate, click rate, conversion rate), total monthly sends, and current quota status (free emails remaining or paid blocks consumed).
+
+**JSON output shape:**
+
+```json
+{
+  "emails": [
+    {
+      "id": "welcome",
+      "sent": 120,
+      "openRate": 0.42,
+      "clickRate": 0.15,
+      "conversionRate": 0.08
+    }
+  ],
+  "monthlySent": 480,
+  "quota": { "free": 20, "paidBlocksUsed": 0 }
+}
+```
 
-**Examples of PR titles:**
+---
+
+### logs
+
+View email send logs and delivery events.
+
+```bash
+mailmodo logs
+mailmodo logs --email sarah@example.com
+mailmodo logs --failed
+mailmodo logs --limit 100 --page 2
+mailmodo logs --json
+```
+
+| Flag       | Type    | Default | Description                            |
+| ---------- | ------- | ------- | -------------------------------------- |
+| `--email`  | string  |         | Filter events by contact email address |
+| `--failed` | boolean | false   | Show only failed or bounced events     |
+| `--limit`  | integer | 50      | Entries per page (max 200)             |
+| `--page`   | integer | 1       | Page number for pagination             |
+
+**JSON output shape:**
+
+```json
+{
+  "entries": [
+    {
+      "timestamp": "2025-06-01T10:00:00Z",
+      "emailId": "welcome",
+      "status": "delivered",
+      "contact": "sarah@example.com",
+      "reason": null
+    }
+  ],
+  "total": 480,
+  "page": 1,
+  "limit": 50
+}
+```
+
+---
+
+### contacts
+
+Manage contacts — search, export, or delete.
+
+```bash
+# Show summary counts
+mailmodo contacts
+
+# Search for a specific contact
+mailmodo contacts --search sarah@example.com
+
+# Export all contacts as GDPR-compliant CSV
+mailmodo contacts --export
+
+# Hard-delete a contact (GDPR right to erasure)
+mailmodo contacts --delete sarah@example.com
+```
+
+| Flag       | Type    | Description                             |
+| ---------- | ------- | --------------------------------------- |
+| `--search` | string  | Look up a contact by email address      |
+| `--export` | boolean | Download all contacts to `contacts.csv` |
+| `--delete` | string  | Permanently delete a contact by email   |
+
+Without any flags, displays total, active, unsubscribed, and bounced contact counts.
+
+---
+
+### billing
+
+View billing status, purchase email blocks, set a monthly cap, or add a payment method.
+
+```bash
+# View current billing status
+mailmodo billing
+mailmodo billing --status
+
+# Open Stripe checkout to add or update a payment method
+mailmodo billing --checkout
+
+# Purchase email blocks immediately
+mailmodo billing --purchase 3
+
+# Set a monthly sending cap (paid tier)
+mailmodo billing --cap 5
+
+# Set cap with auto-refill when quota runs low
+mailmodo billing --cap 5 --auto-charge-block-count 2
+```
+
+| Flag                        | Type    | Description                                                         |
+| --------------------------- | ------- | ------------------------------------------------------------------- |
+| `--status`                  | boolean | Show billing status only (tier, cap, spending)                      |
+| `--checkout`                | boolean | Open Stripe checkout to add or update a payment method              |
+| `--purchase`                | integer | Manually purchase the specified number of email blocks              |
+| `--cap`                     | integer | Set monthly sending cap in blocks                                   |
+| `--auto-charge-block-count` | integer | Blocks to auto-purchase when quota runs low (use alongside `--cap`) |
+
+Each block = 1,000 emails. `--monthly-cap` and `--auto-charge-block-count` require a saved payment method.
+
+---
+
+### report
+
+Fetch a detailed analytics report with flexible filtering and grouping.
+
+```bash
+# Quick report for the last 7 days
+mailmodo report --preset last7d
+
+# Group by email template
+mailmodo report --preset last30d --group-by emailId
+
+# Custom date range, raw event entries
+mailmodo report --from 2025-05-01 --to 2025-06-01 --output entries
+
+# Filter to a specific sequence and event type
+mailmodo report --preset last30d --sequence seq_abc123 --event opened
+
+# Paginate through entries
+mailmodo report --preset last7d --output entries --page 2 --limit 100
+
+mailmodo report --preset last7d --json
+```
+
+| Flag         | Type     | Default   | Description                                                                                                                     |
+| ------------ | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `--preset`   | string   |           | Relative time range: `today`, `yesterday`, `last7d`, `last30d`, `last90d`, `thisMonth`, `lastMonth`                             |
+| `--from`     | string   |           | Start of range inclusive (YYYY-MM-DD). Exclusive with `--preset`                                                                |
+| `--to`       | string   |           | End of range exclusive (YYYY-MM-DD). Exclusive with `--preset`                                                                  |
+| `--group-by` | string   | `none`    | Group results by: `none`, `emailId`, `sequenceId`, `day`, `hour`, `contact`, `status`                                           |
+| `--output`   | string   | `summary` | Output shape: `summary`, `entries`, `timeseries`                                                                                |
+| `--email-id` | string[] |           | Filter by one or more email template IDs (repeatable)                                                                           |
+| `--contact`  | string[] |           | Filter by one or more contact emails (repeatable)                                                                               |
+| `--sequence` | string[] |           | Filter by one or more sequence IDs (repeatable)                                                                                 |
+| `--event`    | string[] |           | Filter by event type: `sent`, `delivered`, `opened`, `clicked`, `bounced`, `complained`, `skipped`, `unsubscribed` (repeatable) |
+| `--limit`    | integer  | 50        | Entries per page, max 200 (applies to `entries` output only)                                                                    |
+| `--page`     | integer  | 1         | Page number (applies to `entries` output only)                                                                                  |
+
+`--preset` and `--from`/`--to` are mutually exclusive.
+
+---
+
+## SDK / App Integration
+
+After deploying a sequence, the CLI prints the exact code to add to your application. You can always retrieve it with:
+
+```bash
+npm install @mailmodo/sdk
+```
+
+```javascript
+import { track, identify } from '@mailmodo/sdk';
+```
+
+### `track(event, properties)`
+
+Called when a lifecycle event happens in your app. This triggers the email configured for that event.
+
+```javascript
+// Example: trigger the "welcome" email on sign-up
+track('myApp$user.signup', {
+  contactEmailId: user.email,
+  first_name: user.firstName,
+  onboarding_url: `https://app.example.com/onboard/${user.id}`,
+});
+```
+
+### `identify(email, properties)`
+
+Updates contact properties used by conditional send logic.
+
+```javascript
+// Example: update onboarding status to conditionally suppress follow-up emails
+identify(user.email, {
+  onboarding_not_completed: user.onboardingStep < 3,
+});
+```
+
+The `mailmodo sdk` command (or the post-deploy output) shows the exact event names and properties for each sequence in your account.
+
+---
+
+## Configuration
+
+### Credentials — `~/.mailmodo/config`
+
+Stores your API key and account metadata. Written by `mailmodo login`, deleted by `mailmodo logout`. Never commit this file.
+
+```json
+{
+  "apiKey": "mk_...",
+  "email": "you@example.com",
+  "totalFreeRemaining": 500
+}
+```
+
+**Environment variable override:** Set `MAILMODO_API_KEY` to bypass the config file entirely — useful in CI/CD pipelines and Docker containers.
+
+### Project Config — `mailmodo.yaml`
+
+Created by `mailmodo init` in your current working directory. This is the source of truth for your email sequence. Commit it to version control.
+
+```yaml
+project:
+  name: MyApp
+  url: https://myapp.com
+  description: Project management for remote teams
+  type: b2b_saas
+  targetUser: engineering managers
+  saasModel: subscription
+  pricingModel: per_seat
+
+  domain: myapp.com
+  fromEmail: hello@myapp.com
+  fromName: MyApp
+  replyTo: support@myapp.com
+  address: 123 Main St, San Francisco, CA 94105, US
+
+  emailStyle: branded # branded | plain
+  brandColor: '#1A56DB'
+  logoUrl: https://cdn.myapp.com/logo.png
+
+  monthlyCap: 5 # paid tier — blocks per month (1 block = 1,000 emails)
+  webhookUrl: https://myapp.com/webhooks/mailmodo
+
+emails:
+  - id: welcome
+    trigger: user.signup
+    delay: 0
+    subject: 'Welcome to MyApp, {{first_name}}!'
+    template: welcome.html
+    style: branded
+    previewText: 'Your account is ready.'
+    goal: Drive user to complete the first key action
+    ctaText: Get Started
+
+  - id: day3-nudge
+    trigger: user.signup
+    delay: '3d'
+    subject: 'Quick tip for getting started'
+    template: day3-nudge.html
+    condition: 'onboarding_not_completed == true'
+```
+
+### HTML Templates — `mailmodo/`
+
+Each email in `mailmodo.yaml` maps to an HTML file in the `mailmodo/` directory:
+
+```
+mailmodo/
+  welcome.html
+  day3-nudge.html
+  trial-expiry.html
+```
+
+Templates are generated by `mailmodo init` and editable directly or via `mailmodo edit`. They are automatically synced to the Mailmodo cloud as a backup on every modifying command and restored automatically if the local file is missing.
+
+---
+
+## AI Agent Support
+
+All commands support two flags designed for headless and automated environments:
+
+| Flag           | Description                                                                                                                                 |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--json`       | All output is valid JSON on stdout. Spinners and progress text go to stderr, keeping stdout clean for piping and parsing.                   |
+| `--yes` / `-y` | Skips all interactive confirmation prompts. The CLI proceeds with the inferred defaults, making it safe to run in scripts and CI pipelines. |
+
+### API key via environment variable
+
+Set `MAILMODO_API_KEY` to authenticate without a config file:
+
+```bash
+MAILMODO_API_KEY=mk_... mailmodo deploy --yes --json
+```
+
+### Example: fully non-interactive deploy in CI
+
+```bash
+MAILMODO_API_KEY=$MAILMODO_API_KEY \
+  mailmodo deploy --yes --json | jq '.sequenceId'
+```
+
+### Example: AI agent loop
+
+```bash
+# Generate emails, skip all prompts, get structured output
+mailmodo init --url https://yourapp.com --yes --json
+
+# Edit with a specific instruction, no confirmation
+mailmodo edit welcome --change "add a P.S. with the link to our docs" --yes --json
+
+# Deploy immediately
+mailmodo deploy --yes --json
+```
+
+---
+
+## Contributing
+
+Contributions are welcome. This is an open-source project and issues, bug reports, and pull requests are appreciated.
+
+```bash
+# Clone and install
+git clone https://github.com/Mailmodo/mailmodo-cli.git
+cd mailmodo-cli
+npm install
+
+# Build
+npm run build
+
+# Run a command without building
+node ./bin/run.js <command>
+
+# Run tests
+npm test
+
+# Run a single test file
+npx mocha --loader ts-node/esm test/commands/<name>/index.test.ts
+
+# Lint
+npm run lint
+```
+
+**Versioning:** PR title tags control version bumps on merge to `main`:
+
+- `[major]` → major bump
+- `[minor]` → minor bump
+- `[patch]` or no tag → patch bump
+
+Beta builds are published automatically to npm on every PR:
+
+```bash
+npm install -g @mailmodo/cli@beta
+```
 
-- `[minor] Add email validation` → minor bump
-- `[major] Rewrite auth flow` → major bump
-- `Fix typo in help text` → patch bump (default)
+---
 
 ## License
 
-MIT
+MIT © [Mailmodo](https://github.com/Mailmodo)

package/oclif.manifest.json

@@ -341,13 +341,13 @@
         "index.js"
       ]
     },
-    "init": {
+    "emails": {
       "aliases": [],
       "args": {},
-      "description": "Analyze your product and generate email sequences",
+      "description": "List and view configured email sequences",
       "examples": [
-        "<%= config.bin %> init",
-        "<%= config.bin %> init --url https://myapp.com --yes"
+        "<%= config.bin %> emails",
+        "<%= config.bin %> emails --json"
       ],
       "flags": {
         "json": {
@@ -362,18 +362,11 @@
           "name": "yes",
           "allowNo": false,
           "type": "boolean"
-        },
-        "url": {
-          "description": "Product URL to analyze",
-          "name": "url",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "init",
+      "id": "emails",
       "pluginAlias": "@mailmodo/cli",
       "pluginName": "@mailmodo/cli",
       "pluginType": "core",
@@ -383,17 +376,17 @@
       "relativePath": [
         "dist",
         "commands",
-        "init",
+        "emails",
         "index.js"
       ]
     },
-    "login": {
+    "init": {
       "aliases": [],
       "args": {},
-      "description": "Authenticate with Mailmodo using your API key",
+      "description": "Analyze your product and generate email sequences",
       "examples": [
-        "<%= config.bin %> login",
-        "MAILMODO_API_KEY=YOUR_API_KEY <%= config.bin %> login"
+        "<%= config.bin %> init",
+        "<%= config.bin %> init --url https://myapp.com --yes"
       ],
       "flags": {
         "json": {
@@ -408,11 +401,18 @@
           "name": "yes",
           "allowNo": false,
           "type": "boolean"
+        },
+        "url": {
+          "description": "Product URL to analyze",
+          "name": "url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "login",
+      "id": "init",
       "pluginAlias": "@mailmodo/cli",
       "pluginName": "@mailmodo/cli",
       "pluginType": "core",
@@ -422,16 +422,17 @@
       "relativePath": [
         "dist",
         "commands",
-        "login",
+        "init",
         "index.js"
       ]
     },
-    "logout": {
+    "login": {
       "aliases": [],
       "args": {},
-      "description": "Sign out by removing saved credentials from this machine",
+      "description": "Authenticate with Mailmodo using your API key",
       "examples": [
-        "<%= config.bin %> logout"
+        "<%= config.bin %> login",
+        "MAILMODO_API_KEY=YOUR_API_KEY <%= config.bin %> login"
       ],
       "flags": {
         "json": {
@@ -450,7 +451,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "logout",
+      "id": "login",
       "pluginAlias": "@mailmodo/cli",
       "pluginName": "@mailmodo/cli",
       "pluginType": "core",
@@ -460,17 +461,16 @@
       "relativePath": [
         "dist",
         "commands",
-        "logout",
+        "login",
         "index.js"
       ]
     },
-    "emails": {
+    "logout": {
       "aliases": [],
       "args": {},
-      "description": "List and view configured email sequences",
+      "description": "Sign out by removing saved credentials from this machine",
       "examples": [
-        "<%= config.bin %> emails",
-        "<%= config.bin %> emails --json"
+        "<%= config.bin %> logout"
       ],
       "flags": {
         "json": {
@@ -489,7 +489,7 @@
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "emails",
+      "id": "logout",
       "pluginAlias": "@mailmodo/cli",
       "pluginName": "@mailmodo/cli",
       "pluginType": "core",
@@ -499,7 +499,7 @@
       "relativePath": [
         "dist",
         "commands",
-        "emails",
+        "logout",
         "index.js"
       ]
     },
@@ -932,5 +932,5 @@
       ]
     }
   },
-  "version": "0.0.58-beta.pr60.110"
+  "version": "0.0.59-beta.pr61.111"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mailmodo/cli",
   "description": "Email lifecycle automation for the AI-native builder generation.",
-  "version": "0.0.58-beta.pr60.110",
+  "version": "0.0.59-beta.pr61.111",
   "author": "provishalk",
   "bin": {
     "mailmodo": "bin/run.js"
@@ -51,8 +51,20 @@
   ],
   "homepage": "https://github.com/Mailmodo/mailmodo-cli",
   "keywords": [
-    "oclif"
+    "email",
+    "email-automation",
+    "lifecycle-emails",
+    "onboarding",
+    "transactional-email",
+    "cli",
+    "ai",
+    "mailmodo",
+    "sdk",
+    "saas"
   ],
+  "publishConfig": {
+    "access": "public"
+  },
   "license": "MIT",
   "main": "dist/index.js",
   "type": "module",
@@ -73,9 +85,9 @@
     "lint": "eslint",
     "postpack": "shx rm -f oclif.manifest.json",
     "posttest": "npm run lint",
-    "prepack": "oclif manifest && oclif readme",
+    "prepack": "oclif manifest",
     "test": "mocha --forbid-only \"test/**/*.test.ts\"",
-    "version": "oclif readme && git add README.md",
+    "version": "git add README.md",
     "prepare": "husky"
   },
   "types": "dist/index.d.ts",