docs: Added documentation for the new command passthrough support in the REPL

2026-06-18 11:53:59 -06:00
parent 89fb4d62b3
commit d07d8b66d6
1 changed files with 32 additions and 1 deletions
@@ -355,3 +355,34 @@ The `.exit` command is used to move between modes in 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.
 ## `!<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 <name> -- <command>`; 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 `<SHELL> -c "<your command>"`. 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).