> ## 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: '/workspace', 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

**env** `Record\<string, string\> | undefined`

Environment variables for the shell. The host process environment is not inherited unless you pass it explicitly.

**cwd** `string | undefined`

Working directory inside the mount. Defaults to `/`.

**executionLimits** `object | undefined`

Limits for command count, loops, output sizes, and related execution safety controls.

**commands** `CommandName[] | undefined`

Restrict available built-in command names.

**customCommands** `Record\<string, CustomCommand\> | undefined`

Register custom command implementations.

**network** `NetworkConfig | undefined`

Enable network commands with explicit URL policy.

**fetch** `SecureFetch | undefined`

Custom secure fetch implementation used by network-enabled commands.

**python** `object | undefined`

Python execution configuration. Disabled by default.

**javascript** `object | undefined`

JavaScript execution configuration. Disabled by default.

**logger** `BashLogger | undefined`

Receives command execution logs.

## 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
`);
```

**command** `string` *required*

Shell script to execute.

## Response

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

**stdout** `string`

Standard output.

**stderr** `string`

Standard error.

**exitCode** `number`

Process exit code. `0` indicates success.

**env** `Record\<string, string\>`

Resulting shell environment when included by `just-bash`.

## Command failures

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

```ts theme={null}
const result = await bash.exec('cat /workspace/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.