sendcraft-cli 1.1.0 → 1.2.0

package/README.md

@@ -0,0 +1,551 @@
+# sendcraft-cli
+
+<p align="center">
+  <img src="https://sendcraft.online/logo.png" alt="SendCraft" width="72" />
+</p>
+
+<p align="center">
+  <strong>Official CLI for <a href="https://sendcraft.online">SendCraft</a> — send emails, manage campaigns, verify domains, and more from your terminal.</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/sendcraft-cli"><img src="https://img.shields.io/npm/v/sendcraft-cli?color=6366f1&label=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/sendcraft-cli"><img src="https://img.shields.io/npm/dm/sendcraft-cli?color=10b981&label=downloads" alt="downloads" /></a>
+  <img src="https://img.shields.io/badge/node-%3E%3D14-brightgreen" alt="node" />
+  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT" />
+</p>
+
+---
+
+```
+  ███████╗███████╗███╗   ██╗██████╗  ██████╗██████╗  █████╗ ███████╗████████╗
+  ██╔════╝██╔════╝████╗  ██║██╔══██╗██╔════╝██╔══██╗██╔══██╗██╔════╝╚══██╔══╝
+  ███████╗█████╗  ██╔██╗ ██║██║  ██║██║     ██████╔╝███████║█████╗     ██║
+  ╚════██║██╔══╝  ██║╚██╗██║██║  ██║██║     ██╔══██╗██╔══██║██╔══╝     ██║
+  ███████║███████╗██║ ╚████║██████╔╝╚██████╗██║  ██║██║  ██║██║        ██║
+  ╚══════╝╚══════╝╚═╝  ╚═══╝╚═════╝  ╚═════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝        ╚═╝
+```
+
+## Features
+
+- 📧 **Send emails** directly from the terminal
+- 📊 **View stats** — opens, clicks, bounces, delivery rates
+- 📣 **Manage campaigns** — list and send with optional scheduling
+- 👥 **Manage subscribers** — list, add, remove with tag support
+- 🌐 **Domain verification** — add domains and see DNS records to configure
+- 🔑 **API key management** — create, list, revoke with permission scopes
+- 🔥 **IP warmup status** — animated progress bar, daily limits at a glance
+- 🤖 **MCP setup** — one-command config for Claude Desktop AI agent integration
+- 🎨 **Beautiful output** — gradient colors, spinners, tables, JSON mode
+- 🖥️ **Interactive TUI** — arrow-key menu when launched with no arguments
+
+---
+
+## Installation
+
+```bash
+npm install -g sendcraft-cli
+```
+
+Or run without installing:
+
+```bash
+npx sendcraft-cli
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Log in (opens a menu — browser redirect or email+password)
+sendcraft login
+
+# 2. Send your first email
+sendcraft send --to user@example.com --subject "Hello!" --html "<h1>It works!</h1>"
+
+# 3. Check your stats
+sendcraft emails stats
+```
+
+---
+
+## Authentication
+
+```bash
+sendcraft login                              # Interactive login (browser or email+password)
+sendcraft login --browser                   # Open dashboard to copy an API key
+sendcraft login --api                       # Sign in with email & password
+sendcraft logout                            # Remove saved API key from this machine
+```
+
+### Browser flow
+`sendcraft login --browser` opens `{your-base-url}/dashboard/settings` in your default browser.
+Create or copy an existing API key from the **API Keys** tab, then paste it back in the terminal.
+The key is verified against the API before being saved.
+
+### Email & Password flow
+`sendcraft login --api` prompts for your email and password, signs you in via the API, then
+automatically creates a named **"CLI"** key with full access and saves it locally.
+
+---
+
+## Configuration
+
+```bash
+sendcraft config init                        # Interactive setup wizard
+sendcraft config set-key <apiKey>            # Set your API key manually
+sendcraft config set-url <url>               # Override API base URL (self-hosted)
+sendcraft config show                        # Print current config
+```
+
+Config is stored in `~/.sendcraft/config.json`.
+
+You can also use an environment variable — it takes precedence over the config file:
+
+```bash
+export SENDCRAFT_API_KEY=sc_live_xxxxxxxxxxxxxxxx
+```
+
+---
+
+## Commands
+
+### `sendcraft send` — Send an email
+
+```bash
+sendcraft send --to user@example.com --subject "Hello" --html "<h1>Hi</h1>"
+```
+
+| Flag | Description |
+|------|-------------|
+| `-t, --to <email>` | **Required.** Recipient email address |
+| `-s, --subject <text>` | **Required.** Email subject line |
+| `-H, --html <html>` | HTML body (required if no `--text`) |
+| `-T, --text <text>` | Plain text body (required if no `--html`) |
+| `-f, --from <email>` | From address (uses account default if omitted) |
+| `-r, --reply-to <email>` | Reply-To address |
+| `--json` | Output raw JSON response |
+
+**Examples:**
+
+```bash
+# Send HTML email
+sendcraft send -t alice@example.com -s "Welcome!" -H "<h1>Hey Alice 👋</h1>"
+
+# Send plain text
+sendcraft send -t bob@example.com -s "Quick note" -T "Hey Bob, just checking in."
+
+# Send with custom from + reply-to
+sendcraft send -t user@example.com -s "Hi" -H "<p>Hello</p>" \
+  -f hello@myapp.com -r support@myapp.com
+
+# Output JSON (good for scripting)
+sendcraft send -t user@example.com -s "Test" -T "Body" --json
+```
+
+---
+
+### `sendcraft emails` — Manage emails
+
+```bash
+sendcraft emails list                        # List recent sent emails
+sendcraft emails stats                       # Delivery stats summary
+sendcraft emails get <emailId>               # Details for a single email
+```
+
+#### `emails list`
+
+```bash
+sendcraft emails list
+sendcraft emails list --limit 50
+sendcraft emails list --status delivered
+sendcraft emails list --page 2 --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `-p, --page <n>` | Page number (default: 1) |
+| `-l, --limit <n>` | Items per page (default: 20) |
+| `--status <s>` | Filter: `sent`, `delivered`, `failed`, `scheduled` |
+| `--json` | Output raw JSON |
+
+#### `emails stats`
+
+```bash
+sendcraft emails stats
+```
+
+Shows total sent, delivered, opened, clicked, bounced, failed, open rate, and click rate.
+
+#### `emails get`
+
+```bash
+sendcraft emails get 64f2a1b3c9e4d50012345678
+sendcraft emails get 64f2a1b3c9e4d50012345678 --json
+```
+
+---
+
+### `sendcraft campaigns` — Manage campaigns
+
+```bash
+sendcraft campaigns list                     # List all campaigns
+sendcraft campaigns send <campaignId>        # Send a campaign now
+sendcraft campaigns send <campaignId> --schedule 2025-12-25T09:00:00Z
+```
+
+| Flag | Description |
+|------|-------------|
+| `--schedule <isoDate>` | Schedule for a specific time (ISO 8601) |
+| `--json` | Output raw JSON |
+
+**Examples:**
+
+```bash
+# List campaigns
+sendcraft campaigns list
+
+# Send immediately
+sendcraft campaigns send 64f2a1b3c9e4d50012345678
+
+# Schedule for Christmas morning
+sendcraft campaigns send 64f2a1b3c9e4d50012345678 \
+  --schedule 2025-12-25T09:00:00Z
+```
+
+> Create campaigns in the [dashboard](https://sendcraft.online/dashboard/campaigns) — the CLI handles sending and scheduling.
+
+---
+
+### `sendcraft subscribers` — Manage subscribers
+
+```bash
+sendcraft subscribers list                           # List all subscribers
+sendcraft subscribers add <email> --list <listId>    # Add a subscriber
+sendcraft subscribers remove <subscriberId>          # Remove a subscriber
+```
+
+#### `subscribers list`
+
+```bash
+sendcraft subscribers list
+sendcraft subscribers list --status active --limit 50
+sendcraft subscribers list --page 3 --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `-p, --page <n>` | Page number (default: 1) |
+| `-l, --limit <n>` | Items per page (default: 20) |
+| `--status <s>` | Filter: `active`, `pending`, `unsubscribed` |
+| `--json` | Output raw JSON |
+
+#### `subscribers add`
+
+```bash
+sendcraft subscribers add alice@example.com --list <listId>
+sendcraft subscribers add bob@example.com --list <listId> \
+  --first-name Bob --last-name Smith --tags "vip,beta"
+```
+
+| Flag | Description |
+|------|-------------|
+| `--list <listId>` | **Required.** Target email list ID |
+| `--first-name <name>` | First name |
+| `--last-name <name>` | Last name |
+| `--tags <tags>` | Comma-separated tags |
+| `--json` | Output raw JSON |
+
+#### `subscribers remove`
+
+```bash
+sendcraft subscribers remove 64f2a1b3c9e4d50012345678
+```
+
+---
+
+### `sendcraft domains` — Manage sender domains
+
+```bash
+sendcraft domains list                       # List all domains
+sendcraft domains add <domain>               # Add a new domain + show DNS records
+sendcraft domains verify <domainId>          # Re-check DNS verification
+sendcraft domains records <domainId>         # Show DNS records to configure
+```
+
+**Full workflow:**
+
+```bash
+# 1. Add your domain
+sendcraft domains add mail.myapp.com
+
+# Output shows DNS records to add:
+#   SPF   — TXT   _spf.mail.myapp.com
+#   DKIM  — TXT   sendcraft._domainkey.mail.myapp.com
+#   DMARC — TXT   _dmarc.mail.myapp.com
+#   BIMI  — TXT   default._bimi.mail.myapp.com (optional)
+
+# 2. Add those records in your DNS provider, then:
+sendcraft domains verify <domainId>
+
+# Check again anytime:
+sendcraft domains records <domainId>
+```
+
+> DNS propagation can take up to 48 hours.
+
+---
+
+### `sendcraft keys` — Manage API keys
+
+```bash
+sendcraft keys list                          # List all API keys
+sendcraft keys create <name>                 # Create a new key
+sendcraft keys revoke <keyId>                # Permanently revoke a key
+```
+
+#### `keys create`
+
+```bash
+# Full access key (default)
+sendcraft keys create "Production"
+
+# Send-only key (cannot manage campaigns, templates, subscribers)
+sendcraft keys create "Frontend App" --permissions sending_access
+
+# Restrict to specific sender domains
+sendcraft keys create "Marketing Tool" --domains "newsletter.myapp.com,promo.myapp.com"
+```
+
+| Flag | Description |
+|------|-------------|
+| `--permissions <type>` | `full_access` (default) or `sending_access` |
+| `--domains <list>` | Comma-separated allowed sender domains |
+| `--json` | Output raw JSON |
+
+> ⚠️ The key is shown **once only**. Copy it immediately.
+
+#### `keys revoke`
+
+```bash
+sendcraft keys revoke 64f2a1b3c9e4d50012345678
+```
+
+---
+
+### `sendcraft warmup` — IP warmup status
+
+```bash
+sendcraft warmup
+sendcraft warmup --json
+```
+
+Shows an animated progress bar, current warmup day, today's send count vs daily limit, and percentage complete.
+
+**Warmup schedule:**
+
+| Day | Daily limit |
+|-----|-------------|
+| 1   | 50 |
+| 2   | 100 |
+| 3   | 250 |
+| 4   | 500 |
+| 5   | 1,000 |
+| 7   | 3,500 |
+| 14  | 7,500 |
+| 21  | 15,000 |
+| 30  | 35,000 |
+| 45  | 75,000 |
+| 60+ | **Unlimited** |
+
+---
+
+### `sendcraft mcp` — MCP server for AI agents
+
+Connect SendCraft to **Claude Desktop** (or any MCP-compatible AI agent) so it can send emails on your behalf — no API calls needed.
+
+```bash
+sendcraft mcp info                           # Print Claude Desktop config snippet
+sendcraft mcp install                        # Install sendcraft-mcp globally
+```
+
+#### Setup in 2 steps
+
+```bash
+# 1. Install the MCP server
+sendcraft mcp install
+
+# 2. Print the config to add to Claude Desktop
+sendcraft mcp info
+```
+
+Paste the printed JSON into:
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+After restarting Claude Desktop, you can say:
+
+> *"Send a welcome email to alice@example.com"*
+
+...and Claude will call `sendcraft_send_email` natively.
+
+**Available MCP tools:** `sendcraft_send_email`, `sendcraft_batch_send`, `sendcraft_list_emails`, `sendcraft_get_stats`, `sendcraft_list_campaigns`, `sendcraft_send_campaign`, `sendcraft_list_subscribers`, `sendcraft_add_subscriber`, `sendcraft_list_templates`, `sendcraft_list_domains`, `sendcraft_verify_domain`, `sendcraft_get_warmup_status`, and more.
+
+---
+
+## Interactive Mode
+
+Launch `sendcraft` with no arguments to open a full-screen arrow-key TUI:
+
+```bash
+sendcraft
+```
+
+```
+  ✦ SendCraft CLI v1.1.0
+
+  ? What would you like to do?
+  ❯ 📧  Send Email
+    📋  Emails
+    📣  Campaigns
+    👥  Subscribers
+    🌐  Domains
+    🔑  API Keys
+    🔥  IP Warmup
+    🤖  MCP Setup
+    🔐  Login
+    ⚙️   Config
+    ✗   Exit
+```
+
+Navigate with **↑ ↓** arrow keys, select with **Enter**.
+
+---
+
+## JSON Output
+
+Every command supports `--json` for machine-readable output — useful in shell scripts and CI/CD pipelines:
+
+```bash
+# Get email stats as JSON
+sendcraft emails stats --json | jq '.stats.openRate'
+
+# List campaigns as JSON
+sendcraft campaigns list --json | jq '.campaigns[].name'
+
+# Pipe email ID after sending
+ID=$(sendcraft send -t x@y.com -s "Hi" -T "Hello" --json | jq -r '.emailId')
+echo "Sent: $ID"
+```
+
+---
+
+## CI/CD Usage
+
+Use `SENDCRAFT_API_KEY` as an environment variable — no config file needed:
+
+```yaml
+# GitHub Actions example
+- name: Send deployment notification
+  env:
+    SENDCRAFT_API_KEY: ${{ secrets.SENDCRAFT_API_KEY }}
+  run: |
+    npx sendcraft-cli send \
+      --to team@myapp.com \
+      --subject "🚀 Deployed to production" \
+      --html "<p>Deploy complete. Commit: ${{ github.sha }}</p>"
+```
+
+```bash
+# Shell script
+export SENDCRAFT_API_KEY=sc_live_xxx
+
+npx sendcraft-cli send \
+  --to "$RECIPIENT" \
+  --subject "Build $BUILD_NUMBER passed" \
+  --text "All tests passed. See $BUILD_URL"
+```
+
+---
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SENDCRAFT_API_KEY` | API key — overrides config file |
+| `SENDCRAFT_API_URL` | API base URL — for self-hosted deployments |
+
+---
+
+## Self-Hosted / Custom API URL
+
+If you run your own SendCraft instance:
+
+```bash
+sendcraft config set-url https://api.myinstance.com/api
+# or
+export SENDCRAFT_API_URL=https://api.myinstance.com/api
+```
+
+---
+
+## All Commands at a Glance
+
+```
+sendcraft                                   Interactive TUI (no args)
+
+sendcraft login                             Log in (browser or email+password)
+sendcraft login --browser                   Open dashboard to copy API key
+sendcraft login --api                       Sign in with email & password
+sendcraft logout                            Remove saved API key
+
+sendcraft config init                       Interactive config wizard
+sendcraft config set-key <key>              Set API key manually
+sendcraft config set-url <url>              Set API base URL
+sendcraft config show                       Show current config
+
+sendcraft send                              Send a transactional email
+  -t <email>  -s <subject>  -H <html>
+
+sendcraft emails list                       List sent emails
+sendcraft emails stats                      Delivery stats
+sendcraft emails get <id>                   Single email details
+
+sendcraft campaigns list                    List campaigns
+sendcraft campaigns send <id>               Send / schedule a campaign
+
+sendcraft subscribers list                  List subscribers
+sendcraft subscribers add <email>           Add a subscriber
+sendcraft subscribers remove <id>           Remove a subscriber
+
+sendcraft domains list                      List domains
+sendcraft domains add <domain>              Add domain + show DNS records
+sendcraft domains verify <id>               Trigger DNS check
+sendcraft domains records <id>              Show DNS records
+
+sendcraft keys list                         List API keys
+sendcraft keys create <name>                Create API key
+sendcraft keys revoke <id>                  Revoke API key
+
+sendcraft warmup                            IP warmup status
+
+sendcraft mcp info                          Claude Desktop config snippet
+sendcraft mcp install                       Install sendcraft-mcp globally
+```
+
+---
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`sendcraft-sdk`](https://www.npmjs.com/package/sendcraft-sdk) | Node.js / TypeScript SDK |
+| [`sendcraft-sdk` (PyPI)](https://pypi.org/project/sendcraft-sdk/) | Python SDK |
+| [`sendcraft-mcp`](https://www.npmjs.com/package/sendcraft-mcp) | MCP server for AI agents |
+
+---
+
+## License
+
+MIT © [SendCraft](https://sendcraft.online)

package/bin/sendcraft.js

@@ -11,6 +11,25 @@ program
   .description('Official SendCraft CLI')
   .version(pkg.version, '-v, --version');
 
+program.addCommand(require('../lib/commands/login'));
+
+// sendcraft logout — convenience alias that clears the stored API key
+const { Command } = require('commander');
+const logoutCmd = new Command('logout')
+  .description('Remove the stored API key from this machine')
+  .action(() => {
+    const { load, save, CONFIG_FILE } = require('../lib/config');
+    const cfg = load();
+    if (!cfg.api_key) {
+      console.log(chalk.yellow('  ⚠  No API key stored — already logged out.'));
+      return;
+    }
+    delete cfg.api_key;
+    save(cfg);
+    console.log(chalk.green('  ✓ ') + chalk.bold('Logged out.') + chalk.dim(' Key removed from ' + CONFIG_FILE));
+  });
+program.addCommand(logoutCmd);
+
 program.addCommand(require('../lib/commands/config'));
 program.addCommand(require('../lib/commands/send'));
 program.addCommand(require('../lib/commands/emails'));

package/lib/client.js

@@ -7,11 +7,94 @@ const http = require('http');
 const { URL } = require('url');
 const { getApiKey, getBaseUrl } = require('./config');
 
+/** Make a request with an explicit bearer token instead of stored API key */
+function requestWithToken(method, path, body, token) {
+  return new Promise((resolve, reject) => {
+    const fullUrl = new URL(getBaseUrl() + path);
+    const isHttps = fullUrl.protocol === 'https:';
+    const mod = isHttps ? require('https') : require('http');
+    const payload = body ? JSON.stringify(body) : null;
+    const options = {
+      hostname: fullUrl.hostname,
+      port: fullUrl.port || (isHttps ? 443 : 80),
+      path: fullUrl.pathname + fullUrl.search,
+      method,
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        ...(payload ? { 'Content-Length': Buffer.byteLength(payload) } : {}),
+      },
+    };
+    const req = mod.request(options, (res) => {
+      let data = '';
+      res.on('data', (chunk) => (data += chunk));
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(data);
+          if (res.statusCode >= 400) {
+            const err = new Error(json.error || json.message || `HTTP ${res.statusCode}`);
+            err.status = res.statusCode;
+            err.body = json;
+            return reject(err);
+          }
+          resolve(json);
+        } catch {
+          reject(new Error(`Invalid JSON response (status ${res.statusCode})`));
+        }
+      });
+    });
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+/** Make a request with no auth header (for public endpoints like /auth/login) */
+function requestNoAuth(method, path, body = null) {
+  return new Promise((resolve, reject) => {
+    const fullUrl = new URL(getBaseUrl() + path);
+    const isHttps = fullUrl.protocol === 'https:';
+    const mod = isHttps ? require('https') : require('http');
+    const payload = body ? JSON.stringify(body) : null;
+    const options = {
+      hostname: fullUrl.hostname,
+      port: fullUrl.port || (isHttps ? 443 : 80),
+      path: fullUrl.pathname + fullUrl.search,
+      method,
+      headers: {
+        'Content-Type': 'application/json',
+        ...(payload ? { 'Content-Length': Buffer.byteLength(payload) } : {}),
+      },
+    };
+    const req = mod.request(options, (res) => {
+      let data = '';
+      res.on('data', (chunk) => (data += chunk));
+      res.on('end', () => {
+        try {
+          const json = JSON.parse(data);
+          if (res.statusCode >= 400) {
+            const err = new Error(json.error || json.message || `HTTP ${res.statusCode}`);
+            err.status = res.statusCode;
+            err.body = json;
+            return reject(err);
+          }
+          resolve(json);
+        } catch {
+          reject(new Error(`Invalid JSON response (status ${res.statusCode})`));
+        }
+      });
+    });
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
 function request(method, path, body = null) {
   return new Promise((resolve, reject) => {
     const apiKey = getApiKey();
     if (!apiKey) {
-      return reject(new Error('No API key configured. Run: sendcraft config set-key <key>'));
+      return reject(new Error('No API key configured. Run: sendcraft login'));
     }
 
     const fullUrl = new URL(getBaseUrl() + path);
@@ -60,4 +143,7 @@ module.exports = {
   get: (path) => request('GET', path),
   post: (path, body) => request('POST', path, body),
   delete: (path) => request('DELETE', path),
+  postNoAuth: (path, body) => requestNoAuth('POST', path, body),
+  postWithToken: (path, body, token) => requestWithToken('POST', path, body, token),
+  getWithToken: (path, token) => requestWithToken('GET', path, null, token),
 };

package/lib/commands/login.js

@@ -0,0 +1,206 @@
+/**
+ * sendcraft login
+ *
+ * Two flows:
+ *   1. Browser — opens the dashboard settings page so the user can copy their API key
+ *   2. Email + Password — calls /auth/login, then auto-creates a "CLI" API key
+ *
+ * URLs are derived from the configured base URL — no domains hardcoded.
+ */
+const { Command } = require('commander');
+const prompts = require('prompts');
+const chalk = require('chalk');
+const { load, save, getWebUrl, CONFIG_FILE } = require('../config');
+const client = require('../client');
+const { success, error, info, warn, spinner } = require('../output');
+const { sendcraftGradient } = require('../banner');
+
+// ─── helpers ──────────────────────────────────────────────────────────────────
+
+/** Open a URL in the system's default browser (cross-platform). */
+function openBrowser(url) {
+  const { execSync } = require('child_process');
+  try {
+    const cmd =
+      process.platform === 'darwin' ? `open "${url}"` :
+      process.platform === 'win32'  ? `start "" "${url}"` :
+      `xdg-open "${url}"`;
+    execSync(cmd, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── browser flow ─────────────────────────────────────────────────────────────
+
+async function browserFlow() {
+  const webUrl = getWebUrl();
+  const settingsUrl = `${webUrl}/dashboard/settings`;
+
+  console.log('\n' + sendcraftGradient('  ✦ Browser Login\n'));
+  info(`Opening dashboard: ${chalk.cyan(settingsUrl)}`);
+  console.log(chalk.dim('  1. Open the API Keys tab'));
+  console.log(chalk.dim('  2. Create or copy an existing key'));
+  console.log(chalk.dim('  3. Paste it below\n'));
+
+  const opened = openBrowser(settingsUrl);
+  if (!opened) {
+    warn('Could not open browser automatically.');
+    console.log(`  Open manually: ${chalk.cyan(settingsUrl)}\n`);
+  }
+
+  const { apiKey } = await prompts(
+    {
+      type: 'password',
+      name: 'apiKey',
+      message: 'Paste your API key here',
+      validate: (v) => (v && v.length > 10) ? true : 'Enter a valid API key',
+    },
+    { onCancel: () => { error('Cancelled.'); process.exit(0); } }
+  );
+
+  if (!apiKey) return;
+
+  // Quick verify the key works
+  const sp = spinner('Verifying key…').start();
+  try {
+    // Store temporarily to use the authenticated client
+    const cfg = load();
+    cfg.api_key = apiKey;
+    save(cfg);
+
+    await client.get('/auth/me');
+    sp.succeed(chalk.dim('Verified'));
+    success(`Logged in! Key stored at ${chalk.dim(CONFIG_FILE)}`);
+  } catch (e) {
+    // Restore old key if verification fails
+    const cfg = load();
+    if (cfg.api_key === apiKey) delete cfg.api_key;
+    save(cfg);
+    sp.fail(chalk.red('Invalid key'));
+    error(e.message);
+  }
+}
+
+// ─── email+password flow ───────────────────────────────────────────────────────
+
+async function apiFlow() {
+  console.log('\n' + sendcraftGradient('  ✦ Sign In\n'));
+
+  const answers = await prompts(
+    [
+      {
+        type: 'text',
+        name: 'email',
+        message: 'Email address',
+        validate: (v) => v && v.includes('@') ? true : 'Enter a valid email',
+      },
+      {
+        type: 'password',
+        name: 'password',
+        message: 'Password',
+        validate: (v) => v && v.length >= 4 ? true : 'Enter your password',
+      },
+    ],
+    { onCancel: () => { error('Cancelled.'); process.exit(0); } }
+  );
+
+  if (!answers.email || !answers.password) return;
+
+  const sp = spinner('Signing in…').start();
+  let token, userName;
+  try {
+    const result = await client.postNoAuth('/auth/login', {
+      email: answers.email,
+      password: answers.password,
+    });
+    token = result.token;
+    userName = result.user?.name || answers.email;
+    sp.succeed(chalk.dim('Authenticated'));
+  } catch (e) {
+    sp.fail(chalk.red('Login failed'));
+    error(e.message === 'Invalid credentials'
+      ? 'Wrong email or password. Try again.'
+      : e.message);
+    return;
+  }
+
+  // Auto-create a CLI API key using the JWT
+  const sp2 = spinner('Creating CLI API key…').start();
+  try {
+    const result = await client.postWithToken('/user/keys', {
+      name: 'CLI',
+      permissions: 'full_access',
+    }, token);
+
+    const apiKey = result.key?.key;
+    if (!apiKey) throw new Error('No key returned from server');
+
+    sp2.succeed(chalk.dim('API key created'));
+
+    const cfg = load();
+    cfg.api_key = apiKey;
+    save(cfg);
+
+    console.log('\n  ' + chalk.bold.green(`Welcome, ${userName}!`));
+    success(`Logged in! Key stored at ${chalk.dim(CONFIG_FILE)}`);
+    console.log(
+      '\n  ' + chalk.dim('Tip: run ') + chalk.cyan('sendcraft config show') +
+      chalk.dim(' to confirm your setup.\n')
+    );
+  } catch (e) {
+    sp2.fail(chalk.red('Could not create API key'));
+    error(e.message);
+    info(`You can create a key manually at ${chalk.cyan(getWebUrl() + '/dashboard/settings')}`);
+  }
+}
+
+// ─── command ──────────────────────────────────────────────────────────────────
+
+const cmd = new Command('login')
+  .description('Log in to SendCraft and save your API key')
+  .option('--browser', 'Open dashboard in browser to copy an API key')
+  .option('--api',     'Log in with email and password via the API')
+  .action(async (opts) => {
+    if (opts.browser) return browserFlow();
+    if (opts.api)     return apiFlow();
+    return runInteractive();
+  });
+
+/** Exported so the interactive TUI can call it directly */
+async function runInteractive() {
+  console.log('\n' + sendcraftGradient('  ✦ SendCraft Login\n'));
+
+  const { method } = await prompts(
+    {
+      type: 'select',
+      name: 'method',
+      message: 'How would you like to log in?',
+      choices: [
+        {
+          title: '🌐  ' + chalk.bold('Browser') +
+                 chalk.dim(' — open dashboard, copy your API key'),
+          value: 'browser',
+        },
+        {
+          title: '🔐  ' + chalk.bold('Email & Password') +
+                 chalk.dim(' — sign in and auto-generate a CLI key'),
+          value: 'api',
+        },
+        {
+          title: chalk.dim('✕   Back'),
+          value: 'cancel',
+        },
+      ],
+    },
+    { onCancel: () => null }
+  );
+
+  if (!method || method === 'cancel') return;
+  if (method === 'browser') return browserFlow();
+  if (method === 'api')     return apiFlow();
+}
+
+cmd.runInteractive = runInteractive;
+module.exports = cmd;

package/lib/config.js

@@ -30,4 +30,24 @@ function getBaseUrl() {
   return process.env.SENDCRAFT_BASE_URL || load().base_url || 'https://api.sendcraft.online/api';
 }
 
-module.exports = { load, save, getApiKey, getBaseUrl, CONFIG_FILE };
+/**
+ * Derives the web dashboard URL from the API base URL.
+ * e.g. "https://api.sendcraft.online/api" → "https://sendcraft.online"
+ *      "http://localhost:3000/api"         → "http://localhost:3000"
+ *      "https://myinstance.com/api"        → "https://myinstance.com"
+ */
+function getWebUrl() {
+  const stored = load().web_url;
+  if (stored) return stored;
+  try {
+    const { URL } = require('url');
+    const parsed = new URL(getBaseUrl());
+    // Strip leading "api." subdomain if present
+    const host = parsed.hostname.replace(/^api\./, '');
+    return `${parsed.protocol}//${host}`;
+  } catch {
+    return 'https://sendcraft.online';
+  }
+}
+
+module.exports = { load, save, getApiKey, getBaseUrl, getWebUrl, CONFIG_FILE };

package/lib/interactive.js

@@ -23,6 +23,7 @@ const MAIN_MENU = [
   { title: '🔑  ' + chalk.bold('API Keys'),           value: 'keys' },
   { title: '🔥  ' + chalk.bold('SMTP Warmup'),        value: 'warmup' },
   { title: '🤖  ' + chalk.bold('MCP Setup'),          value: 'mcp' },
+  { title: '🔐  ' + chalk.bold('Login'),              value: 'login' },
   { title: '⚙️   ' + chalk.bold('Config'),            value: 'config' },
   { title: chalk.dim('✕   Exit'),                     value: 'exit' },
 ];
@@ -369,10 +370,10 @@ module.exports = async function interactive() {
     console.log(chalk.yellow('  ⚠  No API key configured yet.\n'));
     const { setup } = await prompts({
       type: 'confirm', name: 'setup',
-      message: 'Set up your API key now?',
+      message: 'Log in to SendCraft now?',
       initial: true,
     });
-    if (setup) await screenConfig();
+    if (setup) await require('./commands/login').runInteractive();
   }
 
   while (true) {
@@ -400,6 +401,7 @@ module.exports = async function interactive() {
       if (choice === 'keys')        await screenKeys();
       if (choice === 'warmup')      await screenWarmup();
       if (choice === 'mcp')         await screenMcp();
+      if (choice === 'login')       await require('./commands/login').runInteractive();
       if (choice === 'config')      await screenConfig();
     } catch (e) {
       error('Unexpected error: ' + e.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sendcraft-cli",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Official SendCraft CLI — send emails, manage campaigns, and more from your terminal",
   "bin": {
     "sendcraft": "./bin/sendcraft.js"