Skip to main content

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

​
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. 
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. 
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.