# Shell (/tools/toolkits/local/shell)



**ShellTools** enable an Agent to interact with the shell to run commands.

## Prerequisites [#prerequisites]

[Create and activate a virtual environment](/sdk/setup), then install:

```shell
uv pip install agno openai
```

The Agent model uses an OpenAI key, separately from any toolkit provider credentials.

## Set OpenAI Key [#set-openai-key]

Set your `OPENAI_API_KEY` as an environment variable. You can get one [from OpenAI](https://platform.openai.com/account/api-keys).

<CodeBlockTabs defaultValue="Mac">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="Mac">
      Mac
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Windows PowerShell">
      Windows PowerShell
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="Mac">
    ```bash
    export OPENAI_API_KEY=sk-***
    ```
  </CodeBlockTab>

  <CodeBlockTab value="Windows PowerShell">
    ```powershell
    $env:OPENAI_API_KEY = "your-openai-api-key"
    ```
  </CodeBlockTab>
</CodeBlockTabs>

## Example [#example]

The following agent will run a shell command and show contents of the current directory.

<Note>
  Mention your OS to the agent to make sure it runs the correct command.
</Note>

```python title="cookbook/91_tools/shell_tools.py"
from agno.agent import Agent
from agno.tools.shell import ShellTools

agent = Agent(tools=[ShellTools()])
agent.print_response("Show me the contents of the current directory", markdown=True)
```

<Warning>
  `ShellTools` runs any command the model constructs, with no allowlist or confirmation gate. Setting `base_dir` only sets the working directory for the command; it does not restrict what the command can access. Keep human supervision for untrusted prompts, and run inside a sandbox (container, VM, or [Daytona](/tools/toolkits/others/daytona)) for untrusted code execution.
</Warning>

## Toolkit Params [#toolkit-params]

| Parameter                  | Type                         | Default | Description                                 |
| -------------------------- | ---------------------------- | ------- | ------------------------------------------- |
| `base_dir`                 | `Optional[Union[Path, str]]` | `None`  | Base directory for shell command execution  |
| `enable_run_shell_command` | `bool`                       | `True`  | Enables functionality to run shell commands |
| `all`                      | `bool`                       | `False` | Enables all functionality when set to True  |

## Toolkit Functions [#toolkit-functions]

| Function            | Description                                           |
| ------------------- | ----------------------------------------------------- |
| `run_shell_command` | Runs a shell command and returns the output or error. |

## Developer Resources [#developer-resources]

* [Tools](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/tools/shell.py)