@startanaicompany/cli 1.4.16 → 1.4.18

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,13 +450,57 @@ 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.
 
@@ -542,16 +651,361 @@ Uses the same status display logic as the status command (see "Application Statu
 - Domains fallback to `{subdomain}.startanaicompany.com` if not set
 - Branch defaults to 'master' if not specified
 
-### Incomplete Commands
+### Deployments Command Implementation
+
+The `deployments` command displays deployment history for the current application in a formatted table.
+
+**Usage:**
+```bash
+saac deployments
+saac deploys  # Alias
+
+# With pagination
+saac deployments --limit 10
+saac deployments --limit 20 --offset 20
+```
+
+**How It Works:**
+1. Validates authentication (session token not expired)
+2. Checks for project config (`.saac/config.json`)
+3. Fetches deployment history from `/api/v1/applications/:uuid/deployments`
+4. Displays table with columns: UUID, Status, Branch, Commit, Duration, Trigger, Date
+5. Shows pagination info if more deployments available
+
+**Options:**
+- `-l, --limit <number>` - Number of deployments to show (default: 20)
+- `-o, --offset <number>` - Offset for pagination (default: 0)
+
+**Status Display:**
+- ✅ `finished` - Displayed in green
+- ✗ `failed` - Displayed in red
+- ⏳ `running`, `queued` - Displayed in yellow
+- `unknown` - Displayed in gray
+
+**Table Formatting:**
+- UUID truncated to 26 characters for readability
+- Commit SHA truncated to 7 characters
+- Duration shown in seconds
+- Date formatted with `toLocaleString()`
+
+**Response Fields:**
+```json
+{
+  "deployments": [
+    {
+      "deployment_uuid": "...",
+      "status": "finished",
+      "git_branch": "master",
+      "git_commit": "abc1234",
+      "duration_seconds": 45,
+      "triggered_by": "api",
+      "started_at": "2024-01-20T12:00:00Z"
+    }
+  ],
+  "total": 100
+}
+```
+
+**Next Steps:**
+After viewing deployment history, use:
+- `saac logs --deployment` - View latest deployment logs
+- `saac logs --deployment <uuid>` - View specific deployment logs
+
+### Logs Command Implementation
+
+The `logs` command displays application logs with support for both deployment logs (build logs) and runtime logs (container logs).
+
+**Usage:**
+```bash
+# View latest deployment logs (build logs)
+saac logs --deployment
+saac logs -d
+
+# View specific deployment logs
+saac logs --deployment abc123-def456-...
+saac logs abc123-def456-... --deployment
+
+# View deployment logs in raw format
+saac logs --deployment --raw
+
+# View runtime logs (container logs)
+saac logs
+saac logs --tail 200
+saac logs --follow
+saac logs --since 1h
+```
+
+**Two Modes:**
+
+**1. Deployment Logs Mode (Build Logs)**
+- Enabled with `--deployment` flag
+- Shows logs from the build/deployment process
+- Includes build output, errors, and deployment status
+- Supports both parsed (colorized) and raw formats
+
+**Options:**
+- `--deployment [uuid]` - View deployment logs (omit UUID for latest)
+- `--raw` - Show raw log output (no parsing or colorization)
+- `--include-hidden` - Include hidden log lines
+
+**Display:**
+- Header with deployment UUID, status, commit, duration
+- Parsed logs with stderr highlighted in red
+- Error summary if deployment failed
+- Structured error information with types and details
+
+**2. Runtime Logs Mode (Container Logs)**
+- Default mode when no `--deployment` flag
+- Shows logs from the running container
+- Real-time application output
+
+**Options:**
+- `-t, --tail <lines>` - Number of lines to show (default: 100)
+- `-f, --follow` - Follow log output (not yet implemented)
+- `--since <time>` - Show logs since timestamp
+
+**Error Handling:**
+- 404 error → No deployments found, suggests `saac deploy`
+- 501 error → Runtime logs not implemented, suggests deployment logs
+
+**Response Fields (Deployment Logs):**
+```json
+{
+  "deployment_uuid": "...",
+  "status": "finished",
+  "commit": "abc1234",
+  "commit_message": "Fix bug",
+  "started_at": "2024-01-20T12:00:00Z",
+  "finished_at": "2024-01-20T12:02:00Z",
+  "duration_seconds": 120,
+  "log_count": 150,
+  "logs": [
+    {
+      "type": "stdout",
+      "output": "Installing dependencies..."
+    },
+    {
+      "type": "stderr",
+      "output": "npm WARN deprecated package@1.0.0"
+    }
+  ],
+  "raw_logs": "...",
+  "errors": [
+    {
+      "type": "BUILD_FAILED",
+      "message": "Build failed with exit code 1",
+      "detail": "npm ERR! code ELIFECYCLE"
+    }
+  ]
+}
+```
 
-Several commands still need implementation:
-- `src/commands/env.js` - Not implemented (stub only)
-- `src/commands/domain.js` - Not implemented (stub only)
-- `src/commands/logs.js` - Not implemented (stub only)
-- `src/commands/delete.js` - Not implemented (stub only)
-- `src/commands/whoami.js` - Not implemented (stub only)
+### Local Development Commands (NEW in 1.5.0)
 
-**Important:** The `env` and `domain` commands need to export OBJECTS with subcommand methods (e.g., `module.exports = { set, get, list }`), not simple functions. See `bin/saac.js:189-219` for how these are called.
+#### Run Command Implementation
+
+The `run` command allows executing local commands with remote environment variables from the deployed application.
+
+**Usage:**
+```bash
+saac run <command>                  # Run command with remote env vars
+saac run npm start                  # Start app with production env
+saac run --sync npm run build       # Force refresh env vars (skip cache)
+saac run -q npm test                # Quiet mode (suppress warnings)
+```
+
+**Implementation Details:**
+- Fetches env vars from `GET /applications/:uuid/env/export`
+- Uses 5-minute in-memory cache (TTL: 300 seconds)
+- Creates temp file at `/tmp/saac-env-{uuid}.sh` with 0600 permissions
+- Sources env file and executes command in subshell
+- Automatic cleanup on exit (SIGINT/SIGTERM handlers)
+- Rate limit handling (10 requests/minute per user)
+
+**Security Features:**
+- Temp files with 0600 permissions (owner read-write only)
+- Automatic cleanup on process exit
+- Warning message about exposed secrets
+- Cache reduces API calls (rate limit protection)
+
+**Error Handling:**
+- 429 Rate Limit: Shows retry time, mentions caching
+- 403 Forbidden: User doesn't own application
+- 404 Not Found: Application doesn't exist
+- Network failures: Graceful error messages
+
+**Location:** `src/commands/run.js`
+
+---
+
+#### Shell Command Implementation
+
+The `shell` command opens an interactive shell with remote environment variables loaded.
+
+**Usage:**
+```bash
+saac shell                         # Open shell (uses $SHELL or /bin/bash)
+saac shell --cmd zsh               # Use specific shell
+saac shell --sync                  # Force refresh env vars (skip cache)
+```
+
+**Implementation Details:**
+- Fetches env vars from `GET /applications/:uuid/env/export`
+- Uses 5-minute in-memory cache (same as `run`)
+- Creates temp file for env vars at `/tmp/saac-env-{uuid}.sh`
+- Special handling for bash and zsh (custom RC files)
+- Sources environment before shell starts
+- Automatic cleanup when shell exits
+
+**Shell-Specific Behavior:**
+- **bash:** Uses `--rcfile` with temporary RC that sources env + user's `.bashrc`
+- **zsh:** Uses `ZDOTDIR` with temporary `.zshrc` that sources env + user's `.zshrc`
+- **other:** Fallback to bash with source then exec
+
+**Security Features:**
+- Same as `run` command (0600 permissions, cleanup, warnings)
+- Sets environment variables: `SAAC_ENV_LOADED=1`, `SAAC_APP_NAME`, `SAAC_APP_UUID`
+
+**User Experience:**
+```bash
+$ saac shell
+✓ Environment variables retrieved
+
+🚀 Opening shell with 6 environment variables loaded
+
+  Application:  my-app
+  Shell:        bash
+  Variables:    6
+
+⚠️  Secrets are exposed on local machine
+Temporary file: /tmp/saac-env-abc123.sh (will be deleted on exit)
+
+Type "exit" or press Ctrl+D to close the shell
+────────────────────────────────────────────────────────────────
+
+bash-5.0$ echo $NODE_ENV
+production
+bash-5.0$ exit
+
+✓ Shell closed, environment variables cleared
+```
+
+**Location:** `src/commands/shell.js`
+
+---
+
+### Remote Execution Commands (NEW in 1.6.0)
+
+#### Exec Command Implementation
+
+The `exec` command allows executing commands directly in the deployed application's container.
+
+**Usage:**
+```bash
+saac exec "npm run db:migrate"                    # Run database migrations
+saac exec "npm run build" --timeout 120           # With custom timeout
+saac exec "python manage.py collectstatic" --workdir /app/backend
+saac exec --history                               # View execution history
+saac exec --history --limit 50                    # Show more history
+```
+
+**Implementation Details:**
+- Sends command to `POST /applications/:uuid/exec`
+- Backend validates command against allowlist
+- Python daemon executes via Docker API (no shell interpretation!)
+- Returns: execution_id, exit_code, stdout, stderr, duration
+- Command runs in container as detected user (not root)
+
+**Architecture:**
+```
+CLI → Backend API → Database (exec_requests table) → Python Daemon → Docker Container
+```
+
+**Security Features:**
+- ✅ **3-layer validation:** Backend allowlist + daemon validation + Docker array execution
+- ✅ **Command allowlist:** npm, node, python, bash, etc. (dangerous commands blocked)
+- ✅ **Dangerous pattern detection:** Blocks `rm -rf`, `| sh`, `$(...)`, etc.
+- ✅ **Rate limiting:** 30 requests per 5 minutes per user
+- ✅ **No shell interpretation:** Commands executed as arrays, not strings
+- ✅ **Non-root execution:** Commands run as app user, never privileged
+- ✅ **Audit logging:** All executions logged with user, command, exit code
+
+**Allowed Commands:**
+- Node.js: `npm`, `node`, `npx`, `yarn`, `pnpm`
+- Python: `python`, `python3`, `pip`, `poetry`
+- Ruby: `bundle`, `rake`, `rails`
+- Build tools: `make`, `cmake`, `go`, `cargo`
+- Shell: `sh`, `bash`, `echo`, `cat`, `ls`, `pwd`, `env`
+- Database: `psql`, `mysql`, `mongosh`
+
+**Error Handling:**
+- 400 Validation Error: Command not in allowlist or dangerous pattern detected
+- 408 Timeout: Command exceeded timeout limit (default: 30s, max: 300s)
+- 429 Rate Limit: Too many exec requests (30 per 5 minutes)
+- 503 Container Not Running: Application container is not active
+- 500 Execution Failed: Container error or daemon issue
+
+**Example Output:**
+```bash
+$ saac exec "echo 'Hello from container!'"
+
+Executing Command: myapp
+──────────────────────────
+
+  Command: echo 'Hello from container!'
+  Working Directory: /app
+  Timeout: 30s
+
+✓ Command executed
+
+✓ Execution ID: eb41b197-e215-4f9e-87ac-80ce57e732a6
+
+  Exit Code: 0
+  Duration: 3531ms
+  Started: 1/28/2026, 8:55:37 PM
+  Completed: 1/28/2026, 8:55:41 PM
+
+Standard Output:
+────────────────────────────────────────────────────────────
+Hello from container!
+────────────────────────────────────────────────────────────
+```
+
+**History Command:**
+```bash
+$ saac exec --history
+
+Execution History: myapp
+────────────────────────
+
+╔══════════╤═══════════╤═════════════╤═══════════╤══════════╤═══════════════╗
+║ ID       │ Command   │ Status      │ Exit Code │ Duration │ Started       ║
+╠══════════╪═══════════╪═════════════╪═══════════╪══════════╪═══════════════╣
+║ eb41b197 │ echo '...'│ ✓ completed │ 0         │ 0s       │ 1/28/26, 8:55 ║
+║ a3f2c891 │ npm run...│ ✗ completed │ 1         │ 5s       │ 1/28/26, 8:50 ║
+╚══════════╧═══════════╧═════════════╧═══════════╧══════════╧═══════════════╝
+
+Showing 2 of 5 executions
+```
+
+**Location:** `src/commands/exec.js`
+
+**Backend Implementation:**
+- Database table: `exec_requests` (status: pending → running → completed/failed/timeout)
+- Python daemon: `/root/exec-daemon/exec_daemon.py` (polls every 2 seconds)
+- Systemd service: `exec-daemon.service` (auto-restart, logs to `/var/log/exec-daemon.log`)
+
+---
+
+**Backend Requirements (Implemented):**
+- `GET /api/v1/applications/:uuid/env/export` - Export endpoint (deployed 2026-01-28)
+- Returns: `environment` (object), `export_script` (bash format), `dotenv_format` (dotenv format)
+- Rate limit: 10 requests/minute per user
+- Authentication: X-Session-Token or X-API-Key
+- Response includes `expires_in: 300` (5-minute cache recommendation)
+- `POST /api/v1/applications/:uuid/exec` - Execute command in container (deployed 2026-01-28)
+- `GET /api/v1/applications/:uuid/exec/history` - View execution history (deployed 2026-01-28)
+- Rate limit: 30 requests per 5 minutes per user
 
 **Implementation Pattern for New Commands:**
 1. Require flags, no interactive prompts (exception: `init` uses inquirer for app selection)
@@ -560,15 +1014,6 @@ Several commands still need implementation:
 4. Use spinners for async operations
 5. Handle errors with descriptive messages
 
-**Example Module Structure for env.js:**
-```javascript
-async function set(vars) { /* implementation */ }
-async function get(key) { /* implementation */ }
-async function list() { /* implementation */ }
-
-module.exports = { set, get, list };
-```
-
 ### MailHog Integration
 
 The system uses MailHog for email verification in development:
@@ -588,7 +1033,7 @@ 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.16
+## Current Status - Version 1.6.0
 
 ### Completed Features
 
@@ -619,17 +1064,28 @@ The wrapper API expects Git repositories to be hosted on the StartAnAiCompany Gi
 - ✅ `saac update` - Update application configuration (PATCH endpoint)
 - ✅ `saac init` - Link existing application to current directory (interactive)
 - ✅ `saac deploy` - Trigger deployment for current application
+- ✅ `saac deployments` - List deployment history with table display
+- ✅ `saac logs` - View deployment logs (build logs) or runtime logs (container logs)
 - ✅ `saac list` - List all applications with table display
 - ✅ `saac status` - Show login status, user info, and applications
+- ✅ `saac delete` - Delete application with confirmation prompt
+- ✅ `saac whoami` - Show current user information
+
+**Environment & Domain Management:**
+- ✅ `saac env set/get/list` - Manage environment variables (fully implemented)
+- ✅ `saac domain set/show` - Manage application domain (fully implemented)
+
+**Local Development (NEW in 1.5.0):**
+- ✅ `saac run <command>` - Execute local command with remote environment variables
+- ✅ `saac shell` - Open interactive shell with remote environment variables
+- Features: 5-minute caching, secure temp files (0600), automatic cleanup, rate limit handling
+
+**Remote Execution (NEW in 1.6.0):**
+- ✅ `saac exec <command>` - Execute commands in remote container
+- ✅ `saac exec --history` - View execution history
+- Features: Command allowlist, dangerous pattern detection, rate limiting (30/5min), audit logging
 
-**Incomplete Commands:**
-- ⏳ `saac logs` - Not implemented (stub only)
-- ⏳ `saac env` - Not implemented (stub only, needs to export object with set/get/list methods)
-- ⏳ `saac domain` - Not implemented (stub only, needs to export object with set/show methods)
-- ⏳ `saac delete` - Not implemented (stub only)
-- ⏳ `saac whoami` - Not implemented (stub only)
-- ✅ `saac deploy` - Fully implemented
-- ✅ `saac list` - Fully implemented
+**All Commands Implemented!** ✅ No incomplete commands remain
 
 ### Critical Learnings & Bug Fixes
 
@@ -671,7 +1127,7 @@ The wrapper API expects Git repositories to be hosted on the StartAnAiCompany Gi
 
 ### API Endpoint Reference
 
-**Correct Endpoint Paths (v1.4.12):**
+**Correct Endpoint Paths (v1.5.0):**
 - `POST /api/v1/users/register` - Register (email only, git_username optional)
 - `POST /api/v1/users/verify` - Verify email with code
 - `POST /api/v1/auth/login` - Login with API key, get session token
@@ -687,7 +1143,10 @@ The wrapper API expects Git repositories to be hosted on the StartAnAiCompany Gi
 - `GET /api/v1/applications` - List applications
 - `PATCH /api/v1/applications/:uuid` - Update application
 - `POST /api/v1/applications/:uuid/deploy` - Deploy application
-- `GET /api/v1/applications/:uuid/logs` - Get logs
+- `GET /api/v1/applications/:uuid/deployments` - Get deployment history (NEW in 1.4.17)
+- `GET /api/v1/applications/:uuid/deployment-logs` - Get deployment logs (NEW in 1.4.17)
+- `GET /api/v1/applications/:uuid/logs` - Get runtime logs (container logs)
+- `GET /api/v1/applications/:uuid/env/export` - Export environment variables (NEW in 1.5.0)
 - `DELETE /api/v1/applications/:uuid` - Delete application
 
 **Important:** OAuth endpoints (`/oauth/*`) do NOT have the `/api/v1` prefix!
@@ -808,4 +1267,4 @@ Before publishing to npm:
 - `dotenv` - Environment variables
 - `open` - Open browser for OAuth (v8.4.2 for compatibility with chalk v4)
 
-**Version:** 1.4.16 (current)
+**Version:** 1.5.0 (current)

package/bin/saac.js

@@ -22,6 +22,7 @@ const init = require('../src/commands/init');
 const create = require('../src/commands/create');
 const update = require('../src/commands/update');
 const deploy = require('../src/commands/deploy');
+const deployments = require('../src/commands/deployments');
 const logs = require('../src/commands/logs');
 const env = require('../src/commands/env');
 const domain = require('../src/commands/domain');
@@ -30,6 +31,9 @@ const list = require('../src/commands/list');
 const status = require('../src/commands/status');
 const whoami = require('../src/commands/whoami');
 const manual = require('../src/commands/manual');
+const run = require('../src/commands/run');
+const shell = require('../src/commands/shell');
+const execCmd = require('../src/commands/exec');
 
 // Configure CLI
 program
@@ -200,12 +204,62 @@ program
   .action(deploy);
 
 program
-  .command('logs')
-  .description('View application logs')
-  .option('-t, --tail <lines>', 'Number of lines to show', '100')
-  .option('-f, --follow', 'Follow log output')
+  .command('deployments')
+  .alias('deploys')
+  .description('List deployment history')
+  .option('-l, --limit <number>', 'Number of deployments to show', '20')
+  .option('-o, --offset <number>', 'Offset for pagination', '0')
+  .action(deployments);
+
+program
+  .command('logs [deploymentUuid]')
+  .description('View application logs (runtime or deployment logs)')
+  .option('-d, --deployment [uuid]', 'View deployment logs (build logs)')
+  .option('--raw', 'Show raw log output (deployment logs only)')
+  .option('--include-hidden', 'Include hidden log lines (deployment logs only)')
+  .option('-t, --tail <lines>', 'Number of lines to show (runtime logs only)', '100')
+  .option('-f, --follow', 'Follow log output (runtime logs only)')
+  .option('--since <time>', 'Show logs since timestamp (runtime logs only)')
   .action(logs);
 
+// Local development commands
+program
+  .command('run <command>')
+  .description('Run local command with remote environment variables')
+  .option('--sync', 'Force refresh environment variables (skip cache)')
+  .option('-q, --quiet', 'Quiet mode (suppress warnings)')
+  .action(run);
+
+program
+  .command('shell')
+  .description('Open interactive shell with remote environment variables')
+  .option('--cmd <shell>', 'Shell to use (default: $SHELL or /bin/bash)')
+  .option('--sync', 'Force refresh environment variables (skip cache)')
+  .action(shell);
+
+// Remote execution commands
+program
+  .command('exec [command]')
+  .description('Execute command in remote container')
+  .option('--workdir <path>', 'Working directory (default: /app)')
+  .option('--timeout <seconds>', 'Timeout in seconds (default: 30, max: 300)', '30')
+  .option('--history', 'View execution history')
+  .option('--limit <number>', 'Limit for history (default: 20, max: 100)', '20')
+  .option('--offset <number>', 'Offset for history pagination (default: 0)', '0')
+  .action((command, options) => {
+    if (options.history) {
+      execCmd.history(options);
+    } else if (command) {
+      execCmd.exec(command, options);
+    } else {
+      console.error('Error: command is required (unless using --history)');
+      console.log('\nUsage:');
+      console.log('  saac exec <command>           Execute command');
+      console.log('  saac exec --history           View execution history');
+      process.exit(1);
+    }
+  });
+
 // Environment variable commands
 const envCommand = program
   .command('env')

package/package.json

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