execute
Destructive
Run shell commands locally or over SSH with configurable timeouts. Returns output and exit code for completed commands or partial output for silent periods.
Instructions
Execute a command locally or over SSH in an isolated channel.
PARAMETER RELATIONSHIPS & VALIDATION:
- `session_id` vs `shell`: `session_id` determines the execution environment. If provided (must be a valid active session), it runs over SSH and `shell` is completely ignored. If omitted, it runs locally, and `shell` (e.g., 'powershell.exe', '/bin/bash') is used.
- `pause_timeout` vs `total_timeout`: These interact to manage execution time. `pause_timeout` (must be > 0) triggers an early return if the command goes silent for that many seconds. `total_timeout` (must be >= `pause_timeout`) sets a hard wall-clock limit even if output is constantly streaming. To wait longer for a quiet command (e.g., a build), increase `pause_timeout`.
- Both timeouts accept floats but invalid ranges (e.g., pause_timeout <= 0, or total_timeout < pause_timeout) or an unknown `session_id` will raise a ValueError.
WHEN NOT TO USE:
Do not use this to send input to an existing command (`respond`), send control keys (`send_control`), or poll a running command (`read_output`).
SIDE EFFECTS:
Spawns a new, stateless process. `cd` or environment variables do NOT persist between calls. For persistent state, start a terminal multiplexer in the foreground. Never use `&` to background TUI apps.
RETURNS:
- {"status": "completed", "output": str, "exit_code": int}
- {"status": "partial", "output": str, "command_id": str}
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| shell | No | Shell for local execution (e.g. 'powershell.exe', '/bin/bash'); ignored for SSH | |
| command | Yes | Shell command to run (stateless — cd does not persist between calls) | |
| session_id | No | SSH session_id from connect_ssh; omit for local execution | |
| pause_timeout | No | Seconds of silence before returning a partial result (> 0, ≤ total_timeout) | |
| total_timeout | No | Hard cap on call duration in seconds (≥ pause_timeout) |