execute
Destructive
Run shell commands locally or via SSH with isolated channels, configurable pause and total timeouts to handle long-running or silent tasks.
Instructions
Execute a command locally or over SSH in an isolated channel.
Local: just pass command (defaults to cmd.exe/bash).
SSH: also pass session_id from connect_ssh.
PARAMETER GUIDANCE: session_id selects SSH vs local; shell only
applies to local. Chain with && for multi-step; use Zellij
for persistent state. Raise pause_timeout (not total_timeout) for
quiet jobs. Raises ValueError if session_id is invalid.
WHEN NOT TO USE: respond (stdin), send_control (keys), read_output (poll).
SIDE EFFECTS: Spawns a process. Partial commands live until finished
or interrupted. TUI apps MUST start in foreground — never use &.
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) |