shell

The shell namespace — 7 functions.

globals/shell/run

shell.run(command: string) -> ShellResult

Execute a command in the engine's emulated Unix shell and return once it has completed. This is the same shell as the MCP bash tool — 60+ builtins (ls, cat, grep, find, echo, ...) operating on the virtual scene filesystem. A command that runs Luau (run, luau, zm, zero) needs the engine's frame loop, so from a coroutine it is queued to run off the frame loop and this yields until it finishes; everything else runs inline. That queueing runs the whole line, so a line that also ran a command of its own comes back with the explanation in stderr and shell.runAsync as the way to run it whole.

Parameters

• command string — Shell command to execute.

Returns ShellResult — Command result { stdout, stderr, exitCode, ok }.

local r = shell.run("ls /zero/source")

globals/shell/runAsync

shell.runAsync(command: string) -> string

Asynchronous version of shell.run. Returns a promise ID that resolves to a JSON-encoded result string. Use with task.await().

Parameters

• command string — Shell command to execute.

Returns string — Promise ID — pass to task.await() to get the JSON result.

local json = task.await(shell.runAsync("find /zero -name '*.luau'"))

modules/shell/README

require("@builtin/modules/api/engine/shell") -- shell (also available as global 'shell')

Engine emulated Unix shell — same shell that powers the MCP bash tool. Public Luau surface over the __shell Internal FFI namespace.

Usage: local shell = require("@builtin/modules/api/engine/shell") Also available as global: shell

modules/shell/run

run(command: string): ShellResult

Execute a command in the engine's emulated Unix shell and return once it has completed. This is the same shell as the MCP bash tool — 60+ builtins (ls, cat, grep, find, echo, ...) operating on the virtual scene filesystem. A command that runs Luau (run, luau, zm, zero) needs the engine's frame loop, so from a coroutine it is queued to run off the frame loop and this yields until it finishes; everything else runs inline. That queueing runs the whole line, so a line that also ran a command of its own comes back with the explanation in stderr and shell.runAsync as the way to run it whole.

Parameters

• command string — Shell command to execute.

local r = shell.run("ls /zero/source")

modules/shell/runAsync

runAsync(command: string): string

Asynchronous version of shell.run. Returns a promise ID that resolves to a JSON-encoded result string. Use with task.await().

Parameters

• command string — Shell command to execute.

local json = task.await(shell.runAsync("find /zero -name '*.luau'"))

typed/builtin//modules/api/engine/shell/shell/run

shell.run(command: string) -> ShellResult

Execute a command in the engine's emulated Unix shell and return once it has completed. This is the same shell as the MCP bash tool — 60+ builtins (ls, cat, grep, find, echo, ...) operating on the virtual scene filesystem. A command that runs Luau (run, luau, zm, zero) needs the engine's frame loop, so from a coroutine it is queued to run off the frame loop and this yields until it finishes; everything else runs inline. That queueing runs the whole line, so a line that also ran a command of its own comes back with the explanation in stderr and shell.runAsync as the way to run it whole.

Parameters

• command string — Shell command to execute.

Returns ShellResult — Command result { stdout, stderr, exitCode, ok }.

local r = shell.run("ls /zero/source")

typed/builtin//modules/api/engine/shell/shell/runAsync

shell.runAsync(command: string) -> string

Asynchronous version of shell.run. Returns a promise ID that resolves to a JSON-encoded result string. Use with task.await().

Parameters

• command string — Shell command to execute.

Returns string — Promise ID — pass to task.await() to get the JSON result.

local json = task.await(shell.runAsync("find /zero -name '*.luau'"))