Skip to content
Back to search

term-cli

Interactive terminals for AI agents, built for what you can't --yes away. SSH+MFA, GRUB/U-Boot, debconf installers, SOL/serial consoles, fsck, cryptsetup, pdb/gdb, apt, certbot, pwsh and even Vim in tmux-backed sessions. Agent-driven, human-assisted for secrets/MFA. Single-file Python. Agent Skill. CI with 700+ tests. BSD License.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/eliasoenal--term-cli/badge.svg)](/listings/eliasoenal--term-cli)

HTML

<a href="/listings/eliasoenal--term-cli"><img src="/api/listings/eliasoenal--term-cli/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Requires Python 3.8+ and tmux.

# Install tmux first (if not already installed)
brew install tmux        # macOS
apt install tmux         # Debian/Ubuntu

# Install the latest stable term-cli, term-assist, and agent skill files
curl -fsSL https://github.com/EliasOenal/term-cli/releases/latest/download/install.sh | bash

Or from a cloned repo:

git clone https://github.com/EliasOenal/term-cli.git && cd term-cli && ./install.sh

<details> <summary>Install options</summary>

# System-wide install (to /usr/local/bin, requires sudo)
./install.sh --system

# Custom install directory
./install.sh --prefix ~/bin

# Skip skill file installation
./install.sh --no-skill

# Install skills only for specific agents
./install.sh --skill opencode,claude

# Uninstall
./install.sh --uninstall

</details>

<details> <summary>Manual installation</summary>

curl -LO https://github.com/EliasOenal/term-cli/releases/latest/download/term-cli
curl -LO https://github.com/EliasOenal/term-cli/releases/latest/download/term-assist
chmod +x term-cli term-assist

</details>

Agent Skills

[Agent Skills](https://agentskills.io) are instructions and resources that agents discover and load on demand to work more accurately. term-cli includes a skill in `skills/term-cli/`. The installer automatically installs it for all known agents.

**Skills vs MCP:** Skills suit coding agents—concise CLI commands keep context lean when balancing automation with large codebases. MCP servers suit specialized loops that benefit from persistent state and rich introspection. term-cli is CLI-native; no MCP server needed.

**No skill? No problem.** Point your agent at `term-cli --help` and let it figure things out. The CLI is self-documenting.

<details> <summary>Manual skill installation</summary>

Install to your home directory so it works across projects.

# GitHub Copilot (VS Code / Copilot CLI)
mkdir -p ~/.copilot/skills && cp -r skills/term-cli ~/.copilot/skills/

# Gemini CLI
mkdir -p ~/.gemini/skills && cp -r skills/term-cli ~/.gemini/skills/

# OpenAI Codex CLI
mkdir -p ~/.agents/skills && cp -r skills/term-cli ~/.agents/skills/

# OpenClaw
mkdir -p ~/.openclaw/skills && cp -r skills/term-cli ~/.openclaw/skills/

# Claude Code
mkdir -p ~/.claude/skills && cp -r skills/term-cli ~/.claude/skills/

# OpenCode
mkdir -p ~/.config/opencode/skills && cp -r skills/term-cli ~/.config/opencode/skills/

</details>

Works with

<details> <summary>Agents and tools</summary>

Works with **Claude Code**, **Gemini CLI**, **Cursor**, **Aider**, **OpenCode**, **Cline**, **Kilo Code**, **Windsurf**, **Amazon Q**, **Augment Code**, **Moltbot**, **OpenHands**, and any agent that can run shell commands. </details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 352 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="assets/term-cli.svg" alt="term-cli" width="150">
  3. <img src="assets/challenge.webp" alt="term-cli challenge demo">
  4. </p>
  5. **term-cli: unlock interactive terminals for AI agents**
  6. If it blocks in a terminal, it blocks your agent.
  7. Run interactive programs from your AI coding agent without blocking. Dev servers, debuggers, REPLs, databases, editors, SSH sessions, TUIs, long-running watchers, and interactive installers.
  8. <details>
  9. <summary>More examples</summary>
  10. Dev servers (`npm run dev`), debuggers (`pdb`, `gdb`), REPLs (python, node), databases (`psql`, mysql), editors (vim, nano), SSH sessions, TUIs (htop, less), log watchers (`tail -f`, `journalctl`), terminal browsers (carbonyl, browsh, lynx), IRC clients (irssi, weechat), packet capture (termshark), package manager prompts (apt, brew, pacman), EULAs and interactive wizards.
  11. </details>
  12. Hand control to humans for passwords and MFA prompts. Or flip it: human drives while the agent watches, advises, and learns—a pair programmer, rubber duck, or observer looking over your shoulder.
  13. - **term-cli**: Agents run interactive programs in detached terminal sessions (tmux-backed)
  14. - **term-assist**: Humans collaborate, enter passwords, handle MFA, prepare sessions
  15. Single-file Python. No dependencies beyond tmux. 700+ tests, CI on every commit. BSD licensed.
  16. ## The Problem
  17. Agents can run shell commands, but interactive programs block forever:
  18. ```bash
  19. vim config.yaml # millions of developers trapped, now agents join them
  20. npm run dev # blocks, need to see output
  21. python -m pdb script.py # blocks, need to interact
  22. gdb ./crash # blocks, need to step through
  23. ssh user@server # needs password
  24. apt-get install nginx # needs Y/n confirmation
  25. certbot certonly # interactive wizard
  26. tail -f /var/log/app.log # runs forever, need to watch
  27. ```
  28. ## The Solution
  29. ```bash
  30. term-cli start --session debug && term-cli run --session debug "python -m pdb script.py" --wait
  31. term-cli send-text --session debug "b main" --enter && term-cli wait --session debug
  32. term-cli send-text -s debug "c" --enter && term-cli wait -s debug # continue
  33. term-cli capture --session debug # see where we are
  34. term-cli kill --session debug
  35. ```
  36. Agents run commands in detached tmux sessions. Humans join when needed via term-assist.
  37. ## TTY-first workflows you can’t --yes away
  38. Some workflows have no reliable non-interactive mode: serial consoles, boot menus, installers, and full-screen TUIs. `term-cli` lets agents wait for prompts, send keys, capture state, and hand off to humans only when needed.
  39. - **Professional network gear and console access**
  40. - **SSH sessions:** interactive prompts for passwords/MFA and stateful CLI workflows.
  41. - **Paged output (“more”):** keypress to continue on long command output.
  42. - **Serial console sessions:** run tools like `screen` or `picocom` on USB-serial adapters (lab devices, console servers, remote hands).
  43. - **BMC Serial-over-LAN (SOL):** interactive console access via IPMI/iDRAC/iLO-style SOL when the OS is down or pre-boot.
  44. - **Virtual machine consoles:** QEMU/`virsh console`/hypervisor consoles are terminal-first and commonly explored interactively.
  45. - <details>
  46. <summary>Vendor examples</summary>
  47. - **Cisco IOS / IOS XE and Cisco NX-OS:** first-boot setup wizard/utility with interactive yes/no and field entry.
  48. - **Juniper Junos:** password setup with enter and confirm a second time.
  49. </details>
  50. - **Embedded, SoC, and lab bring-up**
  51. - **Bootloaders:** U-Boot autoboot interrupt, boot menus, environment editing, netboot and flash flows over serial.
  52. - **Manufacturing and validation firmware:** text menus for tests, calibration, burn-in loops, operator prompts.
  53. - **JTAG/SWD debugging:** GDB interactive stepping and inspection loops (you can script parts, but engineers usually explore interactively).
  54. - **System recovery and pre-OS troubleshooting**
  55. - **Boot repair shells:** GRUB rescue and bootloader menus when the system won’t boot normally.
  56. - **Initramfs and emergency modes:** dracut, BusyBox, systemd emergency shell workflows that require live interaction.
  57. - **Filesystem repair and recovery:** tools like `fsck` that ask repeated fix/skip prompts (optionally with human approval).
  58. - **Linux installers and package configuration prompts**
  59. - **Debconf TUIs:** timezone (`tzdata`), locales, keyboard, mail setup (`postfix`), database setup wizards.
  60. - **License/EULA accept flows:** “scroll and accept” installers that block on keypress.
  61. - **Config-file conflicts during upgrades:** keep local vs maintainer config prompts (`dpkg`/`apt`).
  62. ## Installation
  63. Requires Python 3.8+ and tmux.
  64. ```bash
  65. # Install tmux first (if not already installed)
  66. brew install tmux # macOS
  67. apt install tmux # Debian/Ubuntu
  68. # Install the latest stable term-cli, term-assist, and agent skill files
  69. curl -fsSL https://github.com/EliasOenal/term-cli/releases/latest/download/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 94 on GitHub
  70. ```
  71. Or from a cloned repo:
  72. ```bash
  73. git clone https://github.com/EliasOenal/term-cli.git && cd term-cli && ./install.sh
  74. ```
  75. <details>
  76. <summary>Install options</summary>
  77. ```bash
  78. # System-wide install (to /usr/local/bin, requires sudo)
  79. ./install.sh --system
  80. # Custom install directory
  81. ./install.sh --prefix ~/bin
  82. # Skip skill file installation
  83. ./install.sh --no-skill
  84. # Install skills only for specific agents
  85. ./install.sh --skill opencode,claude
  86. # Uninstall
  87. ./install.sh --uninstall
  88. ```
  89. </details>
  90. <details>
  91. <summary>Manual installation</summary>
  92. ```bash
  93. curl -LO https://github.com/EliasOenal/term-cli/releases/latest/download/term-cli
  94. curl -LO https://github.com/EliasOenal/term-cli/releases/latest/download/term-assist
  95. chmod +x term-cli term-assist
  96. ```
  97. </details>
  98. ### Agent Skills
  99. [Agent Skills](https://agentskills.io) are instructions and resources that agents discover and load on demand to work more accurately. term-cli includes a skill in `skills/term-cli/`. The installer automatically installs it for all known agents.
  100. **Skills vs MCP:** Skills suit coding agents—concise CLI commands keep context lean when balancing automation with large codebases. MCP servers suit specialized loops that benefit from persistent state and rich introspection. term-cli is CLI-native; no MCP server needed.
  101. **No skill? No problem.** Point your agent at `term-cli --help` and let it figure things out. The CLI is self-documenting.
  102. <details>
  103. <summary>Manual skill installation</summary>
  104. Install to your home directory so it works across projects.
  105. ```bash
  106. # GitHub Copilot (VS Code / Copilot CLI)
  107. mkdir -p ~/.copilot/skills && cp -r skills/term-cli ~/.copilot/skills/
  108. # Gemini CLI
  109. mkdir -p ~/.gemini/skills && cp -r skills/term-cli ~/.gemini/skills/
  110. # OpenAI Codex CLI
  111. mkdir -p ~/.agents/skills && cp -r skills/term-cli ~/.agents/skills/
  112. # OpenClaw
  113. mkdir -p ~/.openclaw/skills && cp -r skills/term-cli ~/.openclaw/skills/
  114. # Claude Code
  115. mkdir -p ~/.claude/skills && cp -r skills/term-cli ~/.claude/skills/
  116. # OpenCode
  117. mkdir -p ~/.config/opencode/skills && cp -r skills/term-cli ~/.config/opencode/skills/
  118. ```
  119. </details>
  120. ### Works with
  121. <details>
  122. <summary>Agents and tools</summary>
  123. Works with **Claude Code**, **Gemini CLI**, **Cursor**, **Aider**, **OpenCode**, **Cline**, **Kilo Code**, **Windsurf**, **Amazon Q**, **Augment Code**, **Moltbot**, **OpenHands**, and any agent that can run shell commands.
  124. </details>
  125. ## term-cli Commands (for agents)
  126. | Command | Description |
  127. |---------|-------------|
  128. | `start --session NAME` | Create session |
  129. | `kill --session NAME` | Destroy session |
  130. | `list` | List sessions |
  131. | `status --session NAME` | Show state and process tree |
  132. | `run --session NAME "cmd" --wait --timeout 60` | Run command, wait for prompt |
  133. | `send-text --session NAME "text" --enter` | Send text (--enter for Enter key) |
  134. | `send-key --session NAME C-c` | Send special key |
  135. | `send-mouse --session NAME --text "Item"` | Click a visible TUI item (alternate screen mode) |
  136. | `send-mouse --session NAME --text "Item" --scroll-down 3` | Scroll at a visible TUI item |
  137. | `send-stdin --session NAME < file.txt` | Send multiline content |
  138. | `capture --session NAME` | Capture screen (auto-annotates active TUIs; --tail/--scrollback for more) |
  139. | `wait --session NAME --timeout 30` | Wait for prompt |
  140. | `wait-idle --session NAME --idle 2` | Wait for output to settle |
  141. | `wait-for --session NAME "pattern"` | Wait for text to appear (--print-match/--print-match-context N) |
  142. | `resize --session NAME --cols 120 --rows 40` | Resize terminal |
  143. | `scroll --session NAME -50` | Scroll viewport (negative=up) |
  144. | `pipe-log --session NAME /tmp/out.log` | Stream output to file |
  145. | `unpipe --session NAME` | Stop streaming |
  146. | `upload --session NAME local.txt remote.txt` | Upload file to session (gzip-compressed, SHA-256 verified) |
  147. | `download --session NAME remote.txt local.txt` | Download file from session (gzip-compressed, SHA-256 verified) |
  148. | `request --session NAME --message "help"` | Request human assistance |
  149. | `request-wait --session NAME` | Wait for human to complete |
  150. | `request-status --session NAME` | Check if request pending |
  151. | `request-cancel --session NAME` | Cancel pending request |
  152. Session names may contain ASCII letters, digits, dashes, and underscores.
  153. Run `term-cli --help` or `term-cli <command> --help` for details.
  154. ### Keys
  155. `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`
  156. ## term-assist Commands (for humans)
  157. | Command | Description |
  158. |---------|-------------|
  159. | `list` | List all sessions (highlights pending requests) |
  160. | `attach --session NAME` | Join session with status bar UI |
  161. | `attach --session NAME --readonly` | Observe without typing |
  162. | `done --session NAME` | Mark request complete (with optional message) |
  163. | `detach` | Detach from current session |
  164. | `start --session NAME` | Create session for agent to use later |
  165. | `kill --session NAME` | Kill session |
  166. | `kill --all` | Kill all sessions |
  167. | `lock --session NAME` | Lock session (agent read-only) |
  168. | `unlock --session NAME` | Unlock session |
  169. ### Key Bindings (when attached)
  170. | Key | Action |
  171. |-----|--------|
  172. | `Ctrl+B Enter` | Complete request (prompt for optional message to agent) |
  173. | `Ctrl+B d` | Detach (if request still pending, agent's request-wait fails) |
  174. ## Example: Dev Server
  175. ```bash
  176. term-cli start --session server && term-cli run --session server "npm run dev"
  177. term-cli wait-idle --session server --timeout 15 && term-cli capture --session server
  178. # ... later ...
  179. term-cli send-key --session server C-c && term-cli wait --session server
  180. term-cli kill --session server
  181. ```
  182. ## Example: Python Debugger
  183. ```bash
  184. term-cli start --session debug && term-cli run --session debug "python3 -m pdb script.py"
  185. term-cli wait -s debug && term-cli send-text -s debug "b 42" --enter && term-cli wait -s debug
  186. term-cli send-text -s debug "c" --enter && term-cli wait -s debug && term-cli capture -s debug
  187. ```
  188. ## Example: File Transfer (over SSH)
  189. ```bash
  190. term-cli start --session remote && term-cli run --session remote "ssh user@server" --wait
  191. term-cli upload --session remote ./deploy.tar.gz /tmp/deploy.tar.gz
  192. term-cli download --session remote /var/log/app.log ./app.log
  193. # Pipe support
  194. cat config.json | term-cli upload --session remote - /app/config.json
  195. term-cli download --session remote /app/data.csv - | head -5
  196. ```
  197. ## Example: SSH with Password (Agent + Human)
  198. **Agent side:**
  199. ```bash
  200. term-cli start --session remote && term-cli run --session remote "ssh user@server"
  201. term-cli wait --session remote && term-cli capture --session remote
  202. # If password prompt shown, request human help; if shell prompt, key auth succeeded
  203. term-cli request --session remote --message "Please enter SSH password"
  204. term-cli request-wait --session remote && term-cli capture --session remote
  205. term-cli run --session remote "ls -la" --wait
  206. ```
  207. **Human side:**
  208. ```bash
  209. term-assist list # See: "remote: Please enter SSH password"
  210. term-assist attach --session remote # Join, see status bar with message
  211. # (enter password)
  212. # Press Ctrl+B Enter, then type optional message or just Enter to complete
  213. ```
  214. ## Example: Human Prepares Session for Agent
  215. **Human side:**
  216. ```bash
  217. term-assist start --session prod --locked
  218. term-assist attach --session prod
  219. # (login to server, set up environment, etc.)
  220. # Press Ctrl+B d to detach when ready
  221. term-assist unlock --session prod
  222. ```
  223. **Agent side:**
  224. ```bash
  225. term-cli capture --session prod # See current state
  226. term-cli run --session prod "deploy.sh" --wait --timeout 300
  227. term-cli kill --session prod
  228. ```
  229. ## Key Features
  230. - **Explicit errors**: `start` fails if session exists; `kill` fails if not exists
  231. - **Wait strategies**: `wait` (prompt), `wait-idle` (output settles), `wait-for` (pattern)
  232. - **Human collaboration**: `request`/`request-wait` + term-assist for passwords, MFA prompts, manual steps
  233. - **Locked sessions**: Human controls, agent observes (start with `--locked` or use `term-assist lock`)
  234. - **Dimension preservation**: Human joining doesn't resize agent's terminal
  235. - **File transfer**: `upload`/`download` with gzip compression, SHA-256 verification, and pipe support (`-` for stdin/stdout)
  236. - **Clean output**: Visible screen only, whitespace trimmed, `--scrollback N` for history
  237. - **Self-documenting**: `--help` on every command
  238. ## Exit Codes
  239. | Code | Meaning |
  240. |------|---------|
  241. | 0 | Success |
  242. | 1 | Runtime error |
  243. | 2 | Invalid input |
  244. | 3 | Timeout |
  245. | 4 | Human detached while request pending |
  246. | 5 | Session locked (agent read-only) |
  247. | 127 | tmux not found |
  248. ## Design Philosophy
  249. - **Two tools**: term-cli for agents, term-assist for humans
  250. - **Single files**: No dependencies beyond Python stdlib + tmux
  251. - **Self-documenting**: Point at `--help` and go
  252. ## Versioning
  253. term-cli follows Semantic Versioning. Run `term-cli --version` or
  254. `term-assist --version` to identify an installation. Releases and their notes
  255. are available on [GitHub](https://github.com/EliasOenal/term-cli/releases); the
  256. maintainer process is documented in [RELEASING.md](RELEASING.md).
  257. ## Requirements
  258. - Python 3.8+
  259. - tmux
  260. ## License
  261. BSD License — see [LICENSE](LICENSE)
  262. ## Contributing
  263. Issues and PRs welcome. This is a small, focused tool: simplicity is a feature.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.