@startanaicompany/cli 1.4.15 → 1.4.17

package/CLAUDE.md

@@ -275,6 +275,71 @@ saac create web -s web -r git@git... -t abc123 \
 - Saves project config to `.saac/config.json` after successful creation
 - Displays next steps and useful commands
 
+**Deployment Behavior (NEW):**
+
+The `create` command now **waits for the initial deployment to complete** (up to 5 minutes) before returning.
+
+**Response Time:**
+- Typical: 30-120 seconds
+- Maximum: 5 minutes (timeout)
+
+**Success Response:**
+```json
+{
+  "success": true,
+  "coolify_app_uuid": "...",
+  "app_name": "my-app",
+  "domain": "https://myapp.startanaicompany.com",
+  "deployment_status": "finished",
+  "deployment_uuid": "...",
+  "git_branch": "master"
+}
+```
+
+**Failure Response (HTTP 200 with success: false):**
+```json
+{
+  "success": false,
+  "coolify_app_uuid": "...",
+  "app_name": "my-app",
+  "deployment_status": "failed",
+  "message": "Port 8080 is already in use. Remove host port bindings...",
+  "errors": [
+    {
+      "type": "PORT_CONFLICT",
+      "message": "Port 8080 is already in use...",
+      "detail": "Bind for 0.0.0.0:8080 failed..."
+    }
+  ],
+  "relevant_logs": [...],
+  "last_logs": [...]
+}
+```
+
+**Error Types:**
+- `PORT_CONFLICT` - Host port binding conflict in docker-compose.yml
+- `BUILD_FAILED` - Build process returned non-zero exit code
+- `TIMEOUT` - Deployment didn't complete in 5 minutes
+- `UNKNOWN` - Generic deployment failure
+
+**Important Notes:**
+1. **Application is created even if deployment fails** - the UUID is saved to `.saac/config.json`
+2. Failed deployments return HTTP 200 (not 4xx) with `success: false`
+3. CLI must check the `success` field, not just HTTP status code
+4. Detailed error information is displayed with actionable advice
+5. User can fix the issue and run `saac deploy` to retry
+
+**Error Display:**
+The CLI displays comprehensive error information:
+- Error summary message
+- Structured error details with types
+- Relevant error logs (filtered)
+- Last log lines for context
+- Actionable advice based on error type:
+  - `PORT_CONFLICT`: Remove host port bindings from docker-compose.yml
+  - `BUILD_FAILED`: Check Dockerfile, run `docker build .` locally
+  - `TIMEOUT`: Check `saac status` and `saac logs`, may still be running
+
 ### Update Command Implementation
 
 The `update` command allows modifying application configuration after deployment using `PATCH /api/v1/applications/:uuid`.
@@ -373,7 +438,7 @@ saac git disconnect git.startanaicompany.com
 
 ### Deploy Command Implementation
 
-The `deploy` command triggers deployment for the current application.
+The `deploy` command triggers deployment and **waits for completion** (up to 5 minutes).
 
 **Usage:**
 ```bash
@@ -385,16 +450,155 @@ saac deploy --force
 1. Validates authentication (session token not expired)
 2. Checks for project config (`.saac/config.json`)
 3. Makes POST request to `/api/v1/applications/:uuid/deploy`
-4. Displays deployment status and deployment ID
-5. Shows command to follow logs: `saac logs --follow`
+4. **Waits for deployment to complete** (up to 5 minutes)
+5. Displays deployment status with detailed error information on failure
 
-**Response Fields:**
-- `status` - Application status after deployment triggered
-- `domain` - Application domain (if available)
-- `deployment_id` - Unique ID for this deployment
+**Response Time:**
+- Typical: 30-120 seconds
+- Maximum: 5 minutes (timeout)
+
+**Success Response:**
+```json
+{
+  "success": true,
+  "status": "finished",
+  "deployment_uuid": "...",
+  "git_branch": "master",
+  "domain": "https://myapp.startanaicompany.com",
+  "traefik_status": "queued"
+}
+```
+
+**Failure Response:**
+```json
+{
+  "success": false,
+  "status": "failed",
+  "message": "Build failed with exit code 1",
+  "errors": [
+    {
+      "type": "BUILD_FAILED",
+      "message": "Build failed with exit code 1",
+      "detail": "npm ERR! code ELIFECYCLE..."
+    }
+  ],
+  "relevant_logs": [...],
+  "last_logs": [...]
+}
+```
+
+**Error Types:**
+- `PORT_CONFLICT` - Host port binding conflict
+- `BUILD_FAILED` - Build process failed
+- `TIMEOUT` - Deployment didn't complete in 5 minutes
+- `UNKNOWN` - Generic failure
+
+**Error Display:**
+The CLI displays:
+1. Error summary message
+2. Structured error details with types
+3. Relevant logs (filtered error logs)
+4. Last 5 log lines for context
+5. Actionable advice based on error type
+6. Suggestion to view full logs with `saac logs --follow`
 
 **Note:** The `--force` flag is defined in the CLI but not currently used by the API.
 
+### OTP-Based Login (NEW in 1.4.16)
+
+The login command now supports two authentication methods:
+
+**Method 1: Login with API Key (Fast Path)**
+```bash
+saac login -e user@example.com -k cw_abc123
+# → Immediate session token, no email verification needed
+```
+
+**Method 2: Login with OTP (Recovery Path)**
+```bash
+# Step 1: Request OTP
+saac login -e user@example.com
+# → Verification code sent to email (6 digits, 5-minute expiration)
+
+# Step 2: Verify OTP
+saac login -e user@example.com --otp 123456
+# → Session token created, user is now logged in
+```
+
+**Why This Feature?**
+
+Solves the **API key lockout problem**:
+- User loses API key
+- All sessions expire
+- Cannot login (no API key)
+- Cannot regenerate key (requires login)
+- **LOCKED OUT** ❌
+
+With OTP login:
+- User can always recover via email ✅
+- No support tickets needed ✅
+- Self-service account recovery ✅
+
+**Implementation Details:**
+
+The `login.js` command now has three modes:
+1. **API key login** - If `-k` flag provided (existing flow)
+2. **OTP request** - If no `-k` or `--otp` flag (new flow)
+3. **OTP verification** - If `--otp` flag provided (new flow)
+
+**Backend Requirements:**
+- `POST /api/v1/auth/login-otp` - Generate and send OTP
+- `POST /api/v1/auth/verify-otp` - Verify OTP and create session
+
+See `/data/sharedinfo/login-feature-update.md` for complete API specifications.
+
+### API Key Management (NEW in 1.4.16)
+
+Users can now regenerate their API keys if lost or compromised.
+
+**Commands:**
+
+```bash
+# Regenerate API key (requires authentication)
+saac keys regenerate
+# → Shows new API key (only once!)
+
+# Show API key info
+saac keys show
+# → Displays key prefix, created date, last used
+```
+
+**Recovery Flow:**
+
+```bash
+# 1. User loses API key but is not logged in
+saac login -e user@example.com
+# → OTP sent to email
+
+# 2. Verify OTP
+saac login -e user@example.com --otp 123456
+# → Logged in with session token
+
+# 3. Generate new API key
+saac keys regenerate
+# → New API key: cw_new_key_xyz...
+
+# 4. On next machine, use new API key
+saac login -e user@example.com -k cw_new_key_xyz...
+```
+
+**Security Notes:**
+- Regenerating API key invalidates the old key immediately
+- Existing session tokens remain valid (no disruption)
+- Email notification sent when key is regenerated
+- Full API key shown only once (must be saved)
+
+**Backend Requirements:**
+- `POST /api/v1/users/regenerate-key` - Generate new API key
+- `GET /api/v1/users/api-key` - Get API key info (optional)
+
+See `/data/sharedinfo/login-feature-update.md` for complete specifications.
+
 ### Init Command Implementation
 
 The `init` command links an existing SAAC application to the current directory.
@@ -493,19 +697,26 @@ The wrapper API expects Git repositories to be hosted on the StartAnAiCompany Gi
 - During registration, Gitea username can be auto-detected or manually provided
 - Applications reference repositories in the format: `git@git.startanaicompany.com:user/repo.git`
 
-## Current Status - Version 1.4.15
+## Current Status - Version 1.4.17
 
 ### Completed Features
 
 **Authentication & Sessions:**
 - ✅ `saac register` - Register with email only (git_username auto-detected from email)
-- ✅ `saac login` - Login with email + API key, receives 1-year session token
+- ✅ `saac login` - Two methods: API key (fast) or OTP (recovery)
+  - `saac login -e email -k api-key` - Login with API key
+  - `saac login -e email` - Request OTP via email
+  - `saac login -e email --otp code` - Verify OTP and login
 - ✅ `saac verify` - Email verification, shows FULL API key for user to save
 - ✅ `saac logout` - Logout from current device
 - ✅ `saac logout-all` - Revoke all sessions
 - ✅ `saac sessions` - List all active sessions
 - ✅ `saac whoami` - Show current user info
 
+**API Key Management (NEW in 1.4.16):**
+- ✅ `saac keys regenerate` - Generate new API key (invalidates old one)
+- ✅ `saac keys show` - Show API key information (prefix, created, last used)
+
 **Git OAuth (NEW in 1.4.0):**
 - ✅ `saac git connect [host]` - OAuth flow for Git authentication
 - ✅ `saac git list` - List connected Git accounts
@@ -706,4 +917,4 @@ Before publishing to npm:
 - `dotenv` - Environment variables
 - `open` - Open browser for OAuth (v8.4.2 for compatibility with chalk v4)
 
-**Version:** 1.4.15 (current)
+**Version:** 1.4.17 (current)

package/bin/saac.js

@@ -16,6 +16,7 @@ const verify = require('../src/commands/verify');
 const logout = require('../src/commands/logout');
 const logoutAll = require('../src/commands/logoutAll');
 const sessions = require('../src/commands/sessions');
+const keys = require('../src/commands/keys');
 const git = require('../src/commands/git');
 const init = require('../src/commands/init');
 const create = require('../src/commands/create');
@@ -56,7 +57,8 @@ program
   .command('login')
   .description('Login with existing account')
   .option('-e, --email <email>', 'Email address')
-  .option('-k, --api-key <key>', 'API key')
+  .option('-k, --api-key <key>', 'API key (for fast login)')
+  .option('--otp <code>', 'One-time password from email')
   .action(login);
 
 program
@@ -80,6 +82,22 @@ program
   .description('List all active sessions')
   .action(sessions);
 
+// API Key management
+const keysCommand = program
+  .command('keys')
+  .description('Manage API keys');
+
+keysCommand
+  .command('regenerate')
+  .description('Generate a new API key (invalidates old one)')
+  .action(keys.regenerate);
+
+keysCommand
+  .command('show')
+  .alias('info')
+  .description('Show API key information')
+  .action(keys.show);
+
 // Git OAuth commands
 const gitCommand = program
   .command('git')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startanaicompany/cli",
-  "version": "1.4.15",
+  "version": "1.4.17",
   "description": "Official CLI for StartAnAiCompany.com - Deploy AI recruitment sites with ease",
   "main": "src/index.js",
   "bin": {

package/src/commands/create.js

@@ -8,6 +8,7 @@ const logger = require('../lib/logger');
 const oauth = require('../lib/oauth');
 const inquirer = require('inquirer');
 const { execSync } = require('child_process');
+const errorDisplay = require('../lib/errorDisplay');
 
 async function create(name, options) {
   try {
@@ -281,14 +282,12 @@ async function create(name, options) {
 
     logger.newline();
 
-    const spin = logger.spinner('Creating application...').start();
+    const spin = logger.spinner('Creating application and deploying (this may take up to 5 minutes)...').start();
 
     try {
       const result = await api.createApplication(appData);
 
-      spin.succeed('Application created successfully!');
-
-      // Save project configuration
+      // Always save project configuration (even if deployment failed)
       saveProjectConfig({
         applicationUuid: result.coolify_app_uuid,
         applicationName: result.app_name,
@@ -297,13 +296,35 @@ async function create(name, options) {
         gitRepository: appData.git_repository,
       });
 
+      // Check if deployment failed
+      if (result.success === false) {
+        spin.fail('Deployment failed');
+
+        // Display detailed error information
+        errorDisplay.displayDeploymentError(result, logger);
+
+        // Show recovery instructions
+        errorDisplay.displayCreateRecoveryInstructions(result, logger);
+
+        process.exit(1);
+      }
+
+      // SUCCESS: Application created and deployed
+      spin.succeed('Application created and deployed successfully!');
+
       logger.newline();
-      logger.success('Application created!');
+      logger.success('Your application is live!');
       logger.newline();
       logger.field('Name', result.app_name);
       logger.field('Domain', result.domain);
       logger.field('UUID', result.coolify_app_uuid);
-      logger.field('Status', result.deployment_status);
+      logger.field('Status', result.deployment_status || 'finished');
+      if (result.git_branch) {
+        logger.field('Branch', result.git_branch);
+      }
+      if (result.deployment_uuid) {
+        logger.field('Deployment ID', result.deployment_uuid);
+      }
       logger.newline();
 
       // Show next steps

package/src/commands/deploy.js

@@ -5,6 +5,7 @@
 const api = require('../lib/api');
 const { getProjectConfig, isAuthenticated } = require('../lib/config');
 const logger = require('../lib/logger');
+const errorDisplay = require('../lib/errorDisplay');
 
 async function deploy(options) {
   try {
@@ -25,30 +26,62 @@ async function deploy(options) {
     const { applicationUuid, applicationName } = projectConfig;
 
     logger.section(`Deploying ${applicationName}`);
+    logger.newline();
 
-    const spin = logger.spinner('Triggering deployment...').start();
+    const spin = logger.spinner('Deploying application (waiting for completion, up to 5 minutes)...').start();
 
     try {
       const result = await api.deployApplication(applicationUuid);
 
-      spin.succeed('Deployment triggered!');
+      // Check if deployment failed
+      if (result.success === false) {
+        spin.fail('Deployment failed');
+
+        // Display detailed error information
+        errorDisplay.displayDeploymentError(result, logger);
+
+        // Handle timeout specifically
+        if (result.status === 'timeout') {
+          errorDisplay.displayTimeoutInstructions(logger);
+        }
+
+        process.exit(1);
+      }
+
+      // SUCCESS: Deployment completed
+      spin.succeed('Deployment completed successfully!');
 
       logger.newline();
-      logger.success('Deployment started successfully');
+      logger.success('Your application has been deployed!');
       logger.newline();
       logger.field('Application', applicationName);
       logger.field('Status', result.status);
+      if (result.git_branch) {
+        logger.field('Branch', result.git_branch);
+      }
       if (result.domain) {
         logger.field('Domain', result.domain);
       }
-      logger.field('Deployment ID', result.deployment_id);
+      if (result.deployment_uuid || result.deployment_id) {
+        logger.field('Deployment ID', result.deployment_uuid || result.deployment_id);
+      }
       logger.newline();
-      logger.info(
-        `View logs with: ${logger.chalk.yellow('saac logs --follow')}`
-      );
+
+      // Show Traefik status if present
+      if (result.traefik_status === 'queued') {
+        logger.info('Routing configuration is being applied (may take a few seconds)');
+        logger.newline();
+      } else if (result.traefik_status === 'failed') {
+        logger.warn('Routing configuration failed - application may not be accessible');
+        logger.newline();
+      }
+
+      logger.info('Useful commands:');
+      logger.log(`  saac logs --follow       View live deployment logs`);
+      logger.log(`  saac status              Check application status`);
 
     } catch (error) {
-      spin.fail('Deployment failed');
+      spin.fail('Deployment request failed');
       throw error;
     }
   } catch (error) {

package/src/commands/keys.js

@@ -0,0 +1,143 @@
+/**
+ * API Key management commands
+ */
+
+const api = require('../lib/api');
+const { getUser, isAuthenticated } = require('../lib/config');
+const logger = require('../lib/logger');
+const inquirer = require('inquirer');
+
+/**
+ * Regenerate API key
+ */
+async function regenerate() {
+  try {
+    // Must be authenticated (via session token)
+    if (!isAuthenticated()) {
+      logger.error('Not logged in');
+      logger.newline();
+      logger.info('You must be logged in to regenerate your API key');
+      logger.newline();
+      logger.info('Login using email verification:');
+      logger.log('  saac login -e <email>           # Request OTP');
+      logger.log('  saac login -e <email> --otp <code>  # Verify OTP');
+      process.exit(1);
+    }
+
+    const user = getUser();
+
+    logger.section('Regenerate API Key');
+    logger.newline();
+
+    logger.warn('This will generate a new API key and invalidate your current one.');
+    logger.warn('Your active session tokens will continue to work.');
+    logger.newline();
+
+    // Confirmation prompt
+    const { confirm } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'confirm',
+        message: 'Are you sure you want to regenerate your API key?',
+        default: false,
+      },
+    ]);
+
+    if (!confirm) {
+      logger.info('Cancelled');
+      return;
+    }
+
+    const spin = logger.spinner('Generating new API key...').start();
+
+    try {
+      const result = await api.regenerateApiKey();
+
+      spin.succeed('New API key generated!');
+
+      logger.newline();
+      logger.success('Your new API key:');
+      logger.newline();
+
+      // Show FULL API key (it's only shown once)
+      logger.field('API Key', result.api_key);
+
+      logger.newline();
+      logger.warn('Save this key securely. It will not be shown again.');
+      logger.newline();
+
+      logger.info('Your existing sessions remain active.');
+      logger.info('Use this new key for future logins or CI/CD.');
+      logger.newline();
+
+      logger.info('To login with the new key:');
+      logger.log(`  saac login -e ${user.email} -k ${result.api_key}`);
+
+    } catch (error) {
+      spin.fail('Failed to regenerate API key');
+      throw error;
+    }
+  } catch (error) {
+    logger.error(error.response?.data?.message || error.message);
+    process.exit(1);
+  }
+}
+
+/**
+ * Show API key info (without revealing full key)
+ */
+async function show() {
+  try {
+    if (!isAuthenticated()) {
+      logger.error('Not logged in');
+      logger.newline();
+      logger.info('Login first:');
+      logger.log('  saac login -e <email>');
+      process.exit(1);
+    }
+
+    logger.section('API Key Information');
+    logger.newline();
+
+    const spin = logger.spinner('Fetching API key info...').start();
+
+    try {
+      const result = await api.getApiKeyInfo();
+
+      spin.succeed('API key info retrieved');
+
+      logger.newline();
+      logger.field('Key Prefix', result.key_prefix); // e.g., "cw_RJ1gH8..."
+      logger.field('Created', new Date(result.created_at).toLocaleDateString());
+      logger.field('Last Used', result.last_used_at
+        ? new Date(result.last_used_at).toLocaleString()
+        : 'Never');
+
+      logger.newline();
+      logger.info('Commands:');
+      logger.log('  saac keys regenerate    Generate new API key');
+      logger.log('  saac sessions           View active sessions');
+
+    } catch (error) {
+      spin.fail('Failed to fetch API key info');
+
+      // If endpoint doesn't exist yet, show helpful message
+      if (error.response?.status === 404) {
+        logger.newline();
+        logger.warn('API key info endpoint not available yet');
+        logger.info('You can still regenerate your key with:');
+        logger.log('  saac keys regenerate');
+      } else {
+        throw error;
+      }
+    }
+  } catch (error) {
+    logger.error(error.response?.data?.message || error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  regenerate,
+  show,
+};

package/src/commands/login.js

@@ -1,5 +1,7 @@
 /**
- * Login command
+ * Login command - Two methods:
+ * 1. With API key (fast): saac login -e email -k api_key
+ * 2. With OTP (recovery): saac login -e email, then saac login -e email --otp code
  */
 
 const inquirer = require('inquirer');
@@ -10,21 +12,23 @@ const logger = require('../lib/logger');
 
 async function login(options) {
   try {
-    // Require both email and API key flags (no interactive prompts)
-    if (!options.email || !options.apiKey) {
-      logger.error('Email and API key are required');
+    // Require email flag
+    if (!options.email) {
+      logger.error('Email is required');
       logger.newline();
       logger.info('Usage:');
-      logger.log('  saac login -e <email> -k <api-key>');
-      logger.log('  saac login --email <email> --api-key <api-key>');
+      logger.log('  saac login -e <email> -k <api-key>           # Login with API key');
+      logger.log('  saac login -e <email>                        # Request OTP via email');
+      logger.log('  saac login -e <email> --otp <code>           # Verify OTP and login');
       logger.newline();
-      logger.info('Example:');
-      logger.log('  saac login -e user@example.com -k cw_your_api_key');
+      logger.info('Examples:');
+      logger.log('  saac login -e user@example.com -k cw_abc123  # Fast login');
+      logger.log('  saac login -e user@example.com               # Send OTP to email');
+      logger.log('  saac login -e user@example.com --otp 123456  # Verify OTP');
       process.exit(1);
     }
 
     const email = options.email;
-    const apiKey = options.apiKey;
 
     // Validate email format
     if (!validator.isEmail(email)) {
@@ -33,46 +37,143 @@ async function login(options) {
     }
 
     logger.section('Login to StartAnAiCompany');
+    logger.newline();
 
-    // Login and get session token
-    const spin = logger.spinner('Logging in...').start();
+    // CASE 1: Login with API key (fast path)
+    if (options.apiKey) {
+      return await loginWithApiKey(email, options.apiKey);
+    }
 
-    try {
-      // Call /auth/login endpoint to get session token
-      const result = await api.login(email, apiKey);
+    // CASE 2: Verify OTP (second step)
+    if (options.otp) {
+      return await verifyOtpAndLogin(email, options.otp);
+    }
 
-      spin.succeed('Login successful!');
+    // CASE 3: Request OTP (first step)
+    return await requestOtp(email);
 
-      // Save session token and expiration
-      saveUser({
-        email: result.user.email || email,
-        userId: result.user.id,
-        sessionToken: result.session_token,
-        expiresAt: result.expires_at,
-        verified: result.user.verified,
-      });
+  } catch (error) {
+    logger.error(error.response?.data?.message || error.message);
+    process.exit(1);
+  }
+}
 
-      logger.newline();
-      logger.success('You are now logged in!');
-      logger.newline();
-      logger.field('Email', result.user.email || email);
-      logger.field('Verified', result.user.verified ? 'Yes' : 'No');
-
-      // Show expiration date
-      if (result.expires_at) {
-        const expirationDate = new Date(result.expires_at);
-        logger.field('Session expires', expirationDate.toLocaleDateString());
-      }
-
-    } catch (error) {
-      spin.fail('Login failed');
-      throw error;
+/**
+ * Login with API key (existing flow)
+ */
+async function loginWithApiKey(email, apiKey) {
+  const spin = logger.spinner('Logging in with API key...').start();
+
+  try {
+    const result = await api.login(email, apiKey);
+
+    spin.succeed('Login successful!');
+
+    // Save session token
+    saveUser({
+      email: result.user.email || email,
+      userId: result.user.id,
+      sessionToken: result.session_token,
+      expiresAt: result.expires_at,
+      verified: result.user.verified,
+    });
+
+    logger.newline();
+    logger.success('You are now logged in!');
+    logger.newline();
+    logger.field('Email', result.user.email || email);
+    logger.field('Verified', result.user.verified ? 'Yes' : 'No');
+
+    if (result.expires_at) {
+      const expirationDate = new Date(result.expires_at);
+      logger.field('Session expires', expirationDate.toLocaleDateString());
     }
+
   } catch (error) {
-    logger.error(
-      error.response?.data?.message || 'Invalid credentials'
-    );
-    process.exit(1);
+    spin.fail('Login failed');
+    throw error;
+  }
+}
+
+/**
+ * Request OTP via email (new flow - step 1)
+ */
+async function requestOtp(email) {
+  const spin = logger.spinner('Sending verification code to email...').start();
+
+  try {
+    const result = await api.requestLoginOtp(email);
+
+    spin.succeed('Verification code sent!');
+
+    logger.newline();
+    logger.success(`A verification code has been sent to ${logger.chalk.cyan(email)}`);
+    logger.newline();
+    logger.info('Check your email and run:');
+    logger.log(`  ${logger.chalk.yellow(`saac login -e ${email} --otp <code>`)}`);
+    logger.newline();
+    logger.warn('Note: Check MailHog at https://mailhog.goryan.io for the verification code');
+    logger.newline();
+
+    if (result.otp_expires_at) {
+      const expiresAt = new Date(result.otp_expires_at);
+      const now = new Date();
+      const minutesLeft = Math.ceil((expiresAt - now) / 60000);
+      logger.info(`Code expires in ${minutesLeft} minutes`);
+    }
+
+  } catch (error) {
+    spin.fail('Failed to send verification code');
+    throw error;
+  }
+}
+
+/**
+ * Verify OTP and complete login (new flow - step 2)
+ */
+async function verifyOtpAndLogin(email, otpCode) {
+  const spin = logger.spinner('Verifying code...').start();
+
+  try {
+    const result = await api.verifyLoginOtp(email, otpCode);
+
+    spin.succeed('Verification successful!');
+
+    // Save session token
+    saveUser({
+      email: result.user.email || email,
+      userId: result.user.id,
+      sessionToken: result.session_token,
+      expiresAt: result.expires_at,
+      verified: result.user.verified,
+    });
+
+    logger.newline();
+    logger.success('You are now logged in!');
+    logger.newline();
+    logger.field('Email', result.user.email || email);
+    logger.field('Verified', result.user.verified ? 'Yes' : 'No');
+
+    if (result.expires_at) {
+      const expirationDate = new Date(result.expires_at);
+      logger.field('Session expires', expirationDate.toLocaleDateString());
+    }
+
+    logger.newline();
+    logger.info('💡 Tip: Generate an API key for faster future logins:');
+    logger.log('  saac keys regenerate');
+
+  } catch (error) {
+    spin.fail('Verification failed');
+
+    if (error.response?.status === 401) {
+      logger.newline();
+      logger.error('Invalid or expired verification code');
+      logger.info('Request a new code:');
+      logger.log(`  saac login -e ${email}`);
+    }
+
+    throw error;
   }
 }
 

package/src/lib/api.js

@@ -9,8 +9,9 @@ const pkg = require('../../package.json');
 
 /**
  * Create axios instance with base configuration
+ * @param {number} timeout - Timeout in milliseconds (default: 30000)
  */
-function createClient() {
+function createClient(timeout = 30000) {
   const user = getUser();
   const envApiKey = process.env.SAAC_API_KEY; // For CI/CD
 
@@ -33,7 +34,7 @@ function createClient() {
 
   return axios.create({
     baseURL: getApiUrl(),
-    timeout: 30000,
+    timeout: timeout,
     headers,
   });
 }
@@ -88,9 +89,11 @@ async function getUserInfo() {
 
 /**
  * Create a new application
+ * Note: This waits for deployment to complete (up to 5 minutes)
  */
 async function createApplication(appData) {
-  const client = createClient();
+  // Use 5-minute timeout for deployment waiting
+  const client = createClient(300000); // 5 minutes
   const response = await client.post('/applications', appData);
   return response.data;
 }
@@ -115,9 +118,11 @@ async function getApplication(uuid) {
 
 /**
  * Deploy application
+ * Note: This waits for deployment to complete (up to 5 minutes)
  */
 async function deployApplication(uuid) {
-  const client = createClient();
+  // Use 5-minute timeout for deployment waiting
+  const client = createClient(300000); // 5 minutes
   const response = await client.post(`/applications/${uuid}/deploy`);
   return response.data;
 }
@@ -181,6 +186,61 @@ async function healthCheck() {
   return response.data;
 }
 
+/**
+ * Request login OTP (no API key required)
+ */
+async function requestLoginOtp(email) {
+  const client = axios.create({
+    baseURL: getApiUrl(),
+    timeout: 30000,
+    headers: {
+      'Content-Type': 'application/json',
+      'User-Agent': `saac-cli/${pkg.version} (${os.platform()}; ${os.arch()})`,
+    },
+  });
+
+  const response = await client.post('/auth/login-otp', { email });
+  return response.data;
+}
+
+/**
+ * Verify login OTP and get session token
+ */
+async function verifyLoginOtp(email, otpCode) {
+  const client = axios.create({
+    baseURL: getApiUrl(),
+    timeout: 30000,
+    headers: {
+      'Content-Type': 'application/json',
+      'User-Agent': `saac-cli/${pkg.version} (${os.platform()}; ${os.arch()})`,
+    },
+  });
+
+  const response = await client.post('/auth/verify-otp', {
+    email,
+    otp_code: otpCode,
+  });
+  return response.data;
+}
+
+/**
+ * Regenerate API key (requires authentication)
+ */
+async function regenerateApiKey() {
+  const client = createClient();
+  const response = await client.post('/users/regenerate-key');
+  return response.data;
+}
+
+/**
+ * Get API key info (prefix, created date, last used)
+ */
+async function getApiKeyInfo() {
+  const client = createClient();
+  const response = await client.get('/users/api-key');
+  return response.data;
+}
+
 module.exports = {
   createClient,
   login,
@@ -197,4 +257,8 @@ module.exports = {
   updateDomain,
   deleteApplication,
   healthCheck,
+  requestLoginOtp,
+  verifyLoginOtp,
+  regenerateApiKey,
+  getApiKeyInfo,
 };

package/src/lib/errorDisplay.js

@@ -0,0 +1,170 @@
+/**
+ * Error Display Utilities
+ * Formats and displays deployment errors with actionable advice
+ */
+
+const chalk = require('chalk');
+
+/**
+ * Get actionable advice for specific error types
+ */
+function getErrorAdvice(errorType) {
+  const advice = {
+    PORT_CONFLICT: [
+      'Fix: Remove host port bindings from your docker-compose.yml',
+      '     Change "8080:8080" to just "8080"',
+      '     Traefik will handle external routing automatically',
+    ],
+    BUILD_FAILED: [
+      'Fix: Check your Dockerfile and build configuration',
+      '     Run "docker build ." locally to debug',
+      '     Verify all dependencies are properly specified',
+    ],
+    TIMEOUT: [
+      'Note: Deployment may still be running in the background',
+      '      Check status with: saac status',
+      '      View logs with: saac logs --follow',
+    ],
+    UNKNOWN: [
+      'Tip: Check the deployment logs for more details',
+      '     Run: saac logs --follow',
+    ],
+    PARSE_ERROR: [
+      'Note: Could not parse deployment logs',
+      '      Contact support if this persists',
+    ],
+  };
+
+  return advice[errorType] || advice.UNKNOWN;
+}
+
+/**
+ * Format log lines for display
+ */
+function formatLogs(logs, maxLines = 10) {
+  if (!logs || logs.length === 0) {
+    return [];
+  }
+
+  // If logs is an array of objects with 'output' field
+  if (logs[0] && typeof logs[0] === 'object' && logs[0].output) {
+    return logs.slice(-maxLines).map(log => log.output);
+  }
+
+  // If logs is an array of strings
+  return logs.slice(-maxLines);
+}
+
+/**
+ * Display detailed deployment error information
+ */
+function displayDeploymentError(result, logger) {
+  logger.newline();
+  logger.error(`Deployment Error: ${result.message || 'Deployment failed'}`);
+  logger.newline();
+
+  // Display deployment info
+  if (result.deployment_status || result.status) {
+    logger.field('Status', result.deployment_status || result.status);
+  }
+  if (result.git_branch) {
+    logger.field('Branch', result.git_branch);
+  }
+  if (result.deployment_uuid) {
+    logger.field('Deployment ID', result.deployment_uuid);
+  }
+
+  logger.newline();
+
+  // Display structured errors
+  if (result.errors && result.errors.length > 0) {
+    logger.info('Error Details:');
+    result.errors.forEach(err => {
+      logger.log(`  ${chalk.yellow(`[${err.type}]`)} ${err.message}`);
+      if (err.detail) {
+        const detailLines = err.detail.split('\n').slice(0, 3); // First 3 lines
+        detailLines.forEach(line => {
+          logger.log(`    ${chalk.gray(line)}`);
+        });
+      }
+    });
+    logger.newline();
+
+    // Display actionable advice for the first error
+    const firstError = result.errors[0];
+    if (firstError && firstError.type) {
+      const advice = getErrorAdvice(firstError.type);
+      if (advice && advice.length > 0) {
+        logger.info('Suggested Fix:');
+        advice.forEach(line => {
+          logger.log(`  ${chalk.cyan(line)}`);
+        });
+        logger.newline();
+      }
+    }
+  }
+
+  // Display relevant logs (filtered error logs)
+  if (result.relevant_logs && result.relevant_logs.length > 0) {
+    logger.info('Relevant Logs:');
+    const logLines = formatLogs(result.relevant_logs, 5);
+    logLines.forEach(line => {
+      logger.log(`  ${chalk.gray(line)}`);
+    });
+    logger.newline();
+  }
+
+  // Display last logs (context)
+  if (result.last_logs && result.last_logs.length > 0) {
+    logger.info('Recent Log Output:');
+    const logLines = formatLogs(result.last_logs, 5);
+    logLines.forEach(line => {
+      logger.log(`  ${chalk.gray(line)}`);
+    });
+    logger.newline();
+  }
+
+  // Suggest viewing full logs
+  if (result.coolify_app_uuid || result.deployment_uuid) {
+    const uuid = result.coolify_app_uuid || result.deployment_uuid;
+    logger.info('View full logs:');
+    logger.log(`  ${chalk.yellow('saac logs --follow')}`);
+    logger.newline();
+  }
+}
+
+/**
+ * Display recovery instructions after failed create
+ */
+function displayCreateRecoveryInstructions(result, logger) {
+  if (result.coolify_app_uuid) {
+    logger.warn(`Application "${result.app_name}" was created but deployment failed.`);
+    logger.info('Fix the issue in your repository, then redeploy:');
+    logger.log(`  ${chalk.yellow('saac deploy')}`);
+    logger.newline();
+    logger.info('Or delete and recreate:');
+    logger.log(`  ${chalk.yellow(`saac delete ${result.coolify_app_uuid}`)}`);
+  }
+}
+
+/**
+ * Display timeout-specific instructions
+ */
+function displayTimeoutInstructions(logger) {
+  logger.warn('Deployment timed out after 5 minutes');
+  logger.newline();
+  logger.info('The deployment may still be running in the background.');
+  logger.info('Check the status:');
+  logger.log(`  ${chalk.yellow('saac status')}`);
+  logger.newline();
+  logger.info('Or view live logs:');
+  logger.log(`  ${chalk.yellow('saac logs --follow')}`);
+}
+
+module.exports = {
+  getErrorAdvice,
+  formatLogs,
+  displayDeploymentError,
+  displayCreateRecoveryInstructions,
+  displayTimeoutInstructions,
+};