> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesa.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# fs.bash()

> Run shell commands against a mounted Mesa filesystem.

`fs.bash(...)` builds a Bash interpreter rooted at the mounted filesystem. Commands run against MesaFS; no host shell is spawned.

```python theme={null}
bash = fs.bash(cwd="/acme/app", env={"CI": "true"}, timeout_ms=30_000)
result = await bash.exec("rg -n TODO src | head -20")

print(result.exit_code)
print(result.stdout.decode())
print(result.stderr.decode())
```

## Options

<ParamField path="env" type="Mapping[str, str] | None">
  Environment variables for the shell. Defaults to empty. The host process environment is not inherited.
</ParamField>

<ParamField path="cwd" type="str | None">
  Working directory inside the mount. Defaults to `/`.
</ParamField>

<ParamField path="timeout_ms" type="int | None">
  Per-exec wall-clock timeout in milliseconds. Defaults to 30 seconds.
</ParamField>

## exec()

`exec(commands)` takes one string containing one or more shell statements.

```python theme={null}
result = await bash.exec("""
rg -l integration .
python -m pytest
""")
```

<ParamField path="commands" type="str" required>
  Shell script to execute.
</ParamField>

## Response

`exec(...)` returns `ExecResult`.

<ResponseField name="stdout" type="bytes">
  Standard output bytes.
</ResponseField>

<ResponseField name="stderr" type="bytes">
  Standard error bytes.
</ResponseField>

<ResponseField name="exit_code" type="int">
  Process exit code. `0` indicates success.
</ResponseField>

## Command failures

Command failures usually return a non-zero `exit_code`; they do not automatically raise.

```python theme={null}
result = await bash.exec("cat /acme/app/missing.txt")
if result.exit_code != 0:
    print(result.stderr.decode())
```

Timeouts may surface as either an exception or a non-zero exit depending on where execution is interrupted.

## Binary files

Use `fs.read(...)` for binary files. Text-oriented shell commands such as `cat` are intended for text output.