> ## 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 `just-bash` interpreter rooted at the mounted filesystem. Commands run against MesaFS; no host shell is spawned.

```ts theme={null}
const bash = fs.bash({ cwd: '/acme/app', env: { CI: 'true' } });
const result = await bash.exec('rg -n TODO src | head -20');

console.log(result.exitCode);
console.log(result.stdout);
console.log(result.stderr);
```

## Options

<ParamField path="env" type="Record<string, string> | undefined">
  Environment variables for the shell. The host process environment is not inherited unless you pass it explicitly.
</ParamField>

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

<ParamField path="executionLimits" type="object | undefined">
  Limits for command count, loops, output sizes, and related execution safety controls.
</ParamField>

<ParamField path="commands" type="CommandName[] | undefined">
  Restrict available built-in command names.
</ParamField>

<ParamField path="customCommands" type="Record<string, CustomCommand> | undefined">
  Register custom command implementations.
</ParamField>

<ParamField path="network" type="NetworkConfig | undefined">
  Enable network commands with explicit URL policy.
</ParamField>

<ParamField path="fetch" type="SecureFetch | undefined">
  Custom secure fetch implementation used by network-enabled commands.
</ParamField>

<ParamField path="python" type="object | undefined">
  Python execution configuration. Disabled by default.
</ParamField>

<ParamField path="javascript" type="object | undefined">
  JavaScript execution configuration. Disabled by default.
</ParamField>

<ParamField path="logger" type="BashLogger | undefined">
  Receives command execution logs.
</ParamField>

## exec()

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

```ts theme={null}
const result = await bash.exec(`
rg -l integration .
node --test
`);
```

<ParamField path="command" type="string" required>
  Shell script to execute.
</ParamField>

## Response

`exec(...)` returns `ExecResult` from `just-bash`.

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

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

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

<ResponseField name="env" type="Record<string, string>">
  Resulting shell environment when included by `just-bash`.
</ResponseField>

## Command failures

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

```ts theme={null}
const result = await bash.exec('cat /acme/app/missing.txt');
if (result.exitCode !== 0) {
  console.error(result.stderr);
}
```

## Binary files

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