Cursor rule to execute commands and file changes on a remote server

remostessh.cursorrules

# Cursor Rules for Remote Server Operations

## Remote Server Interaction Protocol

### Overview
When operating on remote servers, use the tmux-based persistent session approach to maintain state and environment across multiple command executions. This enables true remote development capabilities with session persistence between AI tool calls.

### Initial Setup
1. **Install tmux** (if not available):
   ```bash
   ssh REMOTE_HOST "yum install -y tmux"           # CentOS/RHEL/Rocky
   ssh REMOTE_HOST "apt-get install -y tmux"       # Ubuntu/Debian
   ssh REMOTE_HOST "dnf install -y tmux"           # Fedora
   ssh REMOTE_HOST "pacman -S tmux"                # Arch Linux
   ssh REMOTE_HOST "pkg install tmux"              # FreeBSD
   ```

2. **Create persistent session**:
   ```bash
   ssh REMOTE_HOST "tmux new-session -d -s ai_session"
   ```

3. **Verify session**:
   ```bash
   ssh REMOTE_HOST "tmux list-sessions"
   ```

### Command Execution Pattern

#### Sending Commands
Use this pattern for ALL remote command execution:
```bash
ssh REMOTE_HOST "tmux send-keys -t ai_session 'COMMAND' Enter"
```

#### Retrieving Output
Always capture output after sending commands:
```bash
ssh REMOTE_HOST "tmux capture-pane -t ai_session -p"
```

#### Best Practices
- Always capture output after each command to verify execution
- Wait for command completion before sending next command
- Use clear, descriptive commands to maintain session clarity
- Check exit codes for critical operations

### Advanced File Editing on Remote Server

#### Method 1: SCP-Based Editing (Recommended for Complex Files)
```bash
# Download file to local workspace
scp REMOTE_HOST:/remote/path/file ./temp_file

# Edit locally using edit_file tool
# Upload back to remote
scp ./temp_file REMOTE_HOST:/remote/path/file

# Clean up local copy
rm ./temp_file
```

#### Method 2: Direct Editing with Heredoc
```bash
ssh REMOTE_HOST "tmux send-keys -t ai_session 'cat > filename << EOF' Enter"
ssh REMOTE_HOST "tmux send-keys -t ai_session 'file content here' Enter"
ssh REMOTE_HOST "tmux send-keys -t ai_session 'EOF' Enter"
```

#### Method 3: Backup and Replace Strategy
```bash
# Always backup before editing
ssh REMOTE_HOST "tmux send-keys -t ai_session 'cp file file.backup.\$(date +%Y%m%d_%H%M%S)' Enter"
# Then apply changes
```

#### Method 4: Echo for Simple Files
```bash
ssh REMOTE_HOST "tmux send-keys -t ai_session 'echo \"content\" > filename' Enter"
```

#### Method 5: Multi-line Content with printf
```bash
ssh REMOTE_HOST "tmux send-keys -t ai_session 'printf \"line1\\nline2\\nline3\" > filename' Enter"
```

### Handling Interactive Commands

#### Commands Requiring Confirmation
Use force flags or redirections to bypass prompts:
```bash
# Instead of: cp source dest
ssh REMOTE_HOST "tmux send-keys -t ai_session 'cp -f source dest' Enter"
# Or: 
ssh REMOTE_HOST "tmux send-keys -t ai_session 'yes | cp source dest' Enter"
# Or bypass aliases:
ssh REMOTE_HOST "tmux send-keys -t ai_session '\\cp source dest' Enter"
```

#### Package Managers
```bash
# Use non-interactive flags
ssh REMOTE_HOST "tmux send-keys -t ai_session 'yum install -y package' Enter"
ssh REMOTE_HOST "tmux send-keys -t ai_session 'apt-get install -y package' Enter"
ssh REMOTE_HOST "tmux send-keys -t ai_session 'dnf install -y package' Enter"
```

#### Configuration Tools
```bash
# Redirect stdin to prevent hanging
ssh REMOTE_HOST "tmux send-keys -t ai_session 'command < /dev/null' Enter"
```

### Directory Navigation and State Management
Maintain working directory context:
```bash
ssh REMOTE_HOST "tmux send-keys -t ai_session 'cd /path/to/directory' Enter"
ssh REMOTE_HOST "tmux send-keys -t ai_session 'pwd' Enter"  # Verify location
```

### Session Management

#### Check Session Status
```bash
ssh REMOTE_HOST "tmux list-sessions"
```

#### Reconnect to Existing Session
```bash
ssh REMOTE_HOST "tmux attach-session -t ai_session"
```

#### Kill Session (when done)
```bash
ssh REMOTE_HOST "tmux kill-session -t ai_session"
```

#### Session Recovery
```bash
# If session becomes unresponsive
ssh REMOTE_HOST "tmux kill-session -t ai_session && tmux new-session -d -s ai_session"
```

### Output Handling and Monitoring

#### Capture Recent Output
```bash
ssh REMOTE_HOST "tmux capture-pane -t ai_session -p"
```

#### Capture Specific Line Count
```bash
ssh REMOTE_HOST "tmux capture-pane -t ai_session -S -20 -p"  # Last 20 lines
ssh REMOTE_HOST "tmux capture-pane -t ai_session -S -100 -p" # Last 100 lines
```

#### Clear Screen (for cleaner output)
```bash
ssh REMOTE_HOST "tmux send-keys -t ai_session 'clear' Enter"
```

#### Monitor Long-Running Commands
```bash
# Add status indicators
ssh REMOTE_HOST "tmux send-keys -t ai_session 'command && echo \"[SUCCESS]\" || echo \"[FAILED]\"' Enter"
```

### Error Handling and Validation

#### Check Command Success
Always verify command execution:
```bash
ssh REMOTE_HOST "tmux send-keys -t ai_session 'echo \"Exit code: \$?\"' Enter"
```

#### Validate Before Execution
```bash
# Test configuration syntax before applying
ssh REMOTE_HOST "tmux send-keys -t ai_session 'nginx -t' Enter"
ssh REMOTE_HOST "tmux send-keys -t ai_session 'httpd -t' Enter"
ssh REMOTE_HOST "tmux send-keys -t ai_session 'systemctl --dry-run reload service' Enter"
```

#### Handle Long-Running Commands
For commands that take time:
```bash
ssh REMOTE_HOST "tmux send-keys -t ai_session 'timeout 300 command' Enter"  # 5 minute timeout
```

### File Transfer Strategies

#### Upload Local File to Remote
```bash
scp local_file REMOTE_HOST:/remote/path/
scp -r local_directory/ REMOTE_HOST:/remote/path/  # Recursive
```

#### Download Remote File to Local
```bash
scp REMOTE_HOST:/remote/path/file local_path/
scp -r REMOTE_HOST:/remote/path/directory/ ./      # Recursive
```

#### Transfer with Compression
```bash
scp -C large_file REMOTE_HOST:/remote/path/        # Compress during transfer
```

### Service Management

#### Restart Services Safely
```bash
# Check status first
ssh REMOTE_HOST "tmux send-keys -t ai_session 'systemctl status service_name' Enter"
# Then restart
ssh REMOTE_HOST "tmux send-keys -t ai_session 'systemctl restart service_name' Enter"
# Verify it started
ssh REMOTE_HOST "tmux send-keys -t ai_session 'systemctl is-active service_name' Enter"
```

#### Check Listening Ports
```bash
ssh REMOTE_HOST "tmux send-keys -t ai_session 'ss -tulnp | grep PORT' Enter"
ssh REMOTE_HOST "tmux send-keys -t ai_session 'netstat -tulnp | grep PORT' Enter"
```

### Log Monitoring

#### Real-time Log Monitoring
```bash
ssh REMOTE_HOST "tmux send-keys -t ai_session 'tail -f /var/log/service.log' Enter"
# Stop with Ctrl+C when needed
ssh REMOTE_HOST "tmux send-keys -t ai_session C-c"
```

#### Recent Log Entries
```bash
ssh REMOTE_HOST "tmux send-keys -t ai_session 'tail -50 /var/log/service.log' Enter"
ssh REMOTE_HOST "tmux send-keys -t ai_session 'journalctl -u service -n 50' Enter"
```

### Security Best Practices

#### Authentication
- Always use SSH key authentication when possible
- Never expose credentials in command history
- Use environment variables for sensitive data

#### Command Safety
- Use quoted strings to prevent injection attacks
- Validate remote paths before operations
- Always backup before making changes
- Test configurations before applying

#### Access Control
```bash
# Check current user context
ssh REMOTE_HOST "tmux send-keys -t ai_session 'whoami && pwd && id' Enter"
```

### Troubleshooting Guide

#### Session Issues
```bash
# Session lost or frozen
ssh REMOTE_HOST "tmux kill-session -t ai_session"
ssh REMOTE_HOST "tmux new-session -d -s ai_session"

# List all sessions
ssh REMOTE_HOST "tmux list-sessions"

# Attach to see what's happening
ssh REMOTE_HOST "tmux attach-session -t ai_session"
```

#### SSH Connection Issues
```bash
ssh -v REMOTE_HOST                    # Verbose debugging
ssh -o ConnectTimeout=10 REMOTE_HOST  # Set timeout
```

#### Command Hanging
```bash
# Send Ctrl+C to running command
ssh REMOTE_HOST "tmux send-keys -t ai_session C-c"

# Send Ctrl+Z to suspend
ssh REMOTE_HOST "tmux send-keys -t ai_session C-z"
```

### Performance Optimization

#### Reduce SSH Overhead
```bash
# Use connection multiplexing in ~/.ssh/config
# Host REMOTE_HOST
#   ControlMaster auto
#   ControlPath ~/.ssh/control-%r@%h:%p
#   ControlPersist 600
```

#### Efficient File Transfers
```bash
# Use rsync for large transfers
rsync -avz --progress local_file REMOTE_HOST:/remote/path/
```

### Example Workflows

#### Complete File Edit Workflow
```bash
# 1. Setup session
ssh REMOTE_HOST "tmux new-session -d -s ai_session"

# 2. Navigate and backup
ssh REMOTE_HOST "tmux send-keys -t ai_session 'cd /etc' Enter"
ssh REMOTE_HOST "tmux send-keys -t ai_session 'cp config.conf config.conf.backup.\$(date +%Y%m%d_%H%M%S)' Enter"

# 3. Download, edit locally, upload
scp REMOTE_HOST:/etc/config.conf ./config.conf.tmp
# Use edit_file tool here
scp ./config.conf.tmp REMOTE_HOST:/etc/config.conf
rm ./config.conf.tmp

# 4. Test and apply
ssh REMOTE_HOST "tmux send-keys -t ai_session 'nginx -t' Enter"
ssh REMOTE_HOST "tmux capture-pane -t ai_session -p"
ssh REMOTE_HOST "tmux send-keys -t ai_session 'systemctl reload nginx' Enter"

# 5. Verify
ssh REMOTE_HOST "tmux send-keys -t ai_session 'systemctl status nginx' Enter"
ssh REMOTE_HOST "tmux capture-pane -t ai_session -p"
```

#### Service Configuration Workflow
```bash
# 1. Check current status
ssh REMOTE_HOST "tmux send-keys -t ai_session 'systemctl status service_name' Enter"

# 2. Edit configuration
scp REMOTE_HOST:/etc/service/config ./temp_config
# Edit with edit_file tool
scp ./temp_config REMOTE_HOST:/etc/service/config

# 3. Validate and reload
ssh REMOTE_HOST "tmux send-keys -t ai_session 'service_name -t' Enter"
ssh REMOTE_HOST "tmux send-keys -t ai_session 'systemctl reload service_name' Enter"

# 4. Verify
ssh REMOTE_HOST "tmux send-keys -t ai_session 'systemctl is-active service_name' Enter"
```

### Variable Definitions
- `REMOTE_HOST`: Replace with actual hostname, IP, or SSH alias
- `ai_session`: Replace with desired session name if different
- `service_name`: Replace with actual service name
- `PORT`: Replace with actual port number

### Notes
- Always capture output to verify command execution
- Maintain session state awareness (current directory, environment variables)
- Use tmux session as if it were your local terminal environment
- Prefer SCP method for complex file editing over inline methods
- Always backup before making changes to critical files
- Test configurations before applying them to production services