run_shell
Execute shell commands within a REPL environment, returning structured output with exit code and stdout. Supports stdin piping, timeout, and custom environment variables.
Instructions
Run a shell command inside a REPL context with structured output.
Returns a dict so the caller can branch on exit_code and parse
stdout without string-scraping. Every call is logged to evolution.db
for later recall via `query_command_history`.
Args:
command: The shell command to execute.
repl_id: REPL whose cwd the command runs in.
timeout_seconds: Kill the process if it exceeds this (capped at 600).
cwd: Override the REPL's cwd for this one call.
use_shell: If True, pass to /bin/sh (enables pipes, redirects,
glob expansion). Default False = tokenized exec, safer.
env_extra: Additional env vars merged onto os.environ.
stdin_input: Optional string piped to the command's stdin.
Enables first-class stdin piping so CLI tools that read
from stdin (jq, wc, grep, etc.) work without shell pipe
syntax. When None the child's stdin is /dev/null.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | ||
| command | Yes | ||
| repl_id | Yes | ||
| env_extra | No | ||
| use_shell | No | ||
| stdin_input | No | ||
| timeout_seconds | No |