<!--
hoody-terminal Subskill (cli)
Auto-generated by Hoody Skills Generator
Generated: 2026-05-06T20:42:13.977Z
Model: mimo-v2.5-pro + fixer:mimo-v2.5-pro
Mode: cli


Tokens: 9586

DO NOT EDIT MANUALLY - Changes will be overwritten on next generation
-->

# hoody-terminal Subskill

## Overview

### What This Service Does

hoody-terminal provides HTTP-accessible terminal sessions that are multiplayer by default. It enables:

- **Persistent terminal sessions** — Create, manage, and share terminal instances across clients
- **Command execution** — Run commands synchronously or asynchronously via REST
- **Terminal automation** — Screen reading, key simulation, and condition-based waiting
- **System monitoring** — Process management, resource stats, and port inspection
- **Real-time I/O** — WebSocket connections for interactive terminal access

### When to Use It

| Scenario | Use hoody-terminal |
|----------|-------------------|
| Execute commands in a container | `hoody terminal exec` or `hoody run` |
| Monitor running processes | `hoody terminal list` (processes) |
| Automate interactive CLI tools | `hoody terminal wait`, `find`, `press` |
| Capture terminal state | `hoody terminal snapshot`, `screenshot` |
| Share terminal sessions | Multiplayer WebSocket via `hoody terminal connect` |
| Check service health | `hoody terminal health` |

### How It Fits Into Hoody Philosophy

Terminal sessions are HTTP endpoints — every terminal operation is a REST call. Sessions are multiplayer by default, enabling collaborative debugging and shared access. The `hoody run` shorthand provides quick ephemeral command execution without session management overhead.

**Key principles:**
- All operations go through `hoody` CLI — never use curl
- Target containers with `-c <container-id>` or `HOODY_CONTAINER` env var
- Use `-o json` for machine-readable output
- `hoody run` is shorthand for `hoody terminal exec --ephemeral`

---

## Common Workflows

### Workflow 1: Health Check and Session Discovery

Verify the terminal service is running and discover active sessions.

```
# Check service health
hoody terminal health -c my-container
```

```
{
  "status": "healthy",
  "service": "hoody-terminal",
  "version": "1.0.0",
  "uptime": 3600,
  "timestamp": "2025-01-15T10:30:00Z"
}
```

```
# List all active terminal sessions
hoody terminal list -c my-container -o json
```

```
[
  {
    "terminal_id": "term-abc123",
    "created_at": "2025-01-15T09:00:00Z",
    "status": "active",
    "command_count": 5
  }
]
```

### Workflow 2: Quick Command Execution (Ephemeral)

Use `hoody run` for one-off commands without managing sessions.

```
# Run a single command (ephemeral session)
hoody run -c my-container -- ls -la /tmp
```

```
# Run with JSON output for parsing
hoody run -c my-container -o json -- df -h
```

```
{
  "command_id": "cmd-xyz789",
  "exit_code": 0,
  "stdout": "Filesystem      Size  Used Avail Use% Mounted on\n/dev/sda1        50G   20G   30G  40% /",
  "stderr": ""
}
```

### Workflow 3: Persistent Session with Command History

Create a session, execute multiple commands, and review history.

```
# Step 1: Create a persistent terminal session
hoody terminal create -c my-container -o json
```

```
{
  "terminal_id": "term-def456",
  "status": "created",
  "created_at": "2025-01-15T10:00:00Z"
}
```

```
# Step 2: Execute commands in the session
hoody terminal exec -c my-container --terminal-id term-def456 -- whoami
```

```
# Step 3: Execute another command
hoody terminal exec -c my-container --terminal-id term-def456 -- pwd
```

```
# Step 4: Get command result
hoody terminal command-result -c my-container cmd-abc123 -o json
```

```
{
  "command_id": "cmd-abc123",
  "status": "completed",
  "exit_code": 0,
  "stdout": "/home/user",
  "stderr": "",
  "started_at": "2025-01-15T10:01:00Z",
  "completed_at": "2025-01-15T10:01:01Z"
}
```

```
# Step 5: Review full session history
hoody terminal history -c my-container term-def456 -o json
```

```
[
  {
    "command_id": "cmd-abc123",
    "command": "whoami",
    "exit_code": 0,
    "timestamp": "2025-01-15T10:01:00Z"
  },
  {
    "command_id": "cmd-def456",
    "command": "pwd",
    "exit_code": 0,
    "timestamp": "2025-01-15T10:02:00Z"
  }
]
```

### Workflow 4: Terminal Automation (Screen Reading + Waiting)

Automate interactive applications by reading screen state and waiting for conditions.

```
# Step 1: Create session and run interactive tool
hoody terminal create -c my-container -o json
```

```
{
  "terminal_id": "term-auto123",
  "status": "created"
}
```

```
# Step 2: Execute an interactive command
hoody terminal exec -c my-container --terminal-id term-auto123 -- htop
```

```
# Step 3: Get terminal snapshot (current screen state)
hoody terminal snapshot -c my-container --terminal-id term-auto123 -o json
```

```
{
  "terminal_id": "term-auto123",
  "lines": [
    "  PID USER      PR  NI    VIRT    RES    SHR S  %CPU  %MEM     TIME+ COMMAND",
    "    1 root      20   0   16852   4608   3584 S   0.0   0.1   0:00.05 init"
  ],
  "cursor": {
    "row": 0,
    "col": 0
  },
  "dimensions": {
    "rows": 24,
    "cols": 80
  }
}
```

```
# Step 4: Search for specific text on screen
hoody terminal find -c my-container --terminal-id term-auto123 --pattern "CPU" -o json
```

```
{
  "matches": [
    {
      "text": "CPU",
      "row": 0,
      "col": 55
    }
  ],
  "match_count": 1
}
```

```
# Step 5: Wait for a condition (screen stable for 500ms)
hoody terminal wait -c my-container --terminal-id term-auto123 --mode stable --debounce-ms 500 -o json
```

```
{
  "terminal_id": "term-auto123",
  "condition_met": true,
  "snapshot": {
    "lines": ["..."],
    "cursor": {
      "row": 5,
      "col": 10
    }
  }
}
```

### Workflow 5: Interactive Terminal via WebSocket

Connect to a terminal session for real-time bidirectional I/O.

```
# Connect to terminal via WebSocket (interactive)
hoody terminal connect -c my-container --terminal-id term-abc123
```

This opens an interactive terminal session. Multiple clients can connect to the same `terminal_id` for multiplayer access.

### Workflow 6: Screenshot and Raw Output Capture

Capture terminal state for debugging or documentation.

```
# Capture terminal screenshot as image
hoody terminal screenshot -c my-container --terminal-id term-abc123
```

```
# Get raw terminal output buffer
hoody terminal raw-output -c my-container --terminal-id term-abc123 -o json
```

```
{
  "terminal_id": "term-abc123",
  "format": "text",
  "content": "user@host:~$ ls -la\ntotal 32\ndrwxr-xr-x 4 user user 4096 Jan 15 10:00 .\n..."
}
```

---

## Advanced Operations

### Workflow 7: Long-Running Command with Async Polling

Execute a long-running command and poll for results.

```
# Step 1: Execute command (returns immediately with command_id)
hoody terminal exec -c my-container --terminal-id term-abc123 -- "find / -name '*.log' 2>/dev/null" -o json
```

```
{
  "command_id": "cmd-long789",
  "status": "running"
}
```

```
# Step 2: Poll for result
hoody terminal command-result -c my-container cmd-long789 -o json
```

```
{
  "command_id": "cmd-long789",
  "status": "running",
  "stdout": "/var/log/syslog\n/var/log/auth.log\n"
}
```

```
# Step 3: Abort if needed (graceful - sends SIGINT)
hoody terminal abort -c my-container cmd-long789
```

```
# Or force kill (sends SIGKILL)
hoody terminal abort -c my-container cmd-long789 --force
```

### Workflow 8: System Monitoring and Process Management

Monitor system resources and manage processes.

```
# Get comprehensive system resources
hoody terminal resources -c my-container -o json
```

```
{
  "cpu": {
    "usage_percent": 25.5,
    "cores": 4
  },
  "memory": {
    "total_mb": 8192,
    "used_mb": 4096,
    "usage_percent": 50.0
  },
  "disk": {
    "total_gb": 100,
    "used_gb": 40,
    "usage_percent": 40.0
  },
  "uptime_seconds": 86400
}
```

```
# List all system processes
hoody terminal list -c my-container -o json
```

```
[
  {
    "pid": 1,
    "name": "init",
    "cpu_percent": 0.0,
    "memory_mb": 4.5,
    "state": "S"
  },
  {
    "pid": 1234,
    "name": "node",
    "cpu_percent": 15.2,
    "memory_mb": 256.0,
    "state": "R"
  }
]
```

```
# Get detailed info for specific process
hoody terminal get -c my-container 1234 -o json
```

```
{
  "pid": 1234,
  "name": "node",
  "cmdline": "node /app/server.js",
  "cpu_percent": 15.2,
  "memory_mb": 256.0,
  "state": "R",
  "started_at": "2025-01-15T08:00:00Z",
  "open_files": [
    "/app/server.js",
    "/var/log/app.log"
  ]
}
```

```
# Send signal to process (SIGTERM)
hoody terminal signal -c my-container --pid 1234 --signal SIGTERM
```

```
# Send signal by process name (kills all matching)
hoody terminal signal -c my-container --name "node" --signal SIGKILL
```

### Workflow 9: Network Port Inspection

Discover listening services and their associated processes.

```
# List all listening ports
hoody terminal ports -c my-container -o json
```

```
[
  {
    "port": 8080,
    "protocol": "tcp",
    "state": "LISTEN",
    "process": {
      "pid": 1234,
      "name": "node"
    }
  },
  {
    "port": 5432,
    "protocol": "tcp",
    "state": "LISTEN",
    "process": {
      "pid": 5678,
      "name": "postgres"
    }
  }
]
```

### Workflow 10: Keyboard Input Simulation

Send keyboard input and key presses to automate terminal interactions.

```
# Write text to terminal (auto-appends Enter by default)
hoody terminal write -c my-container --terminal-id term-auto123 --input "ls -la"
```

```
# Write text without auto-Enter
hoody terminal write -c my-container --terminal-id term-auto123 --input "echo " --no-newline
```

```
# Send named key press (e.g., Ctrl+C)
hoody terminal press -c my-container --terminal-id term-auto123 --keys "Ctrl+c"
```

```
# Send multiple key presses
hoody terminal press -c my-container --terminal-id term-auto123 --keys "Enter,Tab,Escape"
```

```
# Paste text with bracketed paste mode
hoody terminal paste -c my-container --terminal-id term-auto123 --input "multi-line\ntext here" --bracketed
```

```
# List all supported key names
hoody terminal keys -c my-container -o json
```

```
[
  "Enter",
  "Tab",
  "Escape",
  "Backspace",
  "Delete",
  "Up",
  "Down",
  "Left",
  "Right",
  "Home",
  "End",
  "PageUp",
  "PageDown",
  "F1",
  "F2",
  "Ctrl+c",
  "Ctrl+d",
  "Ctrl+z"
]
```

### Workflow 11: Wait for Regex Pattern Match

Block until specific text appears on screen.

```
# Wait for "Ready" to appear on screen
hoody terminal wait -c my-container --terminal-id term-auto123 --mode regex --pattern "Ready" -o json
```

```
{
  "terminal_id": "term-auto123",
  "condition_met": true,
  "matched_text": "Server Ready on port 8080",
  "snapshot": {
    "lines": [
      "Starting application...",
      "Loading configuration...",
      "Server Ready on port 8080"
    ],
    "cursor": {
      "row": 3,
      "col": 0
    }
  }
}
```

### Error Recovery Patterns

**Session cleanup on failure:**
```
# Delete terminal session to free resources
hoody terminal delete -c my-container term-abc123 --yes
```

**Check automation metrics for resource usage:**
```
# Monitor server-side resource consumption
hoody terminal metrics -c my-container -o json
```

```
{
  "active_sessions": 3,
  "memory_used_mb": 45.2,
  "memory_cap_mb": 512.0,
  "active_waiters": 1,
  "max_sessions": 100
}
```

**Get per-session automation state:**
```
# Check if vterm is active and session dimensions
hoody terminal automation-state -c my-container term-abc123 -o json
```

```
{
  "terminal_id": "term-abc123",
  "vterm_active": true,
  "dimensions": {
    "rows": 24,
    "cols": 80
  },
  "alt_screen": false,
  "title": "bash",
  "scrollback_length": 1000,
  "active_waiters": 0,
  "last_change_ago_ms": 1500
}
```

### Performance Considerations

1. **Use ephemeral sessions** (`hoody run`) for one-off commands to avoid resource accumulation
2. **Delete sessions** when done to free memory and PTY resources
3. **Monitor metrics** with `hoody terminal metrics` to track resource usage
4. **Prefer `snapshot` over `raw-output`** for structured screen reading
5. **Use `wait` with debounce** to avoid polling loops

---

## Quick Reference

### Essential Commands

| Command | Description |
|---------|-------------|
| `hoody terminal health` | Service health check |
| `hoody run -c <id> -- <cmd>` | Quick command execution |
| `hoody terminal create -c <id>` | Create persistent session |
| `hoody terminal exec -c <id> --terminal-id <tid> -- <cmd>` | Execute in session |
| `hoody terminal list -c <id>` | List active sessions |
| `hoody terminal delete -c <id> <tid>` | Destroy session |
| `hoody terminal connect -c <id> --terminal-id <tid>` | WebSocket connection |
| `hoody terminal snapshot -c <id> --terminal-id <tid>` | Get screen state |
| `hoody terminal wait -c <id> --terminal-id <tid> --mode regex --pattern <p>` | Wait for condition |
| `hoody terminal resources -c <id>` | System resource stats |

### Common Parameters

| Parameter | Description |
|-----------|-------------|
| `-c <container-id>` | Target container (required) |
| `--terminal-id <id>` | Target terminal session |
| `-o json` | Machine-readable JSON output |
| `--yes` | Skip confirmation prompts |
| `--force` | Force kill (for abort) |
| `--pattern <regex>` | PCRE2 regex pattern |
| `--mode <type>` | Wait mode: `stable`, `regex` |
| `--debounce-ms <n>` | Stability debounce time |
| `--keys <key-list>` | Comma-separated key names |
| `--bracketed` | Use bracketed paste mode |

### Typical Response Formats

**Health response:**
```
{
  "status": "healthy",
  "service": "hoody-terminal",
  "version": "1.0.0",
  "uptime": 3600,
  "timestamp": "2025-01-15T10:30:00Z"
}
```

**Command result:**
```
{
  "command_id": "cmd-abc123",
  "status": "completed",
  "exit_code": 0,
  "stdout": "output here",
  "stderr": "",
  "started_at": "2025-01-15T10:00:00Z",
  "completed_at": "2025-01-15T10:00:01Z"
}
```

**Terminal session:**
```
{
  "terminal_id": "term-abc123",
  "status": "active",
  "created_at": "2025-01-15T10:00:00Z",
  "command_count": 5
}
```

**Process info:**
```
{
  "pid": 1234,
  "name": "node",
  "cpu_percent": 15.2,
  "memory_mb": 256.0,
  "state": "R"
}
```