Reference for the shell default tool: run_command, run_script, which, and get_env.

Shell Tool

Script: powers/shell.py Dependencies: pydantic

Execute shell commands, run multi-line scripts, find executables, and read environment variables. Use with caution -- consider restricting via agent tool permissions for untrusted environments.

run_command

Execute a single shell command and return stdout, stderr, and exit code.

Input

Field	Type	Default	Description
`command`	`str`	required	The shell command to execute
`working_dir`	`str`	`null`	Working directory for the command
`timeout`	`int`	`60`	Maximum seconds to wait for command
`max_output`	`int`	`100000`	Maximum bytes for stdout+stderr combined (0 = unlimited)

Output

Field	Type	Description
`ok`	`bool`	`true` if exit code is 0
`stdout`	`str`	Standard output
`stderr`	`str`	Standard error
`exit_code`	`int`	Process exit code
`command`	`str`	The command that was executed

Examples

// List files
{"command": "ls -la"}

// Run in a specific directory
{"command": "pwd", "working_dir": "/tmp"}

// Pipe commands
{"command": "echo 'hello' | grep hello"}

// With timeout
{"command": "sleep 5 && echo done", "timeout": 10}

Output Truncation

When max_output is exceeded, the output is intelligently truncated:

The first ~40% and last ~40% of the output are preserved
Error-like lines from the middle (containing "error", "Error", "Traceback", "panic", etc.) are preserved
A [... truncated N bytes ...] marker indicates what was removed

run_script

Execute a multi-line shell script. Useful when you need multiple sequential commands with shared state (variables, cd, etc.).

Input

Field	Type	Default	Description
`script`	`str`	required	Multi-line script content
`interpreter`	`str`	`/bin/bash`	Script interpreter path
`working_dir`	`str`	`null`	Working directory
`timeout`	`int`	`120`	Max seconds to wait
`max_output`	`int`	`100000`	Maximum bytes for stdout+stderr combined (0 = unlimited)

Output

Field	Type	Description
`ok`	`bool`	`true` if exit code is 0
`stdout`	`str`	Standard output
`stderr`	`str`	Standard error
`exit_code`	`int`	Process exit code

Examples

// Multi-line script
{"script": "cd /tmp\necho $(pwd)\nls -la"}

// Python script
{"script": "import sys\nprint(sys.version)", "interpreter": "/usr/bin/python3"}

which

Find the absolute path of an executable on the system PATH.

Input

Field	Type	Default	Description
`command`	`str`	required	Command name to look up

Output

Field	Type	Description
`ok`	`bool`	`true` if found
`path`	`str`	Absolute path to the executable
`error`	`str`	Error message if not found

Examples

// Find Python
{"command": "python"}
// -> {"ok": true, "path": "/usr/bin/python"}

// Find Git
{"command": "git"}
// -> {"ok": true, "path": "/usr/bin/git"}

// Not found
{"command": "nonexistent"}
// -> {"ok": false, "error": "Command not found: nonexistent"}

get_env

Read the value of an environment variable.

Input

Field	Type	Default	Description
`name`	`str`	required	Environment variable name
`default`	`str`	`null`	Default value if not set

Output

Field	Type	Description
`ok`	`bool`	`true` if variable exists or default provided
`value`	`str`	The variable's value
`error`	`str`	Error message if not set and no default

Examples

// Read HOME
{"name": "HOME"}
// -> {"ok": true, "value": "/Users/alice"}

// With default
{"name": "MY_VAR", "default": "fallback"}
// -> {"ok": true, "value": "fallback"}

// Not set, no default
{"name": "UNSET_VAR"}
// -> {"ok": false, "error": "Environment variable not set: UNSET_VAR"}

Tips

Commands run via shell=True (bash), so shell features like pipes, redirects, and globs work
The max_output truncation preserves error lines from the middle of long outputs, making it easier to diagnose failures in verbose commands
Use run_script instead of run_command when you need cd, variables, or multi-step logic
Consider setting timeout appropriately for long-running commands

Shell Tool

On this page