# Terminal Module Quick Start Guide
Get started with Komodo MCP Terminal operations in 5 minutes.
## Installation
```bash
# Install dependencies
npm install
# Set environment variables
export KOMODO_URL="https://komodo.example.com"
export KOMODO_API_KEY="your-api-key"
export KOMODO_API_SECRET="your-api-secret"
```
## Basic Usage
### 1. Simple Command Execution
Execute a single command without managing sessions:
```typescript
import { handleExecute, handleGetOutput, handleDisconnect } from './src/modules/terminal';
// Execute command (creates session automatically)
const result = await handleExecute({
server_id: 'my-server',
command: 'uptime',
});
// Get output
const output = await handleGetOutput({
session_id: result.sessionId,
});
console.log(output.output.stdout);
// Output: 15:23:45 up 30 days, 2:15, 1 user, load average: 0.45, 0.50, 0.52
// Clean up
await handleDisconnect({ session_id: result.sessionId });
```
### 2. Interactive Session
Execute multiple commands in the same session:
```typescript
import { handleConnect, handleExecute, handleGetOutput, handleDisconnect } from './src/modules/terminal';
// Create persistent session
const session = await handleConnect({
server_id: 'my-server',
options: {
shell: 'bash',
cwd: '/home/user/project',
},
});
const sessionId = session.sessionId;
// Run multiple commands
const commands = [
'pwd',
'ls -la',
'git status',
];
for (const command of commands) {
// Execute
await handleExecute({
server_id: 'my-server',
command,
session_id: sessionId,
});
// Get output
const output = await handleGetOutput({
session_id: sessionId,
});
console.log(`$ ${command}`);
console.log(output.output.stdout);
}
// Close session
await handleDisconnect({ session_id: sessionId });
```
### 3. Command with Environment Variables
```typescript
const result = await handleExecute({
server_id: 'my-server',
command: 'echo $CUSTOM_VAR',
options: {
env: {
CUSTOM_VAR: 'Hello from Komodo!',
},
},
});
const output = await handleGetOutput({
session_id: result.sessionId,
});
console.log(output.output.stdout);
// Output: Hello from Komodo!
await handleDisconnect({ session_id: result.sessionId });
```
## Common Use Cases
### Check Disk Space
```typescript
const { sessionId } = await handleExecute({
server_id: 'prod-server',
command: 'df -h',
});
const output = await handleGetOutput({ session_id: sessionId });
console.log('Disk Usage:', output.output.stdout);
await handleDisconnect({ session_id: sessionId });
```
### Monitor Logs
```typescript
const session = await handleConnect({
server_id: 'prod-server',
});
await handleExecute({
server_id: 'prod-server',
command: 'tail -n 50 /var/log/app.log',
session_id: session.sessionId,
});
const output = await handleGetOutput({
session_id: session.sessionId,
options: {
tail: true,
lines: 50,
},
});
console.log('Recent logs:', output.output.stdout);
await handleDisconnect({ session_id: session.sessionId });
```
### Deploy Application
```typescript
const session = await handleConnect({
server_id: 'prod-server',
options: {
cwd: '/var/www/app',
shell: 'bash',
},
});
const deploySteps = [
'git pull origin main',
'npm install --production',
'npm run build',
'pm2 reload app',
];
for (const step of deploySteps) {
console.log(`Running: ${step}`);
await handleExecute({
server_id: 'prod-server',
command: step,
session_id: session.sessionId,
options: {
timeout: 300, // 5 minutes
},
});
const output = await handleGetOutput({
session_id: session.sessionId,
});
if (output.output.exitCode !== 0) {
console.error('Deployment failed:', output.output.stderr);
break;
}
console.log(output.output.stdout);
}
await handleDisconnect({ session_id: session.sessionId });
```
### System Health Check
```typescript
async function checkSystemHealth(serverId: string) {
const session = await handleConnect({
server_id: serverId,
});
const checks = {
cpu: 'top -bn1 | grep "Cpu(s)"',
memory: 'free -h',
disk: 'df -h /',
uptime: 'uptime',
};
const results: Record<string, string> = {};
for (const [name, command] of Object.entries(checks)) {
await handleExecute({
server_id: serverId,
command,
session_id: session.sessionId,
});
const output = await handleGetOutput({
session_id: session.sessionId,
});
results[name] = output.output.stdout;
}
await handleDisconnect({ session_id: session.sessionId });
return results;
}
// Usage
const health = await checkSystemHealth('prod-server');
console.log('System Health:', health);
```
## Error Handling
### Handling Failed Commands
```typescript
const result = await handleExecute({
server_id: 'my-server',
command: 'exit 1', // Command that fails
});
if (!result.success) {
console.error('Execution failed:', result.error);
} else {
const output = await handleGetOutput({
session_id: result.sessionId,
});
if (output.output.exitCode !== 0) {
console.error('Command failed with exit code:', output.output.exitCode);
console.error('Error output:', output.output.stderr);
}
await handleDisconnect({ session_id: result.sessionId });
}
```
### Handling Timeouts
```typescript
try {
const result = await handleExecute({
server_id: 'my-server',
command: 'sleep 60',
options: {
timeout: 5, // 5 seconds
},
});
const output = await handleGetOutput({
session_id: result.sessionId,
});
await handleDisconnect({ session_id: result.sessionId });
} catch (error) {
console.error('Command timed out:', error);
}
```
### Graceful Session Cleanup
```typescript
async function executeWithCleanup(serverId: string, command: string) {
let sessionId: string | undefined;
try {
const result = await handleExecute({
server_id: serverId,
command,
});
sessionId = result.sessionId;
const output = await handleGetOutput({
session_id: sessionId,
});
return output.output;
} finally {
if (sessionId) {
await handleDisconnect({
session_id: sessionId,
}).catch(err => {
console.error('Failed to disconnect:', err);
});
}
}
}
// Usage
const output = await executeWithCleanup('my-server', 'ls -la');
console.log(output.stdout);
```
## MCP Tool Usage
When using via MCP tools directly:
### komodo_terminal_Connect
```json
{
"name": "komodo_terminal_Connect",
"arguments": {
"server_id": "my-server",
"options": {
"shell": "bash",
"cwd": "/home/user"
}
}
}
```
### komodo_terminal_Execute
```json
{
"name": "komodo_terminal_Execute",
"arguments": {
"server_id": "my-server",
"command": "ls -la",
"session_id": "term_my-server_1234567890_abc123"
}
}
```
### komodo_terminal_GetOutput
```json
{
"name": "komodo_terminal_GetOutput",
"arguments": {
"session_id": "term_my-server_1234567890_abc123",
"options": {
"lines": 100,
"tail": true
}
}
}
```
### komodo_terminal_Disconnect
```json
{
"name": "komodo_terminal_Disconnect",
"arguments": {
"session_id": "term_my-server_1234567890_abc123",
"options": {
"killProcesses": true
}
}
}
```
## Best Practices
### 1. Always Clean Up Sessions
```typescript
// ✅ Good
const session = await handleConnect({ server_id: 'server' });
try {
// ... operations ...
} finally {
await handleDisconnect({ session_id: session.sessionId });
}
// ❌ Bad - session leaks
const session = await handleConnect({ server_id: 'server' });
// ... operations ...
// No cleanup!
```
### 2. Set Appropriate Timeouts
```typescript
// ✅ Good - long timeout for slow operations
await handleExecute({
server_id: 'server',
command: 'npm install',
options: {
timeout: 600, // 10 minutes
},
});
// ❌ Bad - default timeout may be too short
await handleExecute({
server_id: 'server',
command: 'npm install',
});
```
### 3. Reuse Sessions for Multiple Commands
```typescript
// ✅ Good - single session
const session = await handleConnect({ server_id: 'server' });
for (const cmd of commands) {
await handleExecute({
server_id: 'server',
command: cmd,
session_id: session.sessionId,
});
}
await handleDisconnect({ session_id: session.sessionId });
// ❌ Bad - creates new session for each command
for (const cmd of commands) {
const result = await handleExecute({
server_id: 'server',
command: cmd,
});
await handleDisconnect({ session_id: result.sessionId });
}
```
### 4. Check Exit Codes
```typescript
// ✅ Good
const output = await handleGetOutput({ session_id: sessionId });
if (output.output.exitCode !== 0) {
console.error('Command failed:', output.output.stderr);
return;
}
// ❌ Bad - ignores failures
const output = await handleGetOutput({ session_id: sessionId });
console.log(output.output.stdout);
```
## Troubleshooting
### Session Not Found
**Problem:** Getting "Session not found" error
**Solution:** Session may have expired. Create a new session:
```typescript
const session = await handleConnect({ server_id: 'server' });
```
### Output Not Available
**Problem:** Output is empty or incomplete
**Solution:** Wait for command to complete:
```typescript
let output = await handleGetOutput({ session_id: sessionId });
while (!output.output.isComplete) {
await new Promise(resolve => setTimeout(resolve, 1000));
output = await handleGetOutput({ session_id: sessionId });
}
```
### Connection Timeout
**Problem:** Connection times out
**Solution:** Increase timeout or check server connectivity:
```typescript
await handleConnect({
server_id: 'server',
options: {
timeout: 60, // 60 seconds
},
});
```
## Next Steps
- Read full [Terminal Module Documentation](./TERMINAL_MODULE.md)
- Check [API Mapping](./API_MAPPING.md) for all available tools
- Review [tests/terminal.test.ts](../tests/terminal.test.ts) for more examples
- Explore [Environment Configuration](./ENVIRONMENT.md) for setup
## Getting Help
- Check [troubleshooting section](./TERMINAL_MODULE.md#troubleshooting) in full docs
- Review error responses and messages
- Enable debug logging: `export KOMODO_LOG_LEVEL=debug`
- Check active sessions: `getActiveSessionCount()`
