From d07d8b66d6f22899f93ad54c6c285421b46b0638 Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Thu, 18 Jun 2026 11:53:59 -0600 Subject: [PATCH] docs: Added documentation for the new command passthrough support in the REPL --- REPL.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/REPL.md b/REPL.md index 9b39c87..b3f6906 100644 --- a/REPL.md +++ b/REPL.md @@ -350,8 +350,39 @@ The `.exit` command is used to move between modes in the Coyote REPL. | `.exit session` | Exit the active session | | `.exit agent` | Exit the active agent | | `.exit rag` | Exit the active RAG | -| `.exit` | Exit the Coyote REPL | +| `.exit` | Exit the Coyote REPL | ## `.help` - Show the help guide Just like with any shell or REPL, you sometimes need a little help and want to know what commands are available to you. That's when you use the `.help` command. + +## `!` - Run an arbitrary shell command + +Prefix any line with `!` to run the rest of the line as a shell command instead of sending it to the LLM. Output streams +straight to your terminal in real time, and you don't spend any tokens and no output is sent to the LLM. + +![command-passthrough](./images/repl/command-passthrough.png) + +Particularly useful inside [`coyote --sandbox`](Sandboxes) where you need to modify the sandbox itself without running +`sbx exec -- `; e.g., `!apt-get install httpie`, `!git pull`, `!cargo build`, +or anything else you'd normally run in a terminal, without leaving the REPL. + +### How it works + +- The line is passed to your shell as ` -c ""`. Note that Coyote does _not_ inspect or sanitize the + command, but rather the shell parses it. So pipes (`!ls | grep yaml`), redirects (`!cat > /tmp/out`), env-var + expansion (`!echo "$HOME"`), globbing (`!ls *.toml`), command substitution (`!grep ERROR $(ls *.log)`), and inline + env vars (`!FOO=bar cmd`) all work exactly like they do in a normal terminal. +- The `!` must be the **first** character of the line. Lines like ` !ls` (leading whitespace), `echo !foo` (inline `!`), + or `! ` (just whitespace after) are not recognized as shell pass-through; The first two go to the LLM, the last + prints a usage hint. +- Press `Ctrl-C` at any time to interrupt a long-running command. `SIGINT` propagates to the child shell; the command + stops, `[exit 130]` prints, and you return to the prompt. +- If the command exits non-zero, `[exit N]` is printed. Successful commands return to the prompt silently. + +### Limitations + +- `!cd /tmp` does _not_ persist. Each `!cmd` runs in a fresh child shell, so subsequent `!pwd` will show the REPL's + original working directory, not `/tmp`. +- The command is _not_ written to your shell's history file (`~/.bash_history`, `~/.zsh_history`). It is, however, saved + in the REPL's reedline history (use up-arrow to recall).