term-cli

Name: term-cli
Author: EliasOenal

94stars9forks

How to install term-cli?

eliasoenal/term-cli/term-cli

$npx -y skills add EliasOenal/term-cli --skill term-cli

Installs into the current project.

Summary

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

Files · 1

View on GitHub

SKILL.md

1	# Terminal Session Control
2
3	You can now run any interactive application using term-cli — dev servers, debuggers, REPLs, databases, SSH sessions, editors, and TUIs — without blocking.
4
5	Debuggers encouraged: Prefer interactive debuggers (`pdb`, `gdb`) via `term-cli` whenever appropriate for the task. This complements (and is often superior to) print-based debugging: set breakpoints, step, inspect state, then `capture` to reason.
6
7	Think concurrently: term-cli runs long tasks in the background. Start tests/builds/servers in one session while you write docs or investigate code in parallel. Once all other tasks are done, check back with `wait`/`capture`. Tip: occasionally run `date +"%H:%M:%S"` in a session to see when things happened, estimate future execution and to calibrate your own loop speed.
8
9	Self-documenting: Run `term-cli --help` or `term-cli <command> --help` for complete usage details.
10
11	## Quick Start
12
13	```bash
14	term-cli start --session dev && term-cli run --session dev "make test"
15	# ... do other work ...
16	term-cli wait --session dev && term-cli capture --session dev
17	term-cli kill --session dev
18	```
19
20	## Commands
21
22	### Session Management
23
24	```bash
25	term-cli start --session NAME --cwd /path
26	term-cli kill --session NAME
27	term-cli list
28	term-cli status --session NAME
29	```
30
31	### Running Commands
32
33	```bash
34	term-cli run --session NAME "make test" --wait --timeout 60 # default: 10s
35	```
36
37	### Sending Input
38
39	```bash
40	term-cli send-text --session NAME ":wq" --enter && term-cli wait --session NAME
41	term-cli send-key --session NAME C-c
42	term-cli send-stdin --session NAME < file.txt
43	term-cli send-mouse --session NAME --text "Item B"
44	term-cli send-mouse --session NAME --text "Item B" --scroll-down 3
45	```
46
47	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`
48
49	`send-mouse` works only in alternate screen mode (active TUI). Prefer `--text` targets over coordinates when possible.
50
51	### Capturing Output
52
53	```bash
54	# Visible screen only (default: physical rows, trimmed, no ANSI)
55	# Prefer this — it's almost always enough
56	term-cli capture --session NAME
57
58	# Last N physical rows from the bottom of the visible screen
59	term-cli capture --session NAME --tail 10
60
61	# Last N logical lines from scrollback+visible history (joins wrapped lines)
62	# Use only when you need output that scrolled off-screen
63	# In alternate screen (TUIs / nested tmux), this is blocked by default
64	term-cli capture --session NAME --scrollback 20
65
66	# Override alternate-screen protection (may return stale/misleading history)
67	term-cli capture --session NAME --scrollback 20 --force
68
69	# Include ANSI escape codes (colors) — works with any mode
70	term-cli capture --session NAME --scrollback 10 --raw
71
72	# Annotated capture — pane metadata + highlight annotations
73	# Shows screen mode, bell, cursor position, and highlighted TUI elements
74	# Use this when operating TUIs where you need to identify selected items
75	term-cli capture --session NAME --annotate
76
77	# Default capture auto-enables annotations for active alternate-screen TUIs.
78	# Force plain output when needed:
79	term-cli capture --session NAME --no-annotate
80
81	# Optional line numbers (1-based) for visible-screen captures (not scrollback)
82	term-cli capture --session NAME --annotate --line-numbers
83	```
84
85	When to use `--annotate` vs `--raw` vs plain capture:
86	- Plain `capture` — default for shells, REPLs, command output. Fast, clean text.
87	- `--annotate` — for TUIs (menus, file managers, settings panels) where you need to know what's happening. Returns visible content plus an `Annotations:` section with screen mode (normal/alternate), bell alerts, cursor position (`Cursor: row,col`, 1-based), optional mouse mode (`Mouse: ...` when enabled), and highlighted rows (1-based). Bell alerts are one-shot: shown once then cleared.
88	- Auto behavior — plain `capture` auto-enables annotations only when an active alternate-screen TUI is detected; idle shell prompts stay plain. Use `--annotate` / `--no-annotate` to override.
89	- `--raw` — when you need exact ANSI escape codes (e.g., parsing color semantics yourself). Higher token cost.
90
91	### Waiting
92
93	Prefer `wait` — it detects shell prompts ($, %, #), REPL prompts (>>>, (Pdb), >), and is fastest.
94
95	```bash
96	term-cli wait --session NAME
97	```
98
99	Use `wait-idle` for TUIs (vim, htop, less) that don't have a detectable prompt — waits for screen to settle:
100
101	```bash
102	term-cli wait-idle --session NAME # defaults: 2s idle, 10s timeout
103	```
104
105	Use `wait-for` sparingly —

EliasOenalPublisher · 1 listing

Preview

EliasOenal/term-cli

# Terminal Session Control

**You can now run any interactive application using term-cli** — dev servers, debuggers, REPLs, databases, SSH sessions, editors, and TUIs — without blocking.

**Debuggers encouraged:** Prefer **interactive debuggers** (`pdb`, `gdb`) via `term-cli` whenever appropriate for the task. This complements (and is often super

**Think concurrently:** term-cli runs long tasks in the background. Start tests/builds/servers in one session while you write docs or investigate code in parall

RepoEliasOenal/term-cli

LicenseBSD-3-Clause-Clear

TypeSkills

CategoryDesign

UpdatedMar 2026

Repo stars94

First seenJul 22, 2026

People who liked this also viewed

6 picks

Type

term-cli

94stars9forks

View on GitHub

How to install term-cli?

eliasoenal/term-cli/term-cli

$npx -y skills add EliasOenal/term-cli --skill term-cli

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Terminal Session Control
2
3	You can now run any interactive application using term-cli — dev servers, debuggers, REPLs, databases, SSH sessions, editors, and TUIs — without blocking.
4
5	Debuggers encouraged: Prefer interactive debuggers (`pdb`, `gdb`) via `term-cli` whenever appropriate for the task. This complements (and is often superior to) print-based debugging: set breakpoints, step, inspect state, then `capture` to reason.
6
7	Think concurrently: term-cli runs long tasks in the background. Start tests/builds/servers in one session while you write docs or investigate code in parallel. Once all other tasks are done, check back with `wait`/`capture`. Tip: occasionally run `date +"%H:%M:%S"` in a session to see when things happened, estimate future execution and to calibrate your own loop speed.
8
9	Self-documenting: Run `term-cli --help` or `term-cli <command> --help` for complete usage details.
10
11	## Quick Start
12
13	```bash
14	term-cli start --session dev && term-cli run --session dev "make test"
15	# ... do other work ...
16	term-cli wait --session dev && term-cli capture --session dev
17	term-cli kill --session dev
18	```
19
20	## Commands
21
22	### Session Management
23
24	```bash
25	term-cli start --session NAME --cwd /path
26	term-cli kill --session NAME
27	term-cli list
28	term-cli status --session NAME
29	```
30
31	### Running Commands
32
33	```bash
34	term-cli run --session NAME "make test" --wait --timeout 60 # default: 10s
35	```
36
37	### Sending Input
38
39	```bash
40	term-cli send-text --session NAME ":wq" --enter && term-cli wait --session NAME
41	term-cli send-key --session NAME C-c
42	term-cli send-stdin --session NAME < file.txt
43	term-cli send-mouse --session NAME --text "Item B"
44	term-cli send-mouse --session NAME --text "Item B" --scroll-down 3
45	```
46
47	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`
48
49	`send-mouse` works only in alternate screen mode (active TUI). Prefer `--text` targets over coordinates when possible.
50
51	### Capturing Output
52
53	```bash
54	# Visible screen only (default: physical rows, trimmed, no ANSI)
55	# Prefer this — it's almost always enough
56	term-cli capture --session NAME
57
58	# Last N physical rows from the bottom of the visible screen
59	term-cli capture --session NAME --tail 10
60
61	# Last N logical lines from scrollback+visible history (joins wrapped lines)
62	# Use only when you need output that scrolled off-screen
63	# In alternate screen (TUIs / nested tmux), this is blocked by default
64	term-cli capture --session NAME --scrollback 20
65
66	# Override alternate-screen protection (may return stale/misleading history)
67	term-cli capture --session NAME --scrollback 20 --force
68
69	# Include ANSI escape codes (colors) — works with any mode
70	term-cli capture --session NAME --scrollback 10 --raw
71
72	# Annotated capture — pane metadata + highlight annotations
73	# Shows screen mode, bell, cursor position, and highlighted TUI elements
74	# Use this when operating TUIs where you need to identify selected items
75	term-cli capture --session NAME --annotate
76
77	# Default capture auto-enables annotations for active alternate-screen TUIs.
78	# Force plain output when needed:
79	term-cli capture --session NAME --no-annotate
80
81	# Optional line numbers (1-based) for visible-screen captures (not scrollback)
82	term-cli capture --session NAME --annotate --line-numbers
83	```
84
85	When to use `--annotate` vs `--raw` vs plain capture:
86	- Plain `capture` — default for shells, REPLs, command output. Fast, clean text.
87	- `--annotate` — for TUIs (menus, file managers, settings panels) where you need to know what's happening. Returns visible content plus an `Annotations:` section with screen mode (normal/alternate), bell alerts, cursor position (`Cursor: row,col`, 1-based), optional mouse mode (`Mouse: ...` when enabled), and highlighted rows (1-based). Bell alerts are one-shot: shown once then cleared.
88	- Auto behavior — plain `capture` auto-enables annotations only when an active alternate-screen TUI is detected; idle shell prompts stay plain. Use `--annotate` / `--no-annotate` to override.
89	- `--raw` — when you need exact ANSI escape codes (e.g., parsing color semantics yourself). Higher token cost.
90
91	### Waiting
92
93	Prefer `wait` — it detects shell prompts ($, %, #), REPL prompts (>>>, (Pdb), >), and is fastest.
94
95	```bash
96	term-cli wait --session NAME
97	```
98
99	Use `wait-idle` for TUIs (vim, htop, less) that don't have a detectable prompt — waits for screen to settle:
100
101	```bash
102	term-cli wait-idle --session NAME # defaults: 2s idle, 10s timeout
103	```
104
105	Use `wait-for` sparingly —

EliasOenalPublisher · 1 listing

Preview

EliasOenal/term-cli

# Terminal Session Control

**You can now run any interactive application using term-cli** — dev servers, debuggers, REPLs, databases, SSH sessions, editors, and TUIs — without blocking.

**Debuggers encouraged:** Prefer **interactive debuggers** (`pdb`, `gdb`) via `term-cli` whenever appropriate for the task. This complements (and is often super

**Think concurrently:** term-cli runs long tasks in the background. Start tests/builds/servers in one session while you write docs or investigate code in parall

RepoEliasOenal/term-cli

LicenseBSD-3-Clause-Clear

TypeSkills

CategoryDesign

UpdatedMar 2026

Repo stars94

First seenJul 22, 2026

People who liked this also viewed

6 picks

Type