shell

Shell

Interface

• Tool: shell_exec
• Method: runs commands via the host's preferred shell, detected once at startup:
  • Unix: /bin/sh -c
  • Windows: PowerShell 7+ (pwsh) if installed, else Windows PowerShell 5.1 (powershell.exe), else cmd.exe. Check the <device> block in your system prompt to see which one is active — it's reported as shell:.
• Timeout: none by default — commands run until they exit. You may pass an explicit timeout if you want fast failure on a command you expect to finish quickly.
• Elevation: sudo and doas commands are fully supported. The plugin detects them, pops a native OS password dialog (macOS: system dialog via osascript, Linux: zenity or kdialog), and injects the -A flag so no TTY is needed. On macOS and Linux the password is captured once per app run and held in memory, so every later privileged command is silent (Linux needs a GUI password tool — zenity/kdialog/ssh-askpass — and otherwise falls back to sudo's ~5-minute timestamp cache); Windows has no sudo. Either way the user sees one prompt, not one per command.
• stdin: set to /dev/null (EOF) so commands that unexpectedly wait for input fail fast instead of hanging.
• Returns combined stdout+stderr; truncated past ~100 KB

Writing commands for the active shell

The selected shell determines the syntax that works. Mismatched syntax fails fast (the runtime classifies "is not recognized" / "syntax is incorrect" as non-retryable) — so you'll see one fast error rather than minutes of retries, but you still wasted a call.

• PowerShell (pwsh or powershell.exe) — use PowerShell cmdlets and operators. Get-ChildItem (or its alias ls/dir), Get-Content (cat/type), Start-Process, $env:NAME for env vars, 2>$null to discard stderr.
  • On Windows PowerShell 5.1 specifically, && and || chain operators do NOT exist — use ; for unconditional chaining, or wrap in if ($?) { ... } for conditional. pwsh 7+ supports &&/|| natively.
  • where is an alias for Where-Object; to find an executable use where.exe foo or Get-Command foo.
  • Never append 2>&1. This tool already returns combined stdout+stderr, so it adds nothing — and on PowerShell it actively breaks the result. See "Never append 2>&1 on PowerShell" below.
• cmd.exe — classic cmd syntax. dir, type, set FOO=bar, %ENV% expansion, 2>nul, && / || work.
• /bin/sh — POSIX. ls, cat, export FOO=bar, $ENV, 2>/dev/null, && / ||.