shell_exec

Runs a bash command in a persistent session. Off unless the operator enables the shell.

Since 2 Sept 2026

The command is scanned. Hard blocks never run. Risky commands wait for a button. The shell keeps its folder and variables between calls. Output is redacted.

Tool name: shell_exec
Group: Shell
Risk: high
Needs approval: sometimes
Approval rule: Depends on SHELL_APPROVAL. Default risky: MEDIUM and HIGH need a button. HARD BLOCK commands never run.
Allowed in scheduled jobs: No
Default: off

Parameters

Name	Type	Required	Default	Meaning
command	string	Yes		The shell command text.
session	string	No	main	Name of a persistent shell session.
wait	number	No		Seconds to wait for output before returning.
cwd	string	No		Starting folder, inside the shell workspace.
interactive	boolean	No	false	Keep the process open so shell_send can type into it.

Returns

Output so far, and whether the command is still running.

Example (made up for this page)

Call

{
  "command": "demo"
}

Result

$ git status
On branch demo

Side effects

Runs as the bot's OS user
Can change files, use the network and start processes.

How it can fail

When	What the agent sees
Shell is off	A message that the shell is disabled by the operator
Hard block	HARD BLOCK with the reason
Needs approval	Command Approval Required