@mailmodo/cli 0.0.8 → 0.0.9-beta.pr11.15

package/dist/commands/billing/index.js

@@ -35,7 +35,7 @@ export default class Billing extends BaseCommand {
      * opens Stripe Checkout if no card is on file.
      */
     async showStatus(jsonOutput) {
-        const response = await this.apiClient.get(API_ENDPOINTS.BILLING_STATUS);
+        const response = await this.withApiSpinner({ json: jsonOutput, text: '  Loading billing status...' }, () => this.apiClient.get(API_ENDPOINTS.BILLING_STATUS));
         if (!response.ok) {
             this.handleApiError(response);
         }
@@ -84,9 +84,9 @@ export default class Billing extends BaseCommand {
      * @param {boolean} jsonOutput - Whether to output JSON instead of formatted text.
      */
     async setCap(cap, jsonOutput) {
-        const response = await this.apiClient.patch(API_ENDPOINTS.BILLING_CAP, {
+        const response = await this.withApiSpinner({ json: jsonOutput, text: '  Updating spending cap...' }, () => this.apiClient.patch(API_ENDPOINTS.BILLING_CAP, {
             cap,
-        });
+        }));
         if (!response.ok) {
             this.handleApiError(response);
         }

package/dist/commands/contacts/index.js

@@ -43,7 +43,7 @@ export default class Contacts extends BaseCommand {
      * Displays aggregate contact counts: total, active, unsubscribed, bounced.
      */
     async showSummary(jsonOutput) {
-        const response = await this.apiClient.get(API_ENDPOINTS.CONTACTS);
+        const response = await this.withApiSpinner({ json: jsonOutput, text: '  Loading contacts...' }, () => this.apiClient.get(API_ENDPOINTS.CONTACTS));
         if (!response.ok) {
             this.handleApiError(response);
         }
@@ -62,7 +62,7 @@ export default class Contacts extends BaseCommand {
      * status, properties, and pending emails.
      */
     async searchContact(email, jsonOutput) {
-        const response = await this.apiClient.get(`${API_ENDPOINTS.CONTACTS}/${encodeURIComponent(email)}`);
+        const response = await this.withApiSpinner({ json: jsonOutput, text: '  Looking up contact...' }, () => this.apiClient.get(`${API_ENDPOINTS.CONTACTS}/${encodeURIComponent(email)}`));
         if (!response.ok) {
             if (response.status === 404) {
                 if (jsonOutput) {
@@ -97,7 +97,7 @@ export default class Contacts extends BaseCommand {
      * for the generated file.
      */
     async exportContacts(jsonOutput) {
-        const response = await this.apiClient.get(API_ENDPOINTS.CONTACTS_EXPORT);
+        const response = await this.withApiSpinner({ json: jsonOutput, text: '  Preparing contact export...' }, () => this.apiClient.get(API_ENDPOINTS.CONTACTS_EXPORT));
         if (!response.ok) {
             this.handleApiError(response);
         }
@@ -126,7 +126,7 @@ export default class Contacts extends BaseCommand {
                 return;
             }
         }
-        const response = await this.apiClient.delete(`${API_ENDPOINTS.CONTACTS}/${encodeURIComponent(email)}`);
+        const response = await this.withApiSpinner({ json: jsonOutput, text: '  Deleting contact...' }, () => this.apiClient.delete(`${API_ENDPOINTS.CONTACTS}/${encodeURIComponent(email)}`));
         if (!response.ok) {
             this.handleApiError(response);
         }

package/dist/commands/deploy/index.d.ts

@@ -6,7 +6,24 @@ export default class Deploy extends BaseCommand {
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
+    /**
+     * Fetches current DNS verification status for the deploy flow.
+     *
+     * @param jsonOutput - When true, spinner uses stderr for stdout-safe JSON runs.
+     */
+    private fetchDomainVerifyForDeploy;
     run(): Promise<void>;
+    /**
+     * Lists emails about to be deployed (skipped when `--json` is set).
+     *
+     * @param yamlConfig - Loaded project YAML.
+     * @param jsonOutput - When true, skip human-readable output.
+     */
+    private logPreDeploySummary;
+    /**
+     * Prints the post-deploy success message and SDK install snippet for interactive runs.
+     */
+    private logDeploySuccessInstructions;
     /**
      * Interactive domain setup flow. Collects domain, sender email, and business
      * address from the user, then calls the API to get DNS records to configure.

package/dist/commands/deploy/index.js

@@ -12,11 +12,19 @@ export default class Deploy extends BaseCommand {
     static flags = {
         ...BaseCommand.baseFlags,
     };
+    /**
+     * Fetches current DNS verification status for the deploy flow.
+     *
+     * @param jsonOutput - When true, spinner uses stderr for stdout-safe JSON runs.
+     */
+    fetchDomainVerifyForDeploy(jsonOutput) {
+        return this.withApiSpinner({ json: jsonOutput, text: '  Checking domain verification...' }, () => this.apiClient.get(API_ENDPOINTS.DOMAIN_VERIFY));
+    }
     async run() {
         const { flags } = await this.parse(Deploy);
         await this.ensureAuth();
         const yamlConfig = await this.ensureYaml();
-        const domainVerify = await this.apiClient.get(API_ENDPOINTS.DOMAIN_VERIFY);
+        const domainVerify = await this.fetchDomainVerifyForDeploy(flags.json);
         const domainVerified = domainVerify.ok &&
             domainVerify.data?.spf === 'pass' &&
             domainVerify.data?.dkim === 'pass' &&
@@ -44,14 +52,7 @@ export default class Deploy extends BaseCommand {
             if (!completed)
                 return;
         }
-        if (!flags.json) {
-            this.log(`\n  ${chalk.green('✓')} Domain: ${yamlConfig.project?.domain || 'verified'}\n`);
-            this.log(`  Deploying:`);
-            for (const email of yamlConfig.emails) {
-                this.log(`  ${chalk.green('+')} ${email.id.padEnd(24)} ${email.trigger}`);
-            }
-            this.log('');
-        }
+        this.logPreDeploySummary(yamlConfig, flags.json);
         if (!flags.yes) {
             const proceed = await confirm({
                 default: true,
@@ -62,10 +63,10 @@ export default class Deploy extends BaseCommand {
                 return;
             }
         }
-        const response = await this.apiClient.post(API_ENDPOINTS.SEQUENCES, {
+        const response = await this.withApiSpinner({ json: flags.json, text: '  Deploying email sequences...' }, () => this.apiClient.post(API_ENDPOINTS.SEQUENCES, {
             emails: yamlConfig.emails,
             project: yamlConfig.project,
-        });
+        }));
         if (!response.ok) {
             this.handleApiError(response);
         }
@@ -77,6 +78,28 @@ export default class Deploy extends BaseCommand {
             }, null, 2));
             return;
         }
+        this.logDeploySuccessInstructions();
+    }
+    /**
+     * Lists emails about to be deployed (skipped when `--json` is set).
+     *
+     * @param yamlConfig - Loaded project YAML.
+     * @param jsonOutput - When true, skip human-readable output.
+     */
+    logPreDeploySummary(yamlConfig, jsonOutput) {
+        if (jsonOutput)
+            return;
+        this.log(`\n  ${chalk.green('✓')} Domain: ${yamlConfig.project?.domain || 'verified'}\n`);
+        this.log(`  Deploying:`);
+        for (const email of yamlConfig.emails) {
+            this.log(`  ${chalk.green('+')} ${email.id.padEnd(24)} ${email.trigger}`);
+        }
+        this.log('');
+    }
+    /**
+     * Prints the post-deploy success message and SDK install snippet for interactive runs.
+     */
+    logDeploySuccessInstructions() {
         this.log(`  ${chalk.green('Deployed.')} Emails are live.\n`);
         this.log(`  ${'─'.repeat(53)}`);
         this.log(`  ${chalk.bold('ADD THIS TO YOUR APP (one-time only):')}`);
@@ -125,11 +148,11 @@ export default class Deploy extends BaseCommand {
                 validate: (v) => (v?.trim() ? true : 'Address is required'),
             });
         }
-        const domainResponse = await this.apiClient.post(API_ENDPOINTS.DOMAIN, {
+        const domainResponse = await this.withApiSpinner({ json: flags.json, text: '  Configuring domain...' }, () => this.apiClient.post(API_ENDPOINTS.DOMAIN, {
             address,
             domain,
             fromEmail: senderEmail,
-        });
+        }));
         if (!domainResponse.ok) {
             this.handleApiError(domainResponse);
         }
@@ -171,10 +194,7 @@ export default class Deploy extends BaseCommand {
      * @returns {Promise<boolean>} true if all records pass.
      */
     async verifyDomain(jsonOutput) {
-        if (!jsonOutput) {
-            this.log(`\n  Checking DNS...`);
-        }
-        const verify = await this.apiClient.get(API_ENDPOINTS.DOMAIN_VERIFY);
+        const verify = await this.withApiSpinner({ json: jsonOutput, text: '  Checking DNS...' }, () => this.apiClient.get(API_ENDPOINTS.DOMAIN_VERIFY));
         if (!verify.ok) {
             this.handleApiError(verify);
         }

package/dist/commands/domain/index.js

@@ -72,11 +72,11 @@ export default class Domain extends BaseCommand {
                 validate: (v) => (v?.trim() ? true : 'Address is required'),
             });
         }
-        const response = await this.apiClient.post(API_ENDPOINTS.DOMAIN, {
+        const response = await this.withApiSpinner({ json: flags.json, text: '  Configuring domain...' }, () => this.apiClient.post(API_ENDPOINTS.DOMAIN, {
             address,
             domain,
             fromEmail: senderEmail,
-        });
+        }));
         if (!response.ok) {
             this.handleApiError(response);
         }
@@ -112,10 +112,7 @@ export default class Domain extends BaseCommand {
      * Calls the domain verification API and displays pass/fail for each DNS record.
      */
     async verifyDomain(jsonOutput) {
-        if (!jsonOutput) {
-            this.log(`\n  Checking DNS...`);
-        }
-        const response = await this.apiClient.get(API_ENDPOINTS.DOMAIN_VERIFY);
+        const response = await this.withApiSpinner({ json: jsonOutput, text: '  Checking DNS...' }, () => this.apiClient.get(API_ENDPOINTS.DOMAIN_VERIFY));
         if (!response.ok) {
             this.handleApiError(response);
         }
@@ -148,7 +145,7 @@ export default class Domain extends BaseCommand {
      * bounce rate, and spam complaint rate.
      */
     async showDomainStatus(jsonOutput) {
-        const response = await this.apiClient.get(API_ENDPOINTS.DOMAIN_STATUS);
+        const response = await this.withApiSpinner({ json: jsonOutput, text: '  Loading domain status...' }, () => this.apiClient.get(API_ENDPOINTS.DOMAIN_STATUS));
         if (!response.ok) {
             this.handleApiError(response);
         }

package/dist/commands/edit/index.js

@@ -39,7 +39,7 @@ export default class Edit extends BaseCommand {
                 validate: (value) => value?.trim() ? true : 'Please describe the change',
             });
         }
-        const response = await this.apiClient.post(API_ENDPOINTS.EDIT, {
+        const response = await this.withApiSpinner({ json: flags.json, text: '  Applying AI edits...' }, () => this.apiClient.post(API_ENDPOINTS.EDIT, {
             changeRequest: changeDescription,
             currentEmail: {
                 condition: email.condition,
@@ -50,7 +50,7 @@ export default class Edit extends BaseCommand {
                 subject: email.subject,
                 trigger: email.trigger,
             },
-        });
+        }));
         if (!response.ok) {
             this.handleApiError(response);
         }

package/dist/commands/init/index.js

@@ -12,6 +12,23 @@ function isValidUrl(value) {
         return false;
     }
 }
+/**
+ * Prints the human-readable analysis summary using the provided line writer.
+ * Use stderr when `--json` is set so stdout stays free for machine-readable JSON.
+ *
+ * @param analysis - Parsed analyze API payload.
+ * @param logLine - Line writer (typically bound `this.log` or `this.logToStderr`).
+ */
+function logAnalysisSummary(analysis, logLine) {
+    logLine(`  Detected:`);
+    logLine(`  - Type:    ${analysis.businessType} — ${analysis.description}`);
+    logLine(`  - Model:   ${analysis.pricingModel}`);
+    logLine(`  - Users:   ${analysis.targetUser}`);
+    if (analysis.events?.length) {
+        logLine(`  - Events:  ${analysis.events.join(', ')}`);
+    }
+    logLine('');
+}
 export default class Init extends BaseCommand {
     static description = 'Analyze your product and generate email sequences';
     static examples = [
@@ -38,22 +55,22 @@ export default class Init extends BaseCommand {
                 },
             });
         }
-        this.log(`\n  Analyzing your product...`);
-        this.log(`  Scraping: homepage, pricing, features\n`);
-        const analysisResponse = await this.apiClient.post(API_ENDPOINTS.ANALYZE, { url: productUrl });
+        const analysisResponse = await this.withApiSpinner({
+            json: flags.json,
+            text: '  Analyzing your product — scraping homepage, pricing, features',
+        }, () => this.apiClient.post(API_ENDPOINTS.ANALYZE, {
+            url: productUrl,
+        }));
         if (!analysisResponse.ok) {
             this.handleApiError(analysisResponse);
         }
         const analysis = analysisResponse.data;
-        if (!flags.json) {
-            this.log(`  Detected:`);
-            this.log(`  - Type:    ${analysis.businessType} — ${analysis.description}`);
-            this.log(`  - Model:   ${analysis.pricingModel}`);
-            this.log(`  - Users:   ${analysis.targetUser}`);
-            if (analysis.events?.length) {
-                this.log(`  - Events:  ${analysis.events.join(', ')}`);
-            }
-            this.log('');
+        const shouldShowAnalysisSummary = !flags.json || !flags.yes;
+        if (shouldShowAnalysisSummary) {
+            const logSummary = flags.json && !flags.yes
+                ? this.logToStderr.bind(this)
+                : this.log.bind(this);
+            logAnalysisSummary(analysis, logSummary);
         }
         let analysisPayload = analysis;
         if (!flags.yes) {
@@ -89,12 +106,13 @@ export default class Init extends BaseCommand {
                 analysisPayload = JSON.parse(editedAnalysis);
             }
         }
-        this.log('analysisPayload', analysisPayload);
-        this.log('\n  Generating emails...\n');
-        const generateResponse = await this.apiClient.post(API_ENDPOINTS.GENERATE, {
+        const generateResponse = await this.withApiSpinner({
+            json: flags.json,
+            text: '  Generating email templates...',
+        }, () => this.apiClient.post(API_ENDPOINTS.GENERATE, {
             analysis: analysisPayload,
             productUrl,
-        });
+        }));
         if (!generateResponse.ok) {
             this.handleApiError(generateResponse);
         }

package/dist/commands/login/index.js

@@ -3,7 +3,7 @@ import chalk from 'chalk';
 import open from 'open';
 import { BaseCommand } from '../../lib/base-command.js';
 import { ApiClient } from '../../lib/api-client.js';
-import { saveConfig } from '../../lib/config.js';
+import { loadConfig, saveConfig } from '../../lib/config.js';
 import { API_ENDPOINTS, SIGNUP_URL } from '../../lib/constants.js';
 export default class Login extends BaseCommand {
     static description = 'Authenticate with Mailmodo using your API key';
@@ -16,7 +16,30 @@ export default class Login extends BaseCommand {
     };
     async run() {
         const { flags } = await this.parse(Login);
-        let apiKey = process.env.MAILMODO_API_KEY;
+        const envKey = process.env.MAILMODO_API_KEY;
+        if (!envKey) {
+            const existing = await loadConfig();
+            if (existing?.apiKey) {
+                if (flags.json) {
+                    this.log(JSON.stringify({
+                        accountName: existing.accountName ?? null,
+                        email: existing.email ?? null,
+                        freeRemaining: existing.freeRemaining ?? null,
+                        status: 'already_logged_in',
+                    }, null, 2));
+                    return;
+                }
+                this.log('\n  You are already logged in.\n');
+                const emailDisplay = existing.email?.trim()
+                    ? chalk.green(existing.email.trim())
+                    : chalk.dim('(unknown)');
+                this.log(`  Email: ${emailDisplay}\n`);
+                this.log(`  ${chalk.dim('1.')} Run ${chalk.cyan('mailmodo init')} to generate an email sequence.`);
+                this.log(`  ${chalk.dim('2.')} Run ${chalk.cyan('mailmodo logout')} to log in with another account.\n`);
+                return;
+            }
+        }
+        let apiKey = envKey;
         if (apiKey) {
             this.log('Detected MAILMODO_API_KEY from environment.');
         }
@@ -34,15 +57,13 @@ export default class Login extends BaseCommand {
                 validate(value) {
                     if (!value?.trim())
                         return 'API key is required';
-                    if (!value.startsWith('mm_'))
-                        return 'Invalid API key format. Keys start with mm_';
                     return true;
                 },
             });
         }
         const trimmedKey = apiKey.trim();
         const client = new ApiClient(trimmedKey);
-        const response = await client.get(API_ENDPOINTS.AUTH_VALIDATE);
+        const response = await this.withApiSpinner({ json: flags.json, text: '  Validating API key...' }, () => client.post(API_ENDPOINTS.AUTH_VALIDATE, {}));
         if (!response.ok) {
             this.handleApiError(response);
         }

package/dist/commands/logout/index.d.ts

@@ -0,0 +1,10 @@
+import { BaseCommand } from '../../lib/base-command.js';
+export default class Logout extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/logout/index.js

@@ -0,0 +1,28 @@
+import chalk from 'chalk';
+import { BaseCommand } from '../../lib/base-command.js';
+import { clearConfig, loadConfig } from '../../lib/config.js';
+export default class Logout extends BaseCommand {
+    static description = 'Sign out by removing saved credentials from this machine';
+    static examples = ['<%= config.bin %> logout'];
+    static flags = {
+        ...BaseCommand.baseFlags,
+    };
+    async run() {
+        const { flags } = await this.parse(Logout);
+        const config = await loadConfig();
+        if (!config?.apiKey) {
+            if (flags.json) {
+                this.log(JSON.stringify({ status: 'not_logged_in' }, null, 2));
+                return;
+            }
+            this.log('You are not logged in.');
+            return;
+        }
+        await clearConfig();
+        if (flags.json) {
+            this.log(JSON.stringify({ status: 'logged_out' }, null, 2));
+            return;
+        }
+        this.log(`\n  Signed out. Run ${chalk.cyan('mailmodo login')} to authenticate again.\n`);
+    }
+}

package/dist/commands/logs/index.js

@@ -26,7 +26,7 @@ export default class Logs extends BaseCommand {
             params.email = flags.email;
         if (flags.failed)
             params.failed = 'true';
-        const response = await this.apiClient.get(API_ENDPOINTS.LOGS, params);
+        const response = await this.withApiSpinner({ json: flags.json, text: '  Loading email logs...' }, () => this.apiClient.get(API_ENDPOINTS.LOGS, params));
         if (!response.ok) {
             this.handleApiError(response);
         }

package/dist/commands/preview/index.js

@@ -125,9 +125,9 @@ export default class Preview extends BaseCommand {
      */
     async sendTestEmail(emailId, toAddress, jsonOutput) {
         await this.ensureAuth();
-        const response = await this.apiClient.post(`${API_ENDPOINTS.PREVIEW}/${emailId}/send`, {
+        const response = await this.withApiSpinner({ json: jsonOutput, text: '  Sending test email...' }, () => this.apiClient.post(`${API_ENDPOINTS.PREVIEW}/${emailId}/send`, {
             to: toAddress,
-        });
+        }));
         if (!response.ok) {
             this.handleApiError(response);
         }

package/dist/commands/settings/index.d.ts

@@ -14,6 +14,7 @@ export default class Settings extends BaseCommand {
      * and logoUrl in the project config.
      *
      * @param {import('../../lib/yaml-config.js').MailmodoYaml} yamlConfig - The full YAML config to update and save.
+     * @param {boolean} jsonOutput - When true, spinner uses stderr so stdout stays clean.
      */
     private handleLogoUpload;
 }

package/dist/commands/settings/index.js

@@ -89,7 +89,7 @@ export default class Settings extends BaseCommand {
                     return;
                 }
                 if (editKey === 'logo_file') {
-                    await this.handleLogoUpload(yamlConfig);
+                    await this.handleLogoUpload(yamlConfig, flags.json);
                     return;
                 }
                 if (editKey === 'email_style') {
@@ -122,8 +122,9 @@ export default class Settings extends BaseCommand {
      * and logoUrl in the project config.
      *
      * @param {import('../../lib/yaml-config.js').MailmodoYaml} yamlConfig - The full YAML config to update and save.
+     * @param {boolean} jsonOutput - When true, spinner uses stderr so stdout stays clean.
      */
-    async handleLogoUpload(yamlConfig) {
+    async handleLogoUpload(yamlConfig, jsonOutput) {
         const logoPath = await input({ message: 'Path to logo file:' });
         const resolvedPath = resolve(logoPath);
         if (!existsSync(resolvedPath)) {
@@ -134,7 +135,7 @@ export default class Settings extends BaseCommand {
         const fileBuffer = await readFile(resolvedPath);
         const formData = new FormData();
         formData.append('logo', new Blob([new Uint8Array(fileBuffer)]), logoPath.split(/[/\\]/).pop() || 'logo.png');
-        const response = await this.apiClient.postFormData(API_ENDPOINTS.ASSETS_LOGO, formData);
+        const response = await this.withApiSpinner({ json: jsonOutput, text: '  Uploading logo...' }, () => this.apiClient.postFormData(API_ENDPOINTS.ASSETS_LOGO, formData));
         if (!response.ok) {
             this.handleApiError(response);
         }

package/dist/commands/status/index.js

@@ -13,7 +13,7 @@ export default class Status extends BaseCommand {
     async run() {
         const { flags } = await this.parse(Status);
         await this.ensureAuth();
-        const response = await this.apiClient.get(API_ENDPOINTS.ANALYTICS);
+        const response = await this.withApiSpinner({ json: flags.json, text: '  Loading analytics...' }, () => this.apiClient.get(API_ENDPOINTS.ANALYTICS));
         if (!response.ok) {
             this.handleApiError(response);
         }

package/dist/lib/api-client.d.ts

@@ -1,26 +1,29 @@
+/**
+ * Request context attached to API responses for troubleshooting failed calls.
+ * Only the resolved URL is stored; it encodes origin, path, and query string.
+ */
+export interface ApiRequestDebugInfo {
+    /** Node/DNS/network error code when `fetch` throws before an HTTP response. */
+    causeCode?: string;
+    /** Fully resolved request URL (origin, path, and query string). */
+    fullUrl: string;
+    /** Truncated JSON summary of a non-empty error response body, when available. */
+    responseSummary?: string;
+}
 export interface ApiResponse<T = Record<string, unknown>> {
     data: T;
+    /** Populated for tracing; especially useful when `ok` is false. */
+    debug?: ApiRequestDebugInfo;
     error?: string;
     ok: boolean;
     status: number;
 }
-/**
- * HTTP client for the Mailmodo CLI API.
- * Wraps the native fetch API with Bearer token authentication,
- * consistent error handling, and typed responses.
- *
- * All requests include:
- * - Authorization header with the user's API key
- * - Content-Type: application/json
- * - User-Agent: @mailmodo/cli
- *
- * Network errors (ECONNREFUSED, ENOTFOUND) return a friendly message
- * indicating the API may not be available, rather than a raw stack trace.
- */
 export declare class ApiClient {
     private apiKey;
     private baseUrl;
     constructor(apiKey: string);
+    private resolveUrl;
+    private requestDebug;
     /**
      * Sends an HTTP request to the Mailmodo API and returns a typed response.
      *

package/dist/lib/api-client.js

@@ -12,6 +12,22 @@ import { API_BASE_URL } from './constants.js';
  * Network errors (ECONNREFUSED, ENOTFOUND) return a friendly message
  * indicating the API may not be available, rather than a raw stack trace.
  */
+const RESPONSE_BODY_DEBUG_MAX = 800;
+function summarizeResponseBody(data) {
+    if (data === null || data === undefined)
+        return undefined;
+    try {
+        const s = JSON.stringify(data);
+        if (s === '{}' || s === '[]')
+            return undefined;
+        return s.length > RESPONSE_BODY_DEBUG_MAX
+            ? `${s.slice(0, RESPONSE_BODY_DEBUG_MAX)}…`
+            : s;
+    }
+    catch {
+        return undefined;
+    }
+}
 export class ApiClient {
     apiKey;
     baseUrl;
@@ -19,6 +35,18 @@ export class ApiClient {
         this.baseUrl = API_BASE_URL;
         this.apiKey = apiKey;
     }
+    resolveUrl(path, params) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                url.searchParams.set(key, value);
+            }
+        }
+        return url;
+    }
+    requestDebug(url) {
+        return { fullUrl: url.toString() };
+    }
     /**
      * Sends an HTTP request to the Mailmodo API and returns a typed response.
      *
@@ -31,12 +59,8 @@ export class ApiClient {
      *   data (parsed JSON body), and optional error (string message on failure).
      */
     async request(method, path, body, params) {
-        const url = new URL(`${this.baseUrl}${path}`);
-        if (params) {
-            for (const [key, value] of Object.entries(params)) {
-                url.searchParams.set(key, value);
-            }
-        }
+        const url = this.resolveUrl(path, params);
+        const debug = this.requestDebug(url);
         const headers = {
             Authorization: `Bearer ${this.apiKey}`,
             'Content-Type': 'application/json',
@@ -51,8 +75,13 @@ export class ApiClient {
             const data = await response.json().catch(() => ({}));
             if (!response.ok) {
                 const errorData = data;
+                const summary = summarizeResponseBody(data);
                 return {
                     data: data,
+                    debug: {
+                        ...debug,
+                        responseSummary: summary,
+                    },
                     error: errorData?.message ||
                         errorData?.error ||
                         `Request failed with status ${response.status}`,
@@ -65,8 +94,13 @@ export class ApiClient {
         catch (error) {
             const err = error;
             const isConnectionError = err?.cause?.code === 'ECONNREFUSED' || err?.cause?.code === 'ENOTFOUND';
+            const causeCode = err?.cause?.code;
             return {
                 data: {},
+                debug: {
+                    ...debug,
+                    ...(causeCode ? { causeCode } : {}),
+                },
                 error: isConnectionError
                     ? 'Cannot connect to Mailmodo API. The API service may not be available yet.'
                     : err?.message || 'An unexpected network error occurred.',
@@ -88,7 +122,8 @@ export class ApiClient {
         return this.request('POST', path, body);
     }
     async postFormData(path, formData) {
-        const url = new URL(`${this.baseUrl}${path}`);
+        const url = this.resolveUrl(path);
+        const debug = this.requestDebug(url);
         try {
             const response = await fetch(url.toString(), {
                 body: formData,
@@ -101,8 +136,13 @@ export class ApiClient {
             const data = await response.json().catch(() => ({}));
             if (!response.ok) {
                 const errorData = data;
+                const summary = summarizeResponseBody(data);
                 return {
                     data: data,
+                    debug: {
+                        ...debug,
+                        responseSummary: summary,
+                    },
                     error: errorData?.message ||
                         errorData?.error ||
                         `Upload failed with status ${response.status}`,
@@ -114,8 +154,13 @@ export class ApiClient {
         }
         catch (error) {
             const err = error;
+            const causeCode = err?.cause?.code;
             return {
                 data: {},
+                debug: {
+                    ...debug,
+                    ...(causeCode ? { causeCode } : {}),
+                },
                 error: err?.message || 'File upload failed.',
                 ok: false,
                 status: 0,

package/dist/lib/base-command.d.ts

@@ -1,5 +1,5 @@
 import { Command } from '@oclif/core';
-import { ApiClient } from './api-client.js';
+import { ApiClient, type ApiRequestDebugInfo } from './api-client.js';
 import { type MailmodoConfig } from './config.js';
 import { type MailmodoYaml } from './yaml-config.js';
 /**
@@ -22,6 +22,22 @@ export declare abstract class BaseCommand extends Command {
      * @returns {Promise<MailmodoConfig>} The resolved configuration containing the API key.
      */
     protected ensureAuth(): Promise<MailmodoConfig>;
+    /**
+     * Runs an async function (typically an API call) while showing a cyan ora spinner.
+     * When `options.json` is true, the leading blank line is written to stderr so stdout stays
+     * free for machine-readable JSON (e.g. piping to `jq`).
+     *
+     * @template T - Resolved type of the work promise (often the API client response).
+     * @param {{ json: boolean; text: string }} options - Spinner options.
+     * @param {boolean} options.json - If true, stderr for the blank line before the spinner.
+     * @param {string} options.text - Spinner label (often two leading spaces).
+     * @param {() => Promise<T>} work - Zero-argument async function that performs the request.
+     * @returns {Promise<T>} The fulfilled value from `work`.
+     */
+    protected withApiSpinner<T>(options: {
+        json: boolean;
+        text: string;
+    }, work: () => Promise<T>): Promise<T>;
     /**
      * Loads and returns the mailmodo.yaml configuration from the current directory.
      * Exits with an error if the file is not found, directing the user to run init.
@@ -34,12 +50,24 @@ export declare abstract class BaseCommand extends Command {
      * Handles a failed API response by mapping HTTP status codes to
      * user-friendly error messages and exiting the process.
      *
-     * @param {{ status: number; error?: string }} response - The API response object with ok=false.
+     * @param {{ status: number; error?: string; debug?: ApiRequestDebugInfo }} response - The API response object with ok=false.
      *   Status 401 prompts re-authentication, 429 indicates rate limiting,
      *   all others display the server's error message or a generic fallback.
+     *   When `debug` is present, extra lines list Full URL, Status, optional Response
+     *   body summary, and optional Error Code (network failures).
      */
     protected handleApiError(response: {
+        debug?: ApiRequestDebugInfo;
         error?: string;
         status: number;
     }): never;
+    /**
+     * Builds the terminal error string for a failed API call, appending request
+     * metadata when {@link ApiRequestDebugInfo} is available.
+     *
+     * @param {string} message - Primary error text (HTTP message or generic).
+     * @param {{ status: number; debug?: ApiRequestDebugInfo }} response - Failed API response.
+     * @returns {string} Message plus indented Request details for troubleshooting.
+     */
+    private formatApiFailure;
 }

package/dist/lib/base-command.js

@@ -1,5 +1,6 @@
 import { Command, Flags } from '@oclif/core';
 import chalk from 'chalk';
+import ora from 'ora';
 import { ApiClient } from './api-client.js';
 import { loadConfig } from './config.js';
 import { loadYaml } from './yaml-config.js';
@@ -39,6 +40,36 @@ export class BaseCommand extends Command {
         this.apiClient = new ApiClient(config.apiKey);
         return config;
     }
+    /**
+     * Runs an async function (typically an API call) while showing a cyan ora spinner.
+     * When `options.json` is true, the leading blank line is written to stderr so stdout stays
+     * free for machine-readable JSON (e.g. piping to `jq`).
+     *
+     * @template T - Resolved type of the work promise (often the API client response).
+     * @param {{ json: boolean; text: string }} options - Spinner options.
+     * @param {boolean} options.json - If true, stderr for the blank line before the spinner.
+     * @param {string} options.text - Spinner label (often two leading spaces).
+     * @param {() => Promise<T>} work - Zero-argument async function that performs the request.
+     * @returns {Promise<T>} The fulfilled value from `work`.
+     */
+    async withApiSpinner(options, work) {
+        if (options.json) {
+            this.logToStderr('');
+        }
+        else {
+            this.log('');
+        }
+        const spinner = ora({
+            color: 'cyan',
+            text: options.text,
+        }).start();
+        try {
+            return await work();
+        }
+        finally {
+            spinner.stop();
+        }
+    }
     /**
      * Loads and returns the mailmodo.yaml configuration from the current directory.
      * Exits with an error if the file is not found, directing the user to run init.
@@ -57,17 +88,48 @@ export class BaseCommand extends Command {
      * Handles a failed API response by mapping HTTP status codes to
      * user-friendly error messages and exiting the process.
      *
-     * @param {{ status: number; error?: string }} response - The API response object with ok=false.
+     * @param {{ status: number; error?: string; debug?: ApiRequestDebugInfo }} response - The API response object with ok=false.
      *   Status 401 prompts re-authentication, 429 indicates rate limiting,
      *   all others display the server's error message or a generic fallback.
+     *   When `debug` is present, extra lines list Full URL, Status, optional Response
+     *   body summary, and optional Error Code (network failures).
      */
     handleApiError(response) {
         if (response.status === 401) {
-            this.error(`Invalid API key. Run ${chalk.cyan('mailmodo login')} to re-authenticate.`);
+            this.error(this.formatApiFailure(`Invalid API key. Run ${chalk.cyan('mailmodo login')} to re-authenticate.`, response));
         }
         if (response.status === 429) {
-            this.error('Rate limit exceeded. Please try again later.');
+            this.error(this.formatApiFailure('Rate limit exceeded. Please try again later.', response));
+        }
+        this.error(this.formatApiFailure(response.error || 'An unexpected API error occurred.', response));
+    }
+    /**
+     * Builds the terminal error string for a failed API call, appending request
+     * metadata when {@link ApiRequestDebugInfo} is available.
+     *
+     * @param {string} message - Primary error text (HTTP message or generic).
+     * @param {{ status: number; debug?: ApiRequestDebugInfo }} response - Failed API response.
+     * @returns {string} Message plus indented Request details for troubleshooting.
+     */
+    formatApiFailure(message, response) {
+        const { debug, status } = response;
+        if (!debug) {
+            return message;
         }
-        this.error(response.error || 'An unexpected API error occurred.');
+        return [
+            message,
+            '',
+            chalk.dim('Request:'),
+            chalk.dim(`  URL: ${debug.fullUrl}`),
+            status > 0
+                ? chalk.dim(`  Status: ${String(status)}`)
+                : chalk.dim('  Status: (No HTTP response — network or client error)'),
+            ...(debug.responseSummary
+                ? [chalk.dim(`  Response: ${debug.responseSummary}`)]
+                : []),
+            ...(debug.causeCode
+                ? [chalk.dim(`  Error Code: ${debug.causeCode}`)]
+                : []),
+        ].join('\n');
     }
 }

package/dist/lib/config.d.ts

@@ -22,6 +22,11 @@ export declare function loadConfig(): Promise<MailmodoConfig | null>;
  *   at minimum an apiKey. Optional fields: email, accountName, freeRemaining.
  */
 export declare function saveConfig(config: MailmodoConfig): Promise<void>;
+/**
+ * Deletes the saved CLI config file (~/.mailmodo/config), removing the stored API key.
+ * No-op if the file does not exist.
+ */
+export declare function clearConfig(): Promise<void>;
 /**
  * Returns the absolute path to the Mailmodo config directory (~/.mailmodo).
  *

package/dist/lib/config.js

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs';
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 const CONFIG_DIR = join(homedir(), '.mailmodo');
@@ -13,7 +13,6 @@ const CONFIG_FILE = join(CONFIG_DIR, 'config');
  *   or null if the config file does not exist or is corrupted.
  */
 export async function loadConfig() {
-    console.log('Loading config from', CONFIG_FILE);
     if (!existsSync(CONFIG_FILE))
         return null;
     try {
@@ -38,6 +37,20 @@ export async function saveConfig(config) {
     }
     await writeFile(CONFIG_FILE, JSON.stringify(config, null, 2));
 }
+/**
+ * Deletes the saved CLI config file (~/.mailmodo/config), removing the stored API key.
+ * No-op if the file does not exist.
+ */
+export async function clearConfig() {
+    if (!existsSync(CONFIG_FILE))
+        return;
+    try {
+        await unlink(CONFIG_FILE);
+    }
+    catch {
+        // Ignore missing file or permission errors; caller can treat as best-effort sign-out.
+    }
+}
 /**
  * Returns the absolute path to the Mailmodo config directory (~/.mailmodo).
  *

package/dist/lib/constants.d.ts

@@ -1,22 +1,22 @@
 export declare const API_BASE_URL: string;
 export declare const API_ENDPOINTS: Readonly<{
-    ANALYTICS: "/analytics";
-    ANALYZE: "/analyze";
-    ASSETS_LOGO: "/assets/logo";
-    AUTH_VALIDATE: "/auth/validate";
-    BILLING_CAP: "/billing/cap";
-    BILLING_STATUS: "/billing/status";
-    CONTACTS: "/contacts";
-    CONTACTS_EXPORT: "/contacts/export";
-    DOMAIN: "/domain";
-    DOMAIN_STATUS: "/domain/status";
-    DOMAIN_VERIFY: "/domain/verify";
-    EDIT: "/edit";
-    EVENTS: "/events";
-    GENERATE: "/generate";
-    LOGS: "/logs";
-    PREVIEW: "/preview";
-    SEQUENCES: "/sequences";
+    ANALYTICS: "/api/analytics";
+    ANALYZE: "/api/analyze";
+    ASSETS_LOGO: "/api/assets/logo";
+    AUTH_VALIDATE: "/api/auth/validate";
+    BILLING_CAP: "/api/billing/cap";
+    BILLING_STATUS: "/api/billing/status";
+    CONTACTS: "/api/contacts";
+    CONTACTS_EXPORT: "/api/contacts/export";
+    DOMAIN: "/api/domain";
+    DOMAIN_STATUS: "/api/domain/status";
+    DOMAIN_VERIFY: "/api/domain/verify";
+    EDIT: "/api/edit";
+    EVENTS: "/api/events";
+    GENERATE: "/api/generate";
+    LOGS: "/api/logs";
+    PREVIEW: "/api/preview";
+    SEQUENCES: "/api/sequences";
 }>;
 export declare const SIGNUP_URL = "https://mailmodo.com/cli";
 export declare const DOCS_URL = "https://mailmodo.com/docs/cli";

package/dist/lib/constants.js

@@ -1,22 +1,27 @@
-export const API_BASE_URL = process.env.MAILMODO_API_URL || 'https://api.mailmodo.com/cli/v1';
+/** Set by `bin/dev.js` when running the CLI locally (tsx bootstrap). */
+const DEV_API_BASE_URL = 'https://app-vertex-debug.azurewebsites.net';
+const PRODUCTION_API_BASE_URL = 'https://api.mailmodo.com';
+export const API_BASE_URL = process.env.MAILMODO_DEV_TSX
+    ? DEV_API_BASE_URL
+    : PRODUCTION_API_BASE_URL;
 export const API_ENDPOINTS = Object.freeze({
-    ANALYTICS: '/analytics',
-    ANALYZE: '/analyze',
-    ASSETS_LOGO: '/assets/logo',
-    AUTH_VALIDATE: '/auth/validate',
-    BILLING_CAP: '/billing/cap',
-    BILLING_STATUS: '/billing/status',
-    CONTACTS: '/contacts',
-    CONTACTS_EXPORT: '/contacts/export',
-    DOMAIN: '/domain',
-    DOMAIN_STATUS: '/domain/status',
-    DOMAIN_VERIFY: '/domain/verify',
-    EDIT: '/edit',
-    EVENTS: '/events',
-    GENERATE: '/generate',
-    LOGS: '/logs',
-    PREVIEW: '/preview',
-    SEQUENCES: '/sequences',
+    ANALYTICS: '/api/analytics',
+    ANALYZE: '/api/analyze',
+    ASSETS_LOGO: '/api/assets/logo',
+    AUTH_VALIDATE: '/api/auth/validate',
+    BILLING_CAP: '/api/billing/cap',
+    BILLING_STATUS: '/api/billing/status',
+    CONTACTS: '/api/contacts',
+    CONTACTS_EXPORT: '/api/contacts/export',
+    DOMAIN: '/api/domain',
+    DOMAIN_STATUS: '/api/domain/status',
+    DOMAIN_VERIFY: '/api/domain/verify',
+    EDIT: '/api/edit',
+    EVENTS: '/api/events',
+    GENERATE: '/api/generate',
+    LOGS: '/api/logs',
+    PREVIEW: '/api/preview',
+    SEQUENCES: '/api/sequences',
 });
 export const SIGNUP_URL = 'https://mailmodo.com/cli';
 export const DOCS_URL = 'https://mailmodo.com/docs/cli';

package/oclif.manifest.json

@@ -153,14 +153,13 @@
         "index.js"
       ]
     },
-    "domain": {
+    "emails": {
       "aliases": [],
       "args": {},
-      "description": "Set up and verify your sending domain",
+      "description": "List and view configured email sequences",
       "examples": [
-        "<%= config.bin %> domain",
-        "<%= config.bin %> domain --verify",
-        "<%= config.bin %> domain --status"
+        "<%= config.bin %> emails",
+        "<%= config.bin %> emails --json"
       ],
       "flags": {
         "json": {
@@ -175,23 +174,11 @@
           "name": "yes",
           "allowNo": false,
           "type": "boolean"
-        },
-        "status": {
-          "description": "Show domain health status",
-          "name": "status",
-          "allowNo": false,
-          "type": "boolean"
-        },
-        "verify": {
-          "description": "Verify DNS records",
-          "name": "verify",
-          "allowNo": false,
-          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "domain",
+      "id": "emails",
       "pluginAlias": "@mailmodo/cli",
       "pluginName": "@mailmodo/cli",
       "pluginType": "core",
@@ -201,17 +188,23 @@
       "relativePath": [
         "dist",
         "commands",
-        "domain",
+        "emails",
         "index.js"
       ]
     },
-    "emails": {
+    "edit": {
       "aliases": [],
-      "args": {},
-      "description": "List and view configured email sequences",
+      "args": {
+        "id": {
+          "description": "Email ID to edit",
+          "name": "id",
+          "required": true
+        }
+      },
+      "description": "Edit an email using AI-assisted natural language changes",
       "examples": [
-        "<%= config.bin %> emails",
-        "<%= config.bin %> emails --json"
+        "<%= config.bin %> edit welcome",
+        "<%= config.bin %> edit welcome --change \"make subject more urgent\" --yes"
       ],
       "flags": {
         "json": {
@@ -226,11 +219,18 @@
           "name": "yes",
           "allowNo": false,
           "type": "boolean"
+        },
+        "change": {
+          "description": "Natural language description of the change",
+          "name": "change",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "emails",
+      "id": "edit",
       "pluginAlias": "@mailmodo/cli",
       "pluginName": "@mailmodo/cli",
       "pluginType": "core",
@@ -240,23 +240,18 @@
       "relativePath": [
         "dist",
         "commands",
-        "emails",
+        "edit",
         "index.js"
       ]
     },
-    "edit": {
+    "domain": {
       "aliases": [],
-      "args": {
-        "id": {
-          "description": "Email ID to edit",
-          "name": "id",
-          "required": true
-        }
-      },
-      "description": "Edit an email using AI-assisted natural language changes",
+      "args": {},
+      "description": "Set up and verify your sending domain",
       "examples": [
-        "<%= config.bin %> edit welcome",
-        "<%= config.bin %> edit welcome --change \"make subject more urgent\" --yes"
+        "<%= config.bin %> domain",
+        "<%= config.bin %> domain --verify",
+        "<%= config.bin %> domain --status"
       ],
       "flags": {
         "json": {
@@ -272,17 +267,22 @@
           "allowNo": false,
           "type": "boolean"
         },
-        "change": {
-          "description": "Natural language description of the change",
-          "name": "change",
-          "hasDynamicHelp": false,
-          "multiple": false,
-          "type": "option"
+        "status": {
+          "description": "Show domain health status",
+          "name": "status",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "verify": {
+          "description": "Verify DNS records",
+          "name": "verify",
+          "allowNo": false,
+          "type": "boolean"
         }
       },
       "hasDynamicHelp": false,
       "hiddenAliases": [],
-      "id": "edit",
+      "id": "domain",
       "pluginAlias": "@mailmodo/cli",
       "pluginName": "@mailmodo/cli",
       "pluginType": "core",
@@ -292,7 +292,7 @@
       "relativePath": [
         "dist",
         "commands",
-        "edit",
+        "domain",
         "index.js"
       ]
     },
@@ -435,6 +435,44 @@
         "index.js"
       ]
     },
+    "logout": {
+      "aliases": [],
+      "args": {},
+      "description": "Sign out by removing saved credentials from this machine",
+      "examples": [
+        "<%= config.bin %> logout"
+      ],
+      "flags": {
+        "json": {
+          "description": "Output as JSON",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "yes": {
+          "char": "y",
+          "description": "Skip confirmation prompts",
+          "name": "yes",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "logout",
+      "pluginAlias": "@mailmodo/cli",
+      "pluginName": "@mailmodo/cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": false,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "logout",
+        "index.js"
+      ]
+    },
     "preview": {
       "aliases": [],
       "args": {
@@ -580,5 +618,5 @@
       ]
     }
   },
-  "version": "0.0.8"
+  "version": "0.0.9-beta.pr11.15"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mailmodo/cli",
   "description": "Email lifecycle automation for the AI-native builder generation.",
-  "version": "0.0.8",
+  "version": "0.0.9-beta.pr11.15",
   "author": "provishalk",
   "bin": {
     "mailmodo": "bin/run.js"
@@ -14,7 +14,8 @@
     "@oclif/plugin-plugins": "^5",
     "chalk": "^5.6.2",
     "js-yaml": "^4.1.1",
-    "open": "^11.0.0"
+    "open": "^11.0.0",
+    "ora": "^9.3.0"
   },
   "devDependencies": {
     "@eslint/compat": "^1",