# term-cli

> Controls interactive terminal sessions for running long-lived processes, servers, REPLs, debuggers, and TUI programs without blocking. Use when you need to run dev servers (npm run dev), debuggers (pdb, gdb), REPLs (python, node), databases (psql, mysql), SSH sessions, or editors (vim, nano) — any interactive or blocking program.

- Author: Elias Oenal
- Repository: EliasOenal/term-cli
- Version: 20260131220739
- Stars: 27
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/EliasOenal/term-cli
- Web: https://mule.run/skillshub/@@EliasOenal/term-cli~term-cli:20260131220739

---

---
name: term-cli
description: Controls interactive terminal sessions for running long-lived processes, servers, REPLs, debuggers, and TUI programs without blocking. Use when you need to run dev servers (npm run dev), debuggers (pdb, gdb), REPLs (python, node), databases (psql, mysql), SSH sessions, or editors (vim, nano) — any interactive or blocking program.
allowed-tools: Bash(term-cli:*)
---

# Terminal Session Control

**You can now run interactive applications** — dev servers, debuggers, REPLs, databases, SSH sessions, and TUI programs. You can even use vim and finally escape it.

**Memory compaction?** Your scrollback buffer preserves history. Use `capture --lines 200` to recall what happened.

**Shared sessions:** Hand control to your human for passwords, CAPTCHAs, or complex tasks via `request`. They use `term-assist` to attach and help.

**Self-documenting:** Run `term-cli --help` or `term-cli <command> --help` for complete usage details.

## Quick Start

```bash
term-cli start --session dev
term-cli run --session dev "npm run dev"
term-cli capture --session dev
term-cli send-key --session dev C-c
term-cli kill --session dev
```

## Commands

### Session Management

```bash
term-cli start --session NAME --cwd /path
term-cli kill --session NAME
term-cli list
term-cli status --session NAME
```

### Running Commands

```bash
term-cli run --session NAME "make test" --wait --timeout 60   # default: 10s
```

### Sending Input

```bash
term-cli send-text --session NAME ":wq" --enter
term-cli send-key --session NAME C-c
term-cli send-stdin --session NAME < file.txt
```

Keys: `C-c` `C-d` `C-z` `C-u` `C-l` (ctrl), `Enter` `Escape` `Tab` `Space` `BSpace`, `Up` `Down` `Left` `Right`, `Home` `End` `PPage` `NPage`, `F1`-`F12`

### Capturing Output

```bash
term-cli capture --session NAME --lines 200 --raw
```

### Waiting

**Prefer `wait`** — it detects shell prompts ($, %, #), REPL prompts (>>>, (Pdb), >), and is fastest.

```bash
term-cli wait --session NAME --timeout 30                     # default: 10s
```

**Use `wait-idle` for TUIs** (vim, htop, less) that don't have a detectable prompt — waits for screen to settle:

```bash
term-cli wait-idle --session NAME --seconds 2 --timeout 30    # defaults: 2s idle, 10s timeout
```

**Use `wait-for` sparingly** — waits for pattern in screen output:

```bash
term-cli wait-for --session NAME "error" "success" --ignore-case --capture --timeout 30   # default: 10s
```

⚠️ **Warning:** `wait-for` matches the entire screen including your echoed command:

```bash
# WRONG — pattern appears in echoed command, triggers immediately
term-cli send-text --session NAME "./build.sh && echo DONE" --enter
term-cli wait-for --session NAME "DONE"

# RIGHT — wait for program output (not your own marker)
term-cli run --session NAME "npm run dev"
term-cli wait-for --session NAME "Listening on port"

# RIGHT — assemble pattern during print so it doesn't appear in command
term-cli send-text --session NAME "./build.sh && printf 'DON' && printf 'E\n'" --enter
term-cli wait-for --session NAME "DONE"

# BEST — use wait or run --wait when possible
term-cli run --session NAME "./build.sh" --wait
```

### Human Assistance

When you need human help (passwords, CAPTCHAs, manual intervention):

```bash
term-cli request --session NAME --message "Please enter SSH password"
term-cli request-wait --session NAME --timeout 300            # default: 300s (5 min)
term-cli request-status --session NAME
term-cli request-cancel --session NAME
```

**How it works:** Your human runs `term-assist list` to see pending requests, then `term-assist attach --session NAME` to join. A status bar shows your message. When finished, they press **Ctrl+B Enter** to complete — they can optionally type a response message for you. `request-wait` then returns and you continue.

If they detach with Ctrl+B d without completing, `request-wait` fails with exit code 4.

### Other Commands

```bash
term-cli resize --session NAME --cols 120 --rows 40
term-cli scroll --session NAME -50
term-cli pipe-log --session NAME /tmp/out.log
term-cli unpipe --session NAME
```

## Example: Dev Server

```bash
term-cli start --session server
term-cli run --session server "npm run dev"
term-cli capture --session server
term-cli send-key --session server C-c
term-cli kill --session server
```

## Example: Python Debugger (pdb)

```bash
term-cli start --session debug
term-cli run --session debug "python3 -m pdb script.py"
term-cli wait --session debug
term-cli send-text --session debug "b 42" --enter
term-cli wait --session debug
term-cli send-text --session debug "c" --enter
term-cli wait --session debug
term-cli capture --session debug
```

## Example: SSH with Password (Human Helps)

```bash
term-cli start --session remote
term-cli run --session remote "ssh user@host"
term-cli wait-for --session remote "password:" --ignore-case --timeout 30
term-cli request --session remote --message "Please enter SSH password"
term-cli request-wait --session remote
term-cli capture --session remote
```

## Tips

- Use `--help` on any command for details: `term-cli run --help`
- Default timeout is 10s for most wait commands — increase for builds, tests, or slow operations
- `run --wait` already waits for prompt — don't add another `wait` after it
- Capture before sending keys to verify screen state
- Default `request-wait` timeout is 5 minutes — usually no need to override
- Locked sessions (exit code 5): agent can only `capture`, `status`, `wait-*`, and `request`

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success |
| 1 | Runtime error |
| 2 | Invalid input |
| 3 | Timeout |
| 4 | Human detached without completing |
| 5 | Session locked (agent read-only) |
| 127 | tmux not found |

## Feedback

Found a bug or have an idea to improve term-cli? Email the maintainer: Elias Oenal <termcli@eliasoenal.com>