run
Type commands into a persistent terminal session and wait for output, exit status, or the next prompt; works with shells and interactive programs.
Instructions
Type a line into the session, press Enter, and wait for the result: the session's form of a shell tool call, and of a line typed at gdb's or python's prompt.
At a bash prompt (shell integration) it waits for the command to exit
and returns its output with the exit status (pipestatus for a pipeline;
no ; echo $? needed); for a build or a testsuite give timeout_s the
whole run (up to 1500 s) and get the exit status in one reply. Inside
a program (gdb, python, psql, ...) it waits for the program's next
prompt; starting one from bash returns at its first prompt, or its
first screen (vim, less; continue with send). The session persists:
cwd, variables and a running program stay between calls.
Output longer than max_lines keeps its first and last lines with a
marker naming what was left out; nothing is lost: read pages it,
search finds lines in it. So no | tail, | head, 2>&1 > log
-- and never a pipe or redirect on an interactive program (gdb
without -batch, python): it then waits at a prompt you cannot see.
To watch for particular lines as they come, show=REGEX replies with
the matching lines and the last few while the command runs
unfiltered, exit status its own.
At timeout_s -- a short one gives your turn back soon -- the
command keeps running and its region stays open: wait keeps
waiting, send keys=["ctrl+c"] interrupts, send signal="TERM" if
it survives. until=REGEX returns as soon as the output matches.
Several lines go one at a time, each once the previous is back at the
prompt; a line that asks a question or times out stops the rest. Into Python or IPython they go
as one paste (an exception drops the lines after it). Predictable
questions: expect. Keystrokes (ctrl+c, tab, arrows) are send's
keys, not an argument here.
prompt_pattern is rarely needed: never pass one to start a program
(shell, gdb, pdb, lldb, python and any prompt ending in $ # % > are
known); only after a reply came back "waiting" at a prompt it did not
know, which then offers the pattern.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| show | No | regex: reply with only the output lines matching it, in order, plus the last few (like `| grep`, but the command runs unfiltered and the log keeps everything), e.g. "error:|warning:|^FAIL" for a build -- or a program's answer: gdb's `step` under `set debug infrun 1` | |
| force | No | type even over someone else's unsubmitted line at the prompt, discarding it first; only for a line you know is stale | |
| input | Yes | the line to type (Enter is added); several lines are sent one at a time, each after the previous is back at a prompt | |
| until | No | regex: return as soon as the output matches it, the command still running (status "until"; `wait` resumes); not a prompt pattern | |
| typing | No | type the input as a person would, for a human watching: {wps, mistakes, seed} | |
| save_to | No | a file to copy the command's output into, as `> FILE 2>&1` would, while the command itself runs unredirected (the reply and the log are as usual): written at once, kept up to date while it runs, written in full when it ends. A relative path is in the session's current directory; the file is on the machine this server runs on, even for a session over ssh. For a later diff or grep by other tools; `read` and `search` need no file | |
| session | Yes | the session's name (from session_create or session_list) | |
| max_lines | No | lines of output shown in the reply; longer output is clipped in the middle, led by its summary lines (test results, compiler errors, make's failure) when the middle holds them; all of it stays readable with `read`/`search` | |
| settle_ms | No | into a program with no recognised prompt: return once output has been quiet this long and nothing is visibly working (default 3000) | |
| timeout_s | No | seconds to wait before giving up (the command keeps running; `wait` resumes); at most 1500 | |
| last_lines | No | reply with only the last N lines of the output (like `| tail -N`, but the command runs unfiltered and the log keeps everything; the reply says where the rest is); with `show`, how many last lines follow the matches (default 3) | |
| show_after | No | with `show`: also this many lines after each match (like `grep -A N`); a match is numbered "N:", a line after one "N-" | |
| prompt_pattern | No | regex that marks the program's prompt at the end of the cursor line; rarely needed, the default knows shell, gdb, pdb, lldb and python prompts and any ending in $ # % >; pass one only after a reply came back "waiting" at a prompt it did not know (it offers the pattern); make it cover a part that changes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |